PublicArchive/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-07-25 11:22:45 -04:00
Code Issues Packages Projects Releases Wiki Activity

[3.15] gh-151213: Document asyncio debugging tools (GH-151392) (#153370)

Browse Source 
gh-151213: Document asyncio debugging tools (GH-151392)
(cherry picked from commit b2d8db1ac8)

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
This commit is contained in:
Miss Islington (bot)
2026-07-09 01:25:18 +02:00
committed by GitHub
parent cbbccf37b2
commit c512e8f0fb
3 changed files with 177 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/library/asyncio-graph.rst
+7 -1
View File
@@ -4,7 +4,7 @@
.. _asyncio-graph:
========================
Call Graph Introspection
Call graph introspection
========================
**Source code:** :source:`Lib/asyncio/graph.py`
@@ -17,6 +17,12 @@ a suspended *future*. These utilities and the underlying machinery
can be used from within a Python program or by external profilers
and debuggers.
.. seealso::
:ref:`asyncio-introspection-tools`
Command-line tools for inspecting tasks in another running Python
process.
.. versionadded:: 3.14
Doc/library/asyncio-tools.rst
+157
View File
@@ -0,0 +1,157 @@
.. currentmodule:: asyncio
.. _asyncio-introspection-tools:
================================
Command-line introspection tools
================================
**Source code:** :source:`Lib/asyncio/tools.py`
-------------------------------------
The :mod:`!asyncio` module can be invoked as a script via ``python -m
asyncio`` to inspect the task graph of another running Python process without
modifying it or restarting it. The :mod:`!asyncio.tools` submodule implements
this interface.
The following commands inspect the process identified by ``PID``:
.. code-block:: shell-session
$ python -m asyncio pstree [--retries N] PID
$ python -m asyncio ps [--retries N] PID
The commands read the target process state without executing any code in it.
They are only available on supported platforms and may require permission to
inspect another process. See the :ref:`permission-requirements <permission-requirements>` for details.
.. seealso::
:ref:`asyncio-graph`
Programmatic APIs for inspecting the async call graph of a task or
future in the current process.
The command examples below use this program, which creates a task hierarchy
suitable for inspection and prints its process ID:
.. code-block:: python
:caption: example.py
import asyncio
import os
async def play(track):
await asyncio.sleep(3600)
print(f"🎵 Finished: {track}")
async def album(name, tracks):
async with asyncio.TaskGroup() as tg:
for track in tracks:
tg.create_task(play(track), name=track)
async def main():
print(f"PID: {os.getpid()}")
async with asyncio.TaskGroup() as tg:
tg.create_task(
album("Sundowning", ["TNDNBTG", "Levitate"]),
name="Sundowning",
)
tg.create_task(
album("TMBTE", ["DYWTYLM", "Aqua Regia"]),
name="TMBTE",
)
asyncio.run(main())
Run the program in one terminal and leave it running:
.. code-block:: shell-session
$ python example.py
PID: 12345
Then pass the printed process ID to the commands from another terminal.
Thread IDs, task IDs, file paths, and line numbers vary between runs and
source layouts.
.. versionadded:: 3.14
Command-line options
====================
.. option:: pstree PID
Display task and coroutine relationships as a tree. Each task is shown
with its full coroutine stack, nested under the task (if any) that is
awaiting it. This subcommand is useful for quickly identifying which branch
of a task hierarchy is blocked and where in its coroutine stack execution
has paused:
.. code-block:: shell-session
$ python -m asyncio pstree 12345
└── (T) Task-1
└── main example.py:12
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:75
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:124
├── (T) Sundowning
│ └── album example.py:7
│ └── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:75
│ └── TaskGroup._aexit Lib/asyncio/taskgroups.py:124
│ ├── (T) TNDNBTG
│ │ └── play example.py:4
│ │ └── sleep Lib/asyncio/tasks.py:702
│ └── (T) Levitate
│ └── play example.py:4
│ └── sleep Lib/asyncio/tasks.py:702
└── (T) TMBTE
└── album example.py:7
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:75
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:124
├── (T) DYWTYLM
│ └── play example.py:4
│ └── sleep Lib/asyncio/tasks.py:702
└── (T) Aqua Regia
└── play example.py:4
└── sleep Lib/asyncio/tasks.py:702
If the await graph contains a cycle, ``pstree`` reports an error instead
of printing a tree. A cycle in the await graph is unusual and typically
indicates a programming error:
.. code-block:: shell-session
$ python -m asyncio pstree 12345
ERROR: await-graph contains cycles - cannot print a tree!
cycle: Task-2 → Task-3 → Task-2
.. option:: ps PID
Display a flat table of all pending tasks in the process *PID*. Each row
shows the event-loop thread ID, task ID and name, coroutine stack, and the
awaiting task's stack, name, and ID, if any.
This subcommand prints all tasks regardless of whether the await graph
contains cycles:
.. code-block:: shell-session
$ python -m asyncio ps 12345
tid task id task name coroutine stack awaiter chain awaiter name awaiter id
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
18445801 0x10a456060 Task-1 TaskGroup._aexit -> TaskGroup.__aexit__ -> main 0x0
18445801 0x10a439f60 Sundowning TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x10a456060
18445801 0x10a439d70 TMBTE TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x10a456060
18445801 0x10a2a3a80 TNDNBTG sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x10a439f60
18445801 0x10a2a38a0 Levitate sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x10a439f60
18445801 0x10a2d7150 DYWTYLM sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x10a439d70
18445801 0x10a6bdaa0 Aqua Regia sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x10a439d70
.. option:: --retries N
Retry failed attempts to inspect the target process up to *N* times. This
can help when the target process changes while its state is being read.
.. versionadded:: 3.15
Doc/library/asyncio.rst
+13
View File
@@ -47,6 +47,13 @@ asyncio provides a set of **high-level** APIs to:
* :ref:`synchronize <asyncio-sync>` concurrent code;
For **introspection**, asyncio provides APIs and tools for:
* inspecting the :ref:`async call graph <asyncio-graph>` of tasks and futures;
* inspecting tasks in another running Python process with
:ref:`command-line tools <asyncio-introspection-tools>`;
Additionally, there are **low-level** APIs for
*library and framework developers* to:
@@ -108,7 +115,13 @@ for full functionality and the latest features.
asyncio-subprocess.rst
asyncio-queue.rst
asyncio-exceptions.rst
.. toctree::
:caption: Introspection APIs
:maxdepth: 1
asyncio-graph.rst
asyncio-tools.rst
.. toctree::
:caption: Low-level APIs