Python / 系统课时
asyncio 调试模式怎么开
asyncio 调试模式怎么开
异步服务出现“偶尔卡住、任务没报错却不继续、某段协程特别慢”时,普通日志往往只看到结果,看不到事件循环内部信号。开启 asyncio 调试模式后,可以直接暴露慢回调、未等待协程等问题,再用较小范围的代码定位阻塞点。
学习目标
- 掌握开启 asyncio 调试模式的三种常用方式。
- 会设置慢回调阈值并读懂关键调试日志。
- 知道调试模式适合在什么环境开启,以及如何避免把正常慢 I/O 误判为事件循环阻塞。
打开调试模式
最直接的方式是在 asyncio.run() 中传入 debug=True。如果程序不是由 asyncio.run() 统一创建事件循环,也可以拿到当前 loop 后调用 loop.set_debug(True)。启动阶段还可以使用环境变量 PYTHONASYNCIODEBUG=1,开发机也可用 python -X dev app.py 打开 Python Development Mode。
下面用一个故意写错的处理函数制造事件循环阻塞。time.sleep() 会占住事件循环线程,因此适合验证慢回调检测是否真正生效。
import asyncio
import logging
import time
logging.basicConfig(level=logging.DEBUG)
async def blocking_handler() -> None:
print("handler started")
# 故意使用阻塞睡眠,模拟协程里混入同步耗时调用。
time.sleep(0.05)
print("handler finished")
async def main() -> None:
loop = asyncio.get_running_loop()
# 把阈值降到 10 ms,便于在本地快速观察慢执行告警。
loop.slow_callback_duration = 0.01
await blocking_handler()
if __name__ == "__main__":
asyncio.run(main(), debug=True)预期输出
handler started
handler finished标准输出至少包含上面两行;stderr 的 asyncio 日志还会出现包含 Executing 和 took <TIME> seconds 的慢执行警告。任务描述、源文件位置和实际耗时会随 Python 版本与机器变化,因此应关注“哪个 Task 或 callback 超过阈值”,不要依赖整行文本完全一致。
用慢回调阈值缩小范围
调试模式下,事件循环会记录执行时间超过 loop.slow_callback_duration 的 callback 或 Task step。默认阈值通常是 0.1 秒;排查偶发抖动时,可以暂时降到 0.01~0.05 秒,但阈值越低,日志越多。
慢回调日志说明的是“事件循环线程长时间没有把控制权交还给 loop”,常见原因包括同步文件操作、同步数据库客户端、time.sleep()、大块 JSON 编解码以及纯 Python CPU 计算。它不等价于“某个网络请求本身很慢”:正常的 await 网络等待会把控制权交回事件循环,不会因为等待 500 ms 就自动成为慢回调。
读懂调试信号
调试模式最有价值的不是日志数量,而是能把几类常见错误变成更明确的信号:
- 慢 callback 或 Task step:优先检查协程内部是否执行了同步阻塞或重 CPU 工作。
- “coroutine was never awaited”:通常表示调用异步函数后忘了
await,或者没有用create_task()安排执行。 - 非线程安全 API 被错误线程调用:调试模式更容易直接暴露线程边界问题。
- 未正确处理的 Task 异常:结合 Task 创建位置,可以反查“任务从哪里启动、为什么没人消费异常”。
看到慢执行日志后,先定位具体协程,再在可疑代码段前后记录 time.perf_counter()。如果耗时集中在同步函数,应改成真正的异步 API;纯 Python CPU 计算应考虑进程池;阻塞 I/O 可考虑线程池或替换为异步客户端。
调试模式什么时候关闭
调试模式适合本地开发、压测复现和短时线上诊断,不建议默认长期全量开启。它会执行额外检查并输出更多日志,性能特征与正常模式并不完全相同。
修复后应恢复合理的 slow_callback_duration,关闭全局 debug,再用同样的请求和并发条件复测延迟、吞吐和错误率。若关闭调试后问题仍消失,说明还需要检查日志量、探针或测试代码本身是否改变了时序。