VizTracer

VizTracer 是一个低开销的日志记录/调试/性能分析工具，可以跟踪和可视化您的 Python 代码执行。

前端 UI 由 Perfetto 驱动。使用"AWSD"进行缩放/导航。更多帮助可以在"支持 - 控制"中找到。

亮点

时间线上详细的函数进入/退出信息，附带源代码
使用超级简单，大多数功能无需更改源代码，无包依赖
支持线程、多进程、子进程和异步
强大的前端，能够流畅渲染 GB 级别的跟踪数据
适用于 Linux/MacOS/Windows

安装

推荐通过 pip 安装 VizTracer

pip install viztracer

基本用法

命令行

假设您有一个要运行的 Python 脚本：

python3 my_script.py arg1 arg2

您可以简单地使用 VizTracer：

viztracer my_script.py arg1 arg2

将生成一个 result.json 文件，您可以使用 vizviewer 打开它

vizviewer result.json
# 您也可以显示目录中的所有文件并在浏览器中打开它们
vizviewer ./
# 对于非常大的跟踪文件，请尝试使用外部跟踪处理器
vizviewer --use_external_processor result.json

VS Code 扩展可以让您的使用更加便捷。

内联

您也可以在脚本中手动启动/停止 VizTracer。

from viztracer import VizTracer

tracer = VizTracer()
tracer.start()
# 这里发生一些事情
tracer.stop()
tracer.save() # 也可以接受 output_file 作为可选参数

或者，您可以使用 with 语句

with VizTracer(output_file="optional.json") as tracer:
    # 这里发生一些事情

Jupyter

如果您使用 Jupyter，可以使用 viztracer 单元格魔法。

# 首先需要加载扩展
%load_ext viztracer

%%viztracer
# 之后是您的代码

单元格执行后会出现一个 "VizTracer Report" 按钮，您可以点击它查看结果

高级用法

跟踪过滤器

VizTracer 可以过滤掉您不需要的数据，以减少开销并在转储日志之前保留更长时间段的信息。

无需更改代码的额外日志

VizTracer 可以在不更改源代码的情况下记录额外信息

添加自定义事件

VizTracer 支持在程序运行时插入自定义事件。这类似于打印调试，但您可以在查看跟踪数据时知道这个打印发生的时间。

其他

多线程支持

VizTracer 支持 Python 原生的 threading 模块，无需对代码进行任何修改。只需在创建线程之前启动 VizTracer，它就会正常工作。对于其他多线程场景，您可以使用 enable_thread_tracing() 来通知 VizTracer 需要追踪的线程。

详情请参阅多线程文档

多进程支持

VizTracer 原生支持 subprocess、multiprocessing、os.fork()、concurrent.futures 和 loky。

对于更一般的多进程情况，VizTracer 可以通过一些额外步骤来支持。

详情请参阅多进程文档

异步支持

VizTracer 原生支持 asyncio，但可以通过使用 --log_async 来增强报告。

详情请参阅异步文档

火焰图

VizTracer 可以显示追踪数据的火焰图。

vizviewer --flamegraph result.json

远程附加

只要可以导入 viztracer，VizTracer 就支持远程附加到任意 Python 进程来追踪它。

详情请参阅远程附加文档

JSON 替代方案

VizTracer 需要将内部数据转储为 json 格式。建议用户安装 orjson，它比内置的 json 库快得多。VizTracer 会尝试导入 orjson，如果 orjson 不存在，则会回退到内置的 json 库。

性能

在最坏情况下，VizTracer 会引入 2 到 3 倍的开销。如果函数调用较少或正确应用了过滤器，开销会好得多。

<details> <summary> 在 Github VM 上使用 Python 3.8 / Ubuntu 18.04.4 运行 test_performance 的示例 </summary>

fib:
0.000678067(1.00)[origin]
0.019880272(29.32)[py] 0.011103901(16.38)[parse] 0.021165599(31.21)[json]
0.001344933(1.98)[c] 0.008181911(12.07)[parse] 0.015789866(23.29)[json]
0.001472846(2.17)[cProfile]

hanoi     (6148, 4100):
0.000550255(1.00)[origin]
0.016343521(29.70)[py] 0.007299123(13.26)[parse] 0.016779364(30.49)[json]
0.001062505(1.93)[c] 0.006416136(11.66)[parse] 0.011463236(20.83)[json]
0.001144914(2.08)[cProfile]

qsort     (8289, 5377):
0.002817679(1.00)[origin]
0.052747431(18.72)[py] 0.011339725(4.02)[parse] 0.023644345(8.39)[json]
0.004767673(1.69)[c] 0.008735166(3.10)[parse] 0.017173703(6.09)[json]
0.007248019(2.57)[cProfile]

slow_fib  (1135, 758):
0.028759652(1.00)[origin]
0.033994071(1.18)[py] 0.001630461(0.06)[parse] 0.003386635(0.12)[json]
0.029481623(1.03)[c] 0.001152415(0.04)[parse] 0.002191417(0.08)[json]
0.028289305(0.98)[cProfile]