Call Graph Introspection

Source code:Lib/asyncio/graph.py

asyncio has powerful runtime call graph introspection utilitiesto trace the entire call graph of a runningcoroutine ortask, ora suspendedfuture. These utilities and the underlying machinerycan be used from within a Python program or by external profilersand debuggers.

Added in version 3.14.

asyncio.print_call_graph(future=None,/,*,file=None,depth=1,limit=None)

Print the async call graph for the current task or the providedTask orFuture.

This function prints entries starting from the top frame and goingdown towards the invocation point.

The function receives an optionalfuture argument.If not passed, the current running task will be used.

If the function is called onthe current task, the optionalkeyword-onlydepth argument can be used to skip the specifiednumber of frames from top of the stack.

If the optional keyword-onlylimit argument is provided, each call stackin the resulting graph is truncated to include at mostabs(limit)entries. Iflimit is positive, the entries left are the closest tothe invocation point. Iflimit is negative, the topmost entries areleft. Iflimit is omitted orNone, all entries are present.Iflimit is0, the call stack is not printed at all, only“awaited by” information is printed.

Iffile is omitted orNone, the function will printtosys.stdout.

Example:

The following Python code:

importasyncioasyncdeftest():asyncio.print_call_graph()asyncdefmain():asyncwithasyncio.TaskGroup()asg:g.create_task(test(),name='test')asyncio.run(main())

will print:

*Task(name='test',id=0x1039f0fe0)+Callstack:|File't2.py',line4,inasynctest()+Awaitedby:*Task(name='Task-1',id=0x103a5e060)+Callstack:|File'taskgroups.py',line107,inasyncTaskGroup.__aexit__()|File't2.py',line7,inasyncmain()
asyncio.format_call_graph(future=None,/,*,depth=1,limit=None)

Likeprint_call_graph(), but returns a string.Iffuture isNone and there’s no current task,the function returns an empty string.

asyncio.capture_call_graph(future=None,/,*,depth=1,limit=None)

Capture the async call graph for the current task or the providedTask orFuture.

The function receives an optionalfuture argument.If not passed, the current running task will be used. If there’s nocurrent task, the function returnsNone.

If the function is called onthe current task, the optionalkeyword-onlydepth argument can be used to skip the specifiednumber of frames from top of the stack.

Returns aFutureCallGraph data class object:

  • FutureCallGraph(future,call_stack,awaited_by)

    Wherefuture is a reference to aFuture oraTask (or their subclasses.)

    call_stack is a tuple ofFrameCallGraphEntry objects.

    awaited_by is a tuple ofFutureCallGraph objects.

  • FrameCallGraphEntry(frame)

    Whereframe is a frame object of a regular Python functionin the call stack.

Low level utility functions

To introspect an async call graph asyncio requires cooperation fromcontrol flow structures, such asshield() orTaskGroup.Any time an intermediateFuture object with low-level APIs likeFuture.add_done_callback() isinvolved, the following two functions should be used to inform asyncioabout how exactly such intermediate future objects are connected withthe tasks they wrap or control.

asyncio.future_add_to_awaited_by(future,waiter,/)

Record thatfuture is awaited on bywaiter.

Bothfuture andwaiter must be instances ofFuture orTask or their subclasses,otherwise the call would have no effect.

A call tofuture_add_to_awaited_by() must be followed by aneventual call to thefuture_discard_from_awaited_by() functionwith the same arguments.

asyncio.future_discard_from_awaited_by(future,waiter,/)

Record thatfuture is no longer awaited on bywaiter.

Bothfuture andwaiter must be instances ofFuture orTask or their subclasses, otherwisethe call would have no effect.