viztracer

Python

VizTracer 1.0.0 Release

下载

可视化追踪器

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

前端 UI 由 Perfetto 提供支持。使用“AWSD”缩放/导航。更多帮助可以在“支持 - 控件”中找到。

示例_img

亮点

时间轴上详细的函数进入/退出信息以及源代码
超级易于使用，大多数功能无需更改源代码，无包依赖性
开销低，可能是市场上最快的跟踪器
支持线程、多处理、子进程、异步和 PyTorch
强大的前端，可流畅渲染GB级trace
适用于 Linux/MacOS/Windows

安装

安装 VizTracer 的首选方式是通过 pip

pip install viztracer

基本用法

命令行

 # Instead of "python3 my_script.py arg1 arg2"
viztracer my_script.py arg1 arg2

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

 # You can display all the files in a directory and open them in browser too
vizviewer ./
# For very large trace files, try external trace processor
vizviewer --use_external_processor result.json

vizviewer 将在http://localhost:9001上托管一个 HTTP 服务器。您还可以打开浏览器并使用该地址。

如果您不希望 vizviewer 自动打开网页浏览器，您可以使用

vizviewer --server_only result.json

如果您只需要调出一次跟踪报告，并且不需要持久服务器，请使用

vizviewer --once result.json

vizviewer result.json

VS Code 扩展可以让您的生活变得更加轻松。

添加--open以在跟踪后立即打开报告

viztracer --open my_script.py arg1 arg2
viztracer -o result.html --open my_script.py arg1 arg2

还支持模块和控制台脚本（如flask ）

viztracer -m your_module

viztracer flask run

排队

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

 from viztracer import VizTracer

tracer = VizTracer ()
tracer . start ()
# Something happens here
tracer . stop ()
tracer . save () # also takes output_file as an optional argument

或者，您可以使用with语句来做到这一点

 with VizTracer ( output_file = "optional.json" ) as tracer :
    # Something happens here

朱皮特

如果您使用 Jupyter，则可以使用 viztracer cell magic。

 # You need to load the extension first
% load_ext viztracer

 % % viztracer
# Your code after

单元格后面将出现一个VizTracer Report按钮，您可以单击它来查看结果

火炬

VizTracer 可以使用--log_torch记录 PyTorch （基于torch.profiler ）的本机调用和 GPU 事件。

 with VizTracer ( log_torch = True ) as tracer :
    # Your torch code

viztracer --log_torch your_model.py

高级用法

微量过滤器

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

最短持续时间
最大堆叠深度
包含文件
排除文件
忽略 C 函数
稀疏日志

无需更改代码即可获得额外日志

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

具有正则表达式的任何变量/属性
函数入口
指定函数中的变量
垃圾收集器操作
函数输入参数
函数返回值
审计事件
引发异常

添加自定义事件

VizTracer 支持在程序运行时插入自定义事件。这就像打印调试一样，但是您可以在查看跟踪数据时知道打印何时发生。

即时事件
可变事件
持续时间事件

杂项

多线程支持

对于Python3.12+，VizTracer支持Python级别的多线程跟踪，无需对代码进行任何修改。

对于3.12之前的版本，VizTracer支持python原生threading模块。只需在创建线程之前启动VizTracer ，它就会正常工作。

对于其他多线程场景，您可以使用enable_thread_tracing()来通知VizTracer有关线程的信息以对其进行跟踪。

示例_img

详细信息请参阅多线程文档

多进程支持

VizTracer 开箱即用地支持subprocess 、 multiprocessing 、 os.fork() 、 concurrent.futures和loky 。

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

示例_img

有关详细信息，请参阅多进程文档

异步支持

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

示例_img

有关详细信息，请参阅异步文档

火焰图

Perfetto 支持原生火焰图，只需在 UI 上选择切片并选择“切片火焰图”即可。

示例_img

远程连接

VizTracer 支持远程连接到任意 Python 进程来跟踪它，只要 viztracer 是可导入的

请参阅远程连接文档

JSON 替代方案

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

表现

VizTracer 投入了大量精力来实现低开销。实际的性能影响很大程度上取决于您的应用程序。对于典型的代码库，开销预计低于 1 倍。如果您的代码不频繁调用函数，则开销可能会很小。

详细解释

VizTracer 引入的开销基本上是函数进入和退出期间的固定时间量，因此函数进入和退出花费的时间越多，观察到的开销就越多。纯递归fib函数在 Python3.11+ 上可能会遭受 3 倍到 4 倍的开销（当优化 Python 调用时，之前的 Python 调用速度较慢，因此开销比率会更少）。

在现实生活中，您的代码不应该在函数调用上花费太多时间（它们实际上并没有做任何有用的事情），因此开销会小得多。

应用了许多技术来最大限度地减少代码执行期间的总体开销，以减少 VizTracer 引入的不可避免的偏差（报告保存部分并不那么重要）。例如，VizTracer 尝试使用 CPU 时间戳计数器而不是系统调用来获取可用时间。在 Python 3.12+ 上，VizTracer 使用sys.monitoring ，其开销比sys.setprofile更少。所有这些努力都使其明显比 Python stdlib 分析器cProfile更快。

然而，VizTracer 是一个跟踪器，这意味着它必须记录每个函数的进入和退出，因此它不能像采样分析器一样快 - 它们不是同一件事。由于额外的开销，VizTracer 提供了比普通采样分析器更多的信息。