sys.monitoring 是 python 3.12 中需 c 层启用的低开销事件钩子机制，非开箱即用；默认全禁用，须通过 -x dev 启动并调用 c api 注册事件与回调，python 层仅能占位工具 id。
Sys.monitoring 在 Python 3.12 中不是“开箱即用”的监控模块，它是一套极低开销、可动态启用的底层事件钩子机制，不提供现成的统计图表或火焰图，直接用容易触发 RuntimeError: monitoring not enabled 或收不到事件。
为什么 sys.monitoring 默认完全禁用
Python 3.12 把监控开关全权交给运行时控制：即使你 import 了 sys 并访问 sys.monitoring，所有事件类型（如 sys.monitoring.events.LINE）初始状态都是 sys.monitoring.UNINITIALIZED，且无法通过 Python 代码自行激活——必须由 C 扩展、嵌入式环境或启动时带特定 flag（如 -X dev 配合 C API 调用）启用。普通脚本里直接调 sys.monitoring.use_tool_id() 会报错。
- 它设计目标是供 profiler 工具（如
py-spy下一代后端、tracemalloc增强版）做无侵入采样，不是给应用层写“监控逻辑”用的 - 启用后每个事件（比如每次函数入口）只增加约 0.5ns 开销，但代价是：所有线程共享同一组全局钩子，不能 per-thread 控制
- 事件回调必须是 C 函数指针，Python 可调用对象（如 lambda）会被拒绝，传
lambda: None会静默失败或 segfault
怎么让 sys.monitoring 实际生效（仅限开发/调试环境）
目前唯一稳定可用的方式是配合 C 扩展或使用已封装好的实验性工具。官方示例（Tools/scripts/monitoring_example.c）需要手动编译并用 python -X dev 启动：
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
python -X dev -c "import sys; print(sys.monitoring.get_tool(1))"
这行命令本身不会输出内容——因为没注册 tool_id=1 的工具。真正要看到事件，得：
- 用
PyMonitoring_SetEvents()C API 注册事件类型（如PY_MONITORING_EVENT_CALL） - 用
PyMonitoring_SetCallback()绑定 C 回调函数，该函数接收PyFrameObject*和事件参数 - Python 层只能通过
sys.monitoring.use_tool_id(1, 'mytool')占位，实际开关和回调全在 C 侧 - 注意：CPython 3.12.0–3.12.3 中
sys.monitoring的 Python 接口仍标记为 “provisional”，API 可能在补丁版本中微调
sys.monitoring 和传统方案（sys.settrace / sys.setprofile）的关键差异
它不是替代品，而是降级路径：当你发现 sys.settrace 导致程序慢 5–10 倍时，才考虑迁移。区别在于：
-
sys.settrace每行都进 Python 层回调，能改frame.f_locals；sys.monitoring只通知事件发生，不暴露 frame 对象（除非显式开启FRAME事件并手动解析） -
sys.monitoring支持 per-event 精确开关：比如只开LINE事件分析热点行，关掉CALL避免爆炸式调用栈 - 没有
sys.monitoring.disable()这种函数——停用靠PyMonitoring_UnsetEvents()C 调用，Python 层只能设为UNINITIALIZED占位 - Windows 上部分事件（如
EXCEPTION_HANDLED）可能因 SEH 机制缺失而始终不触发
真正想用它，得接受“写少量 C 代码 + 编译 + 启动参数”的门槛。纯 Python 用户现在更现实的选择是 py-spy record -p $(pidof python)，它底层已悄悄适配了 sys.monitoring 的 C API，但把复杂性藏在了 Rust 绑定里。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
