Python 3.14 asyncio pstree 如何定位未结束任务

Python 3.14 的 asyncio 新增了命令行任务检查工具。服务卡住时，先拿到目标进程的 PID，再执行 python -m asyncio pstree PID，就能从任务父子关系和 coroutine stack 里找出仍停在 await 链上的分支。这个命令读取目标进程状态，不需要修改代码或重启服务；但它需要运行平台支持，并可能受进程检查权限限制。

先让任务树成为可读的排障证据

如果所有任务都使用默认名称，树上只能看到一串抽象编号。排查前可以在复现环境给任务命名，并保留一个明确的等待点。下面的例子只用于说明任务关系，不需要在生产进程里额外注入调试代码。

import asyncio
import os

async def worker(name):
    # 长时间等待用于保留可观察的挂起协程，业务中可替换为网络 I/O。
    await asyncio.sleep(3600)

async def main():
    # TaskGroup 让父任务和两个业务分支在任务树中保持清晰关系。
    async with asyncio.TaskGroup() as group:
        group.create_task(worker("sync-orders"), name="sync-orders")
        group.create_task(worker("refresh-cache"), name="refresh-cache")

if __name__ == "__main__":
    # 打印 PID，便于在另一个终端执行 pstree 或 ps。
    print(f"PID: {os.getpid()}")
    asyncio.run(main())

启动后记下打印的 PID。示例里的 TaskGroup、sync-orders、refresh-cache、worker 和 asyncio.sleep 都是之后解释树形输出的定位锚点。真实服务也应优先使用能表达业务含义的任务名。

用 pstree 沿着父子关系找未结束分支

在另一个终端执行：

# 用目标 Python 进程的 PID 查看任务树，不要把 PID 写成启动命令的进程组编号。
python -m asyncio pstree 12345

pstree 会把 task 和 coroutine 的关系显示成树：某个任务下面嵌套它正在等待的协程栈，TaskGroup 创建的子任务会落在对应父分支下。阅读时先从根任务向下走，再看每个叶子停在什么函数；如果叶子落在 worker 的等待点，说明这条分支当前仍未完成，下一步应检查它等待的外部 I/O、队列、锁或超时策略。

不要把树上的层级直接当成执行先后。它表达的是当前 await 关系，而不是时间线；同一层的任务可能由事件循环交替推进。图中看见 asyncio.sleep 也只能说明协程停在该等待点，不能单凭这一点断定系统故障。

pstree 与 ps 怎么分工

任务树适合回答“哪个父任务下面挂着这条未完成分支”，但它有一个明确边界：如果 await graph 存在循环，pstree 无法打印树，会返回循环错误。此时改用平面列表：

# 树形关系无法展开时，列出目标进程中所有 pending task 做横向比较。
python -m asyncio ps 12345

ps 会给出事件循环线程、任务 ID、任务名、coroutine stack，以及存在时的 awaiter 信息。它不依赖树能否展开，因此适合确认是否还有任务、比较多个任务停留位置，或保留循环依赖的现场。两条命令只观察目标状态，不会替你取消任务、释放锁或修复业务逻辑。

一份不改动目标进程的检查清单

1. 确认目标确实使用 Python 3.14 或更高版本，并取得正确 PID。
2. 优先执行 pstree PID，沿根任务、TaskGroup、业务任务和 coroutine stack 向下记录停留点。
3. 看到 worker 或其他业务协程时，回到对应 I/O、队列、锁和超时配置核对，不把等待本身当作根因。
4. 遇到循环错误或需要全量比较时执行 ps PID，保存任务名、任务 ID 和 awaiter 链。
5. 若读取失败，检查操作系统支持与权限；工具能看到的是运行时现场，不是完整的业务因果链。

这套方法的价值在于先缩小观察范围：先判断未完成任务属于哪个分支，再决定查外部依赖、取消传播还是资源释放。它不会自动修复 asyncio 服务，但能把“程序卡住了”变成一组可复查的任务关系证据。

相关问题

Python 3.13 能直接使用 asyncio pstree 吗？

不能按本文命令假定可用。官方文档将命令行 introspection tools 标记为 Python 3.14 新增能力，旧版本应使用已有的应用内调试手段或升级后再采集。

pstree 会修改正在运行的服务吗？

官方说明是读取目标进程状态，不在目标进程中执行代码；不过能否读取仍取决于平台和进程检查权限。

为什么 pstree 失败后要换 ps？

await 图出现循环时没有合法的树形展开结果，ps 仍能按平面表列出 pending task，便于先确认循环涉及哪些任务。