Python sys.monitoring 怎么做低开销函数追踪：事件掩码、工具 ID 与回退边界

线上服务里有一段函数偶尔变慢，想临时看调用路径，却不愿意给整个进程打开高密度逐行追踪。Python 3.12 引入的 sys.monitoring 适合处理这种窄范围问题：先占用一个工具 ID，再只打开需要的执行事件，回调里还可以对已经确认无关的代码位置返回 DISABLE。

先把“想看函数”拆成三个选择

第一次接触这个 API 时，最容易把它当成开了就能直接吐出所有函数调用的开关。实际落地要捋清楚三个核心选择：哪个工具ID占住监控槽位、要监听哪些目标事件、回调拿到事件后要记录哪些有效信息。漏了任何一步都拿不到可用的追踪结果。

工具 ID 是协作边界。官方 API 目前允许使用 0 到 5，其中 DEBUGGER_ID、COVERAGE_ID 和 PROFILER_ID 已经有约定用途。临时脚本可以选择一个未占用的 ID，但不能假设某个 ID 永远空闲；use_tool_id() 如果发现冲突会抛出 ValueError。

事件则决定回调密度。只想知道函数进入和退出，可以先组合 PY_START | PY_RETURN；想精确到每行才加 LINE。后者产生的回调明显更多，不能作为默认配置。

用最小脚本记录函数进入和返回

下面这段代码只追踪当前进程中 Python 函数的开始和返回。回调签名要按事件类型处理：PY_START 与 PY_RETURN 都会带代码对象，返回事件还可能带返回值。

import sys

monitor = getattr(sys, "monitoring", None)
if monitor is None:
    raise RuntimeError("需要 Python 3.12 或更高版本")

tool_id = 3
events = monitor.events

def on_start(code, instruction_offset):
    print("enter", code.co_qualname, code.co_filename)

def on_return(code, instruction_offset, retval):
    print("return", code.co_qualname, repr(retval))

monitor.use_tool_id(tool_id, "local-trace")
try:
    monitor.register_callback(tool_id, events.PY_START, on_start)
    monitor.register_callback(tool_id, events.PY_RETURN, on_return)
    monitor.set_events(tool_id, events.PY_START | events.PY_RETURN)
    # 在这里调用待观察的业务函数
finally:
    monitor.set_events(tool_id, events.NO_EVENTS)
    monitor.free_tool_id(tool_id)

这个示例故意没有把逻辑写进全局导入阶段。实际项目里应该把监控包在一次明确的诊断窗口内，避免测试结束后仍然占用工具 ID。要是业务函数在 try 块中抛错，finally 仍然会执行清理，这是临时诊断脚本必须保留的收口动作。

事件掩码怎么选，取决于证据而不是习惯

sys.monitoring.events 中的事件常量是可以按位或组合的整数。几个常用选择可以这样理解：

别一上来把 LINE、INSTRUCTION 和所有调用事件全打开。先用函数开始/返回确定慢点在哪一层，再把事件范围缩到目标代码对象，通常更容易读懂结果。

全局事件与局部事件不是同一层开关

set_events() 设置的是工具的全局事件；set_local_events() 则可以给某个代码对象增加局部事件。局部事件会叠加到全局事件上，并不会把全局事件屏蔽掉。所以如果全局已经打开 LINE，只对一个函数设置局部 PY_START，并不能把其他函数的逐行事件自动关掉。

要做窄范围诊断，一种更稳的做法是全局只打开很少的事件，或者把全局设为 NO_EVENTS，再针对目标代码对象设置局部事件。示意代码如下：

target_code = target_function.__code__

monitor.set_events(tool_id, events.NO_EVENTS)
monitor.set_local_events(
    tool_id,
    target_code,
    events.PY_START | events.PY_RETURN,
)

try:
    target_function()
finally:
    monitor.set_local_events(tool_id, target_code, events.NO_EVENTS)

代码对象范围适合已知目标函数的实验。若函数会被装饰器替换，先确认拿到的是实际执行的 __code__，否则会出现“回调已经注册但没有输出”的假象。

确认无关位置后，用 DISABLE 停掉后续回调

回调可以返回 sys.monitoring.DISABLE，让当前代码位置的事件停止。它不会改变其他代码位置，也不会替你释放工具 ID，因此适合处理“第一次命中后不需要继续观察”的场景。

seen = set()

def on_line(code, line_number):
    key = (code.co_filename, code.co_firstlineno, line_number)
    if key in seen:
        return monitor.DISABLE
    seen.add(key)
    print("line", code.co_name, line_number)

monitor.register_callback(tool_id, events.LINE, on_line)
monitor.set_events(tool_id, events.LINE)
try:
    run_one_diagnostic_request()
finally:
    monitor.restart_events()
    monitor.set_events(tool_id, events.NO_EVENTS)

这里的 DISABLE 是事件级别的局部停用，不要把它理解成取消整个工具。需要恢复所有被停用的事件时可以调用 restart_events()，但恢复之后仍要在最终清理阶段关闭工具事件。

版本回退和三个常见误判

把它写成独立模块导入

sys.monitoring 是 sys 的命名空间，不能依赖 import sys.monitoring。兼容代码可以通过 getattr(sys, "monitoring", None) 判断能力是否存在，再决定启用监控还是走普通日志/计时路径。

看到回调冲突就强行换 ID

ValueError 说明当前 ID 已经被其他工具使用。先检查约定 ID 和当前进程内的工具协作方式，再选择空闲 ID；更重要的是在退出时调用 free_tool_id()，不要让诊断脚本把槽位长期占住。

只看函数进入就判断函数很慢

PY_START 只能说明进入了函数。要做耗时判断，至少记录开始和返回的时间戳，并把异常退出、阻塞等待和子调用单独区分；监控事件本身不是完整的性能剖析结果。

把选择收敛成一张检查清单

如果目标只是临时确认一条调用路径，先选一个空闲工具 ID，注册 PY_START 和 PY_RETURN，把结果写到诊断日志里；只有锁定目标函数后，才考虑 LINE 或局部代码对象事件。每次测试结束都检查事件是否为 NO_EVENTS、工具 ID 是否已经释放，并在 Python 3.11 及更早版本走明确的回退实现。

这套 API 的核心优势是可控：监控覆盖范围、事件触发密度、停用回收时机全部可以由业务脚本自主控制。它没法替代全量的专业性能分析工具，也不会自动定位出业务变慢的根因，但在短时间的局部诊断场景下，完全可以把“代码到底有没有走到这一步”这类纯猜测的问题，变成可以回溯校验的实锤证据。

常见问题

Python 3.11 能直接使用 sys.monitoring 吗？

不能。这个命名空间从 Python 3.12 开始提供。旧版本应当走普通日志、装饰器计时或现有 profiler 的回退路径，不要在运行到一半时才因为属性不存在而中断业务。

为什么已经注册回调，却没有任何输出？

先检查工具 ID 是否已经通过 use_tool_id() 占用，再确认对应事件已经用 set_events() 或 set_local_events() 打开。若只注册回调而没有启用事件，回调不会自动触发。

set_local_events 会覆盖全局事件吗？

不会。局部事件会叠加到全局事件上。想把监控限制在一个代码对象，先把全局事件收窄到 NO_EVENTS，再设置局部事件，并在诊断结束时清理局部配置。

返回 DISABLE 后怎样恢复？

可以调用 restart_events() 恢复被停用的事件，但它不等于释放工具。最终仍要执行 set_events(tool_id, events.NO_EVENTS)，并调用 free_tool_id() 归还工具槽位。