Skip to content

Commit b2d8db1

Browse files
johnslavikjohnslavik
authored
gh-151213: Document asyncio debugging tools (#151392)
1 parent 0c6422f commit b2d8db1

3 files changed

Lines changed: 177 additions & 1 deletion

File tree

‎Doc/library/asyncio-graph.rst‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
.. _asyncio-graph:
55

66
========================
7-
Call Graph Introspection
7+
Call graph introspection
88
========================
99

1010
**Source code:** :source:`Lib/asyncio/graph.py`
@@ -17,6 +17,12 @@ a suspended *future*. These utilities and the underlying machinery
1717
can be used from within a Python program or by external profilers
1818
and debuggers.
1919

20+
.. seealso::
21+
22+
:ref:`asyncio-introspection-tools`
23+
Command-line tools for inspecting tasks in another running Python
24+
process.
25+
2026
.. versionadded:: 3.14
2127

2228

‎Doc/library/asyncio-tools.rst‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
.. currentmodule:: asyncio
2+
3+
.. _asyncio-introspection-tools:
4+
5+
================================
6+
Command-line introspection tools
7+
================================
8+
9+
**Source code:** :source:`Lib/asyncio/tools.py`
10+
11+
-------------------------------------
12+
13+
The :mod:`!asyncio` module can be invoked as a script via ``python -m
14+
asyncio`` to inspect the task graph of another running Python process without
15+
modifying it or restarting it. The :mod:`!asyncio.tools` submodule implements
16+
this interface.
17+
18+
The following commands inspect the process identified by ``PID``:
19+
20+
.. code-block:: shell-session
21+
22+
$ python -m asyncio pstree [--retries N] PID
23+
$ python -m asyncio ps [--retries N] PID
24+
25+
The commands read the target process state without executing any code in it.
26+
They are only available on supported platforms and may require permission to
27+
inspect another process. See the :ref:`permission-requirements <permission-requirements>` for details.
28+
29+
.. seealso::
30+
31+
:ref:`asyncio-graph`
32+
Programmatic APIs for inspecting the async call graph of a task or
33+
future in the current process.
34+
35+
The command examples below use this program, which creates a task hierarchy
36+
suitable for inspection and prints its process ID:
37+
38+
.. code-block:: python
39+
:caption: example.py
40+
41+
import asyncio
42+
import os
43+
44+
async def play(track):
45+
await asyncio.sleep(3600)
46+
print(f"🎵 Finished: {track}")
47+
48+
async def album(name, tracks):
49+
async with asyncio.TaskGroup() as tg:
50+
for track in tracks:
51+
tg.create_task(play(track), name=track)
52+
53+
async def main():
54+
print(f"PID: {os.getpid()}")
55+
async with asyncio.TaskGroup() as tg:
56+
tg.create_task(
57+
album("Sundowning", ["TNDNBTG", "Levitate"]),
58+
name="Sundowning",
59+
)
60+
tg.create_task(
61+
album("TMBTE", ["DYWTYLM", "Aqua Regia"]),
62+
name="TMBTE",
63+
)
64+
65+
asyncio.run(main())
66+
67+
Run the program in one terminal and leave it running:
68+
69+
.. code-block:: shell-session
70+
71+
$ python example.py
72+
PID: 12345
73+
74+
Then pass the printed process ID to the commands from another terminal.
75+
Thread IDs, task IDs, file paths, and line numbers vary between runs and
76+
source layouts.
77+
78+
.. versionadded:: 3.14
79+
80+
Command-line options
81+
====================
82+
83+
.. option:: pstree PID
84+
85+
Display task and coroutine relationships as a tree. Each task is shown
86+
with its full coroutine stack, nested under the task (if any) that is
87+
awaiting it. This subcommand is useful for quickly identifying which branch
88+
of a task hierarchy is blocked and where in its coroutine stack execution
89+
has paused:
90+
91+
.. code-block:: shell-session
92+
93+
$ python -m asyncio pstree 12345
94+
└── (T) Task-1
95+
└── main example.py:12
96+
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:75
97+
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:124
98+
├── (T) Sundowning
99+
│ └── album example.py:7
100+
│ └── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:75
101+
│ └── TaskGroup._aexit Lib/asyncio/taskgroups.py:124
102+
│ ├── (T) TNDNBTG
103+
│ │ └── play example.py:4
104+
│ │ └── sleep Lib/asyncio/tasks.py:702
105+
│ └── (T) Levitate
106+
│ └── play example.py:4
107+
│ └── sleep Lib/asyncio/tasks.py:702
108+
└── (T) TMBTE
109+
└── album example.py:7
110+
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:75
111+
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:124
112+
├── (T) DYWTYLM
113+
│ └── play example.py:4
114+
│ └── sleep Lib/asyncio/tasks.py:702
115+
└── (T) Aqua Regia
116+
└── play example.py:4
117+
└── sleep Lib/asyncio/tasks.py:702
118+
119+
If the await graph contains a cycle, ``pstree`` reports an error instead
120+
of printing a tree. A cycle in the await graph is unusual and typically
121+
indicates a programming error:
122+
123+
.. code-block:: shell-session
124+
125+
$ python -m asyncio pstree 12345
126+
ERROR: await-graph contains cycles - cannot print a tree!
127+
128+
cycle: Task-2 → Task-3 → Task-2
129+
130+
.. option:: ps PID
131+
132+
Display a flat table of all pending tasks in the process *PID*. Each row
133+
shows the event-loop thread ID, task ID and name, coroutine stack, and the
134+
awaiting task's stack, name, and ID, if any.
135+
136+
This subcommand prints all tasks regardless of whether the await graph
137+
contains cycles:
138+
139+
.. code-block:: shell-session
140+
141+
$ python -m asyncio ps 12345
142+
tid task id task name coroutine stack awaiter chain awaiter name awaiter id
143+
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
144+
18445801 0x10a456060 Task-1 TaskGroup._aexit -> TaskGroup.__aexit__ -> main 0x0
145+
18445801 0x10a439f60 Sundowning TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x10a456060
146+
18445801 0x10a439d70 TMBTE TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x10a456060
147+
18445801 0x10a2a3a80 TNDNBTG sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x10a439f60
148+
18445801 0x10a2a38a0 Levitate sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x10a439f60
149+
18445801 0x10a2d7150 DYWTYLM sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x10a439d70
150+
18445801 0x10a6bdaa0 Aqua Regia sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x10a439d70
151+
152+
.. option:: --retries N
153+
154+
Retry failed attempts to inspect the target process up to *N* times. This
155+
can help when the target process changes while its state is being read.
156+
157+
.. versionadded:: 3.15

‎Doc/library/asyncio.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,13 @@ asyncio provides a set of **high-level** APIs to:
4747

4848
* :ref:`synchronize <asyncio-sync>` concurrent code;
4949

50+
For **introspection**, asyncio provides APIs and tools for:
51+
52+
* inspecting the :ref:`async call graph <asyncio-graph>` of tasks and futures;
53+
54+
* inspecting tasks in another running Python process with
55+
:ref:`command-line tools <asyncio-introspection-tools>`;
56+
5057
Additionally, there are **low-level** APIs for
5158
*library and framework developers* to:
5259

@@ -108,7 +115,13 @@ for full functionality and the latest features.
108115
asyncio-subprocess.rst
109116
asyncio-queue.rst
110117
asyncio-exceptions.rst
118+
119+
.. toctree::
120+
:caption: Introspection APIs
121+
:maxdepth: 1
122+
111123
asyncio-graph.rst
124+
asyncio-tools.rst
112125

113126
.. toctree::
114127
:caption: Low-level APIs

0 commit comments

Comments
 (0)