VizTracer 自定义事件指南：用 log_instant、log_var 与 log_event 精细化插桩你的 Python 程序

开发工具可观测性【免费下载链接】viztracerA debugging and profiling tool that can trace and visualize python code execution项目地址https://gitcode.com/gh_mirrors/vi/viztracer点击查看免费下载VizTracer 默认会自动记录函数调用形成完整的调用链火焰图。但在实际调试中我们往往还需要在任意代码位置注入个人标记记录一个瞬时状态、跟踪某个变量的值变化、或者把一段非函数代码当作一个可测耗时的事件。本文基于 docs/source/custom_event_intro.rst系统讲解 VizTracer 的三种自定义事件Instant Event、Variable Event、Duration Event并结合仓库源码说明其底层实现与--magic_comment命令行选项的用法帮助你零侵入地为报告补充业务语义。三种自定义事件总览VizTracer 在自动记录函数调用之外额外支持三类用户主动注入的事件事件类型API报告中的表现典型用途Instant Event瞬时事件tracer.log_instant(name, args, scope)以箭头形式出现在时间轴上记录某个瞬态事件如开始下载收到请求Variable Event变量事件tracer.log_var(name, var)数值用 Counter 曲线展示非数值用瞬时事件展示跟踪某个变量的变化轨迹Duration Event时长事件with tracer.log_event(name):与函数调用事件外观一致ph: X为任意代码片段计时而不仅限于函数三者均可通过 Tracer 对象直接调用在命令行CLI模式下可以通过get_tracer()获取当前活动的 Tracer。下面分别展开。Instant Event在时间轴上打一个瞬时箭头Instant Event 是某一具体时间戳上的日志在报告中显示为一个箭头适合记录转瞬即逝的事件。调用方式tracer.log_instant(fEvent1, argsargs, scopep)参数说明与 viztracer.py 中 log_instant 的实现 对应name字符串事件名称会直接显示在报告中args可选的附加数据必须是可 json 序列化的对象通常是一个字符串或由 dict、list、string、number 组合而成的结构scope事件的作用域取值tthread默认、pprocess或gglobal用于决定该事件在时间轴上的归属层级cond附加的布尔条件源码中的可选参数为False时本次记录被跳过。从源码看log_instant在cond为真时调用底层的add_instant(name, argsargs, scopescope)生成一个ph: iinstant的 trace event写入最终的 JSON 报告snaptrace.pyi。测试 tests/test_regression.py 中展示了用它记录耗时数据的实际用法get_tracer().log_instant(duration, args{duration: (end - start) / 1000})Variable Event跟踪变量的值变化Variable Event 用于把程序中的某个变量记录到报告中。它的行为取决于变量类型源码实现若变量是float或intVizTracer 生成counter event计数器事件在报告中呈现为随时间变化的数值曲线否则如 dict、list、str 等生成instant event并使用objprint.objstr()将对象格式化为可读字符串后作为参数展示。调用方式trace.log_var(name for the var, var)以测试 tests/test_fastlog.py 为例下面两种用法分别产生 Counter 曲线与 Instant 箭头tracer.log_var(test, 3) # 数值 → counter 事件 tracer.log_var(test, {a: 1, b: [3, 4, 3.6]}) # 非数值 → instant 事件在 tests/test_codemonkey.py 的校验逻辑中可以确认数值变量a最终以ph C的 counter 事件出现args为{value: 3}而字符串类瞬时事件以ph i出现。Magic Comment零开销、零副作用的注释插桩如果你希望正常运行程序时完全没有开销和副作用只在用 viztracer 追踪时才记录事件可以使用 Magic Comment 方式——通过特殊注释声明要记录的事件由 viztracer 在追踪时对源码做预处理把注释翻译成真实的日志调用。整行 Magic Comment在代码行上方书写# !viztracer: log_instant(...)或# !viztracer: log_var(a, a)# !viztracer: log_instant(start logging) a 3 # !viztracer: log_var(a, a)行内 Magic Comment# !viztracer: log可以放在语句末尾行为自动判定SourceProcessor.inline_transform 的实现逻辑若该语句是赋值语句记录被赋值的变量否则记录一个表示该行被执行的瞬时事件。# 这行会记录一个名为 f() 的瞬时事件 f() # !viztracer: log # 这行会记录变量 a a 3 # !viztracer: log对应源码中的变换结果是f() ; __viz_tracer__.log_instant(f())与a 3 ; __viz_tracer__.log_var(a, (a))这在 tests/test_codemonkey.py 的单测中有精确断言。条件记录两种注释形式都支持追加if条件仅当条件为真时才记录# 仅当 a 3 时记录变量 a a 3 # !viztracer: log if a 3 # 等价写法整行形式 if 条件 # !viztracer: log_var(a, a)从源码看条件分支在 SourceProcessor.line_transform_condition / inline_transform_condition 中被翻译为带if ...: __viz_tracer__.log_var(...)/if ...: __viz_tracer__.log_instant(...)的语句。注意log_var本身也支持cond参数Magic Comment 中的if条件最终就是走这一路径生效的。通过 --magic_comment 开启Magic Comment 需要显式开启否则注释会被当作普通注释忽略viztracer --magic_comment your_program.py命令行开关定义在 src/viztracer/main.py--magic_comment为store_true型布尔选项默认False。开启后CodeMonkey 会向编译流程注入一个SourceProcessor逐行用正则匹配并改写包含!viztracer:的行再交给 Python 正常编译执行。完整的 Magic Comment 行为矩阵在 tests/test_codemonkey.py 中的 file_magic_comment 脚本 里有系统覆盖包括四种组合整行/行内 × 无条件/带 if。Duration Event为任意代码片段计时Duration Event 与自动记录的函数调用事件几乎完全相同唯一区别是它不要求被测代码是函数——任何一段代码都可以像函数调用一样出现在最终报告的火焰图/时间轴中。from viztracer import get_tracer with get_tracer().log_event(my event name): # some code running here使用要点通过get_tracer()获取当前 TracerCLI 模式下自动注入或在内联inline场景直接传入自己创建的 Tracer 实例log_event返回一个上下文管理器对象with语句进入/退出时分别记录起止时间戳。底层实现VizEvent 上下文管理器log_event在 viztracer.py 中调用sys._getframe(1)捕获调用点的文件名与行号构造 VizEvent 对象进入with块时__enter__记录开始时间戳self._tracer.getts()退出时__exit__计算dur getts() - start生成ph: Xcomplete/duration事件cat标记为FEE事件名自动追加(file:lineno)以便定位代码位置最后通过self._tracer.add_raw(raw_data)写入报告数据。对应测试 tests/test_vizevent.py 验证了with tracer.log_event(event):会产生预期的 trace events。与 log_sparse 配合使用Duration Event 在**稀疏追踪log_sparse**场景下尤其有价值log_sparse只记录手动标记的代码路径而跳过大部分自动跟踪此时用log_event包裹关键代码段就能在稀疏报告中保留精确的耗时信息。log_sparse的具体用法见 docs/source/decorator.rst也可参考 tests/test_logsparse.py 中get_tracer().log_event(custom_event)的实测示例。小结与选择建议需求推荐方式是否需要开启选项记录某个瞬时事件tracer.log_instant(...)否跟踪数值/对象变量变化tracer.log_var(...)否零侵入地留下插桩标记Magic Comment viztracer --magic_comment是为非函数代码片段计时with get_tracer().log_event(...):否三种自定义事件都基于同一个底层事件写入机制add_instant/add_counter/add_raw因此会自动融入现有报告与火焰图视图。在调试复杂业务逻辑时建议优先使用 Magic Comment 方式保持源码纯净而在需要精确控制采样点如配合 log_sparse的场景直接调用log_instant/log_var/log_event更为灵活。赞分享开发工具可观测性【免费下载链接】viztracerA debugging and profiling tool that can trace and visualize python code execution项目地址https://gitcode.com/gh_mirrors/vi/viztracer点击查看免费下载相关推荐VizTracer 自定义事件深度指南用 VizCounter 与 VizObject 追踪程序运行中的任意数据VizTracer 自定义事件深度指南用 VizCounter 与 VizObject 追踪程序运行中的任意数据 本文以 VizTracer 的对象级自定义事开发工具可观测性从零构建本地语音智能体Speech-to-Speech实战指南从零构建本地语音智能体Speech to Speech实战指南 在当今AI应用开发中语音交互系统正从云端向本地迁移。开发者面临的核心挑战是如何在本地环境中人工智能大模型语音音频AI 应用本地部署后端从3.x迁移到4.xdocker-baseimage-gui适配指南与注意事项从3.x迁移到4.xdocker baseimage gui适配指南与注意事项 docker baseimage gui是一个用于简化X图形应用容器创建的最小上一篇RimSort终极免费的环世界MOD管理器3分钟解决加载顺序混乱下一篇番茄小说下载器终极指南如何三步搭建个人离线图书馆创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考