从安装到可视化：VizTracer快速上手完全指南
项目地址: https://gitcode.com/gh_mirrors/vi/viztracer VizTracer是一款低开销的Python代码追踪、调试和性能分析工具，能够将代码执行过程以可视化方式呈现。它采用Perfetto作为前端UI，支持多线程、多进程、异步代码和PyTorch追踪，帮助开发者直观理解程序运行状态。本文将从安装到高级功能，全面介绍VizTracer的使用方法。
安装VizTracer
VizTracer支持Python 3.9+，可在Linux、macOS和Windows系统运行，无额外依赖。推荐通过pip安装：
pip install viztracer
也可使用conda安装：
conda install conda-forge::viztracer
为提升JSON处理性能，建议安装orjson：
pip install orjson
或直接安装包含所有优化的完整版：
pip install viztracer[full]
官方安装文档：docs/source/installation.rst
基础使用方法
命令行模式
最简单的使用方式是通过命令行。正常运行Python脚本的命令为：
python3 my_script.py
使用VizTracer只需将命令替换为：
viztracer my_script.py
# 或
python3 -m viztracer my_script.py
这将生成result.json文件，通过以下命令查看可视化报告：
vizviewer result.json
若脚本需要参数，直接追加即可：
viztracer my_script.py arg1 arg2
可指定输出文件路径和格式（JSON、HTML或GZ压缩）：
viztracer -o report.html my_script.py
viztracer -o report.json.gz my_script.py
使用--open选项可在追踪完成后自动打开报告：
viztracer --open my_script.py
代码内联模式
如需精确控制追踪范围，可在代码中手动启停VizTracer：
from viztracer import VizTracer
# 使用with语句自动管理生命周期
with VizTracer(output_file="custom_report.json") as tracer:
# 需要追踪的代码块
your_function()
# 或手动控制
tracer = VizTracer()
tracer.start()
# 追踪开始
tracer.stop()
tracer.save("manual_report.json")
Jupyter环境支持
在Jupyter中使用时，需先加载扩展：
%load_ext viztracer
然后使用单元格魔法命令：
%%viztracer
# 要追踪的代码
for i in range(1000):
compute(i)
执行后将出现"Show VizTracer Report"按钮，点击即可查看报告。
基础使用详细文档：docs/source/basic_usage.rst
可视化报告查看
VizTracer生成的JSON报告需通过vizviewer工具查看：
vizviewer result.json
默认会启动HTTP服务器并打开浏览器，访问http://localhost:9001查看报告。常用参数：
--server_only：仅启动服务器不自动打开浏览器--port 8080：指定端口--once：查看后自动关闭服务器--use_external_processor：使用外部处理器加载大型报告
多线程追踪效果
VizTracer自动支持Python原生线程追踪，无需修改代码。以下是多线程程序的追踪可视化效果：
多进程追踪效果
对于多进程程序，VizTracer可追踪包括subprocess、multiprocessing等多种进程创建方式：
异步代码追踪
使用--log_async选项增强异步代码追踪能力：
viztracer --log_async async_script.py
高级功能
火焰图生成
在Perfetto界面中选择任意时间段，点击"Slice Flamegraph"即可生成火焰图，直观展示函数调用耗时分布：
报告合并
可将多个追踪报告合并为一个，特别适用于分布式系统分析：
# 普通合并
viztracer --combine process1.json process2.json -o combined.json
# 时间对齐合并（用于对比分析）
viztracer --align_combine run1.json run2.json -o compare.json
自定义事件追踪
通过API在代码中插入自定义事件，辅助调试和性能分析：
from viztracer import get_tracer
# 瞬时事件
get_tracer().add_instant_event("start_processing", {"data": value})
# 持续事件
with get_tracer().add_duration_event("task", "subtask1"):
# 执行任务
自定义事件文档：docs/source/custom_event.rst
PyTorch追踪
启用--log_torch选项可追踪PyTorch原生调用和GPU事件：
viztracer --log_torch model_training.py
或在代码中设置：
with VizTracer(log_torch=True) as tracer:
model.train()
性能优化建议
- 控制追踪范围：使用
max_stack_depth限制调用栈深度，减少输出体积 - 过滤不需要的函数：通过
--include_files和--exclude_files正则匹配文件 - 调整缓冲区大小：
--tracer_entries 500000控制内存使用 - 使用稀疏日志：
--log_sparse仅记录关键事件 - 生成压缩报告：
--compress生成CVF格式压缩报告，节省存储空间
性能优化详细文档：docs/source/filter.rst
总结
VizTracer提供了从简单到复杂场景的全面追踪能力，无论是日常调试还是性能优化都能胜任。其低开销设计确保了在生产环境中也可安全使用，而强大的可视化界面让复杂的程序执行流程变得一目了然。
项目完整文档：docs/ 源代码仓库：src/viztracer/ 示例代码：example/src/
通过本文介绍的方法，您已掌握VizTracer的核心使用技巧。开始使用VizTracer洞察您的Python代码执行过程吧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
