Python 3.14 asyncio 调试调用图如何定位悬挂任务：print_call_graph、TaskGroup 与取消状态核对

服务没有报错，却一直等不到结果，asyncio 程序里最难查的往往不是异常，而是某个任务停在了不该停的位置。Python 3.14 新增的 asyncio.print_call_graph() 可以把当前任务或指定任务的调用栈、等待关系打印出来，配合 TaskGroup 和取消状态，就能把“像挂住了”变成一条可以核对的等待链。

先用调用图确认任务究竟在等待谁，再检查 CancelledError 是否被吞掉；不要一看到超时就盲目加大等待时间。

先确认 Python 3.14 的新观察入口

调用图接口属于 Python 3.14 的 asyncio 能力，常用的三个函数分别是 asyncio.print_call_graph()、asyncio.format_call_graph() 和 asyncio.capture_call_graph()。前者直接输出文本，后两者更适合把结果交给日志或调试工具。

本文只讨论当前进程中的任务观察。Python 官方文档还提供了 python -m asyncio ps PID 和 python -m asyncio pstree PID 这类命令行检查方式，但它们依赖目标进程和平台权限，不应和应用内调用图混为一谈。

TaskGroup 里的任务为什么像挂住了

先准备一个足够小的任务层次：main() 创建 TaskGroup，组内启动 task_group_job()，任务再等待一个没有及时完成的 Future。排查重点不是把代码改得更复杂，而是保留任务名字和等待边界。

import asyncio

async def task_group_job(waiter):
    await waiter

async def main(waiter):
    async with asyncio.TaskGroup() as TaskGroup:
        TaskGroup.create_task(task_group_job(waiter), name="task_group_job")

asyncio.run(main(waiter))

这里的 TaskGroup 会在上下文退出时等待组内任务。只要 task_group_job 一直没有完成，外层就会保持等待。这样的现象不能直接证明是死锁，也可能只是 Future 没有结果、网络依赖迟迟不返回，或者清理代码截断了取消信号。

后面用 asyncio.print_call_graph 观察这条等待链时，仍然要把 TaskGroup 和 task_group_job 当作同一条真实调用关系来核对。

先给任务命名，再把 waiter 的创建位置记下来，后面看到调用图时才知道哪一段是业务等待，哪一段是 TaskGroup 的管理等待。

用 print_call_graph 把等待链展开

在仍处于运行状态的任务里调用 asyncio.print_call_graph()，可以从当前任务向下打印调用栈，并显示谁在等待它。若要观察指定任务，可以把 Task 或 Future 作为位置参数传入；depth 控制当前任务顶部栈帧的跳过层数，limit 控制每条调用栈保留的层数。

async def inspect_task(task):
    asyncio.print_call_graph(task, limit=4)

async def main(waiter):
    async with asyncio.TaskGroup() as TaskGroup:
        task = TaskGroup.create_task(task_group_job(waiter), name="task_group_job")
        await asyncio.sleep(0)
        await inspect_task(task)

这次核对要看三件事：图上是否出现 task_group_job，它的调用栈是否停在 await waiter，以及 TaskGroup 是否出现在“Awaited by”关系中。三者同时出现，才说明任务确实卡在已知等待点；如果任务根本不在图里，应先检查任务是否已完成或引用是否已经丢失。

format_call_graph() 适合把同一份信息写进日志，capture_call_graph() 则返回包含 future、call_stack 和 awaited_by 的数据对象。不要把调用图当作性能基准，它记录的是观察时刻的关系，不是耗时统计。

CancelledError 不能被吞掉

TaskGroup 和 asyncio.timeout() 都会使用取消机制。任务收到取消请求后，asyncio.CancelledError 会在下一次合适的等待点抛出。清理资源时可以捕获它，但清理结束后通常应继续抛出，否则外层的 TaskGroup 可能误以为任务正常完成。

从 asyncio.run 进入的主任务也要沿着这条边界观察，不能只在子任务里打印状态。

async def task_group_job(waiter):
    try:
        await waiter
    except asyncio.CancelledError:
        close_local_resource()
        raise

async def main(waiter):
    async with asyncio.TaskGroup() as TaskGroup:
        TaskGroup.create_task(task_group_job(waiter), name="task_group_job")
        await asyncio.sleep(0)
        # 发生异常或外部取消后，TaskGroup 会取消其余任务

current = asyncio.current_task()
if current is not None:
    print(current.cancelling())

Task.cancelling() 返回当前任务收到的取消请求计数。它不是“任务是否卡住”的直接指标，但能帮助确认取消请求有没有传到正确的边界。Python 3.14 文档也强调，TaskGroup 会保留这个取消计数；如果业务代码无意中吞掉 CancelledError，调用图和取消计数就可能给出互相矛盾的线索。

从日志到修复的复查清单

1. 确认运行环境是 Python 3.14，并记录任务名称、Future 创建点和调用图采集时间。
2. 用 asyncio.print_call_graph(task, limit=4) 查看任务当前栈，重点核对真正停留的 await。
3. 沿 “Awaited by” 关系向上检查是谁在等这个任务，区分业务 Future、TaskGroup 管理和超时包装。
4. 在取消路径中保留 try/finally 清理；若捕获 asyncio.CancelledError，清理后继续抛出。
5. 修复后重新采集调用图，并确认任务完成、TaskGroup 正常退出，且 Task.cancelling() 的变化符合预期。

如果调用图只显示任务仍在等待，而没有告诉你 Future 为什么没有完成，就继续回到 Future 的生产者、超时边界和资源释放日志。调用图解决的是“停在哪里、谁在等谁”，不会替代网络、数据库或文件系统依赖的健康检查。

常见问题

print_call_graph() 能查看已经完成的任务吗？

可以传入已经完成的 Task 或 Future，但看到的调用栈信息会受任务生命周期影响。排查悬挂任务时，应在任务仍等待时采集。

为什么调用图里没有业务函数？

可能是任务已经完成、调用图深度被限制，或者中间 Future 没有正确建立等待关系。先提高 limit，再检查任务引用和等待对象。

捕获 CancelledError 后一定要重新抛出吗？

如果只是做清理，通常应该重新抛出；只有确实要抑制取消时，才需要同时正确处理取消状态，不能把异常静默吞掉。

总结

Python 3.14 的 asyncio 调用图把任务排查从猜测推进到证据核对：先定位任务，再沿调用栈和 “Awaited by” 找到等待边界，最后用 CancelledError 和取消计数复查退出路径。对 TaskGroup 来说，清楚地传递取消信号比单纯增加超时更可靠。