Python 3.15 sampling profiler 怎样采集热点

Python 3.15 的采样分析器通过 python3.15 -m profiling.sampling 使用：新任务用 run，已有进程用 attach。先选 CPU 或墙钟时间口径，再用有限时长采样观察热点；不要把采样占比当作精确调用次数，也不要直接把所有等待位置认作计算瓶颈。

官方地址：https://www.python.org/

3.15 新增的 profiling 包把采样与跟踪分析分开组织，采样工具也称 Tachyon。本文给出适合受控环境的采集方法，不运行示例，不提供虚构报告或性能提升数字。

先确定要找计算热点还是等待位置

如果服务响应慢，先问“时间花在计算还是等待”。官方说明中，wall 口径包含等待，cpu 口径关注活跃 CPU 执行。因此一个在 wall 中占比高的调用位置，可能关联外部资源等待，不等于那一行代码正在持续消耗处理器。

把问题写成可判断的一句话，例如“定位报表任务中持续计算的调用路径”，而不是“找所有性能问题”。这能限制采集范围，也能防止拿到漂亮图形后忘记最初要回答的问题。对于同一任务，CPU 口径与墙钟口径可以各自保存，但不能混成一张未经说明的排名。

准备匹配版本和受控采集环境

先在应用的实际运行环境确认解释器和工具入口，避免本机用 3.15、目标服务仍在另一版本。附加采样要求工具与目标的 Python 次版本一致，标准构建与自由线程构建也不能随意交叉附加。先记录构建身份，再决定使用哪个解释器。

# 确认当前命令对应的解释器版本和工具帮助，不启动业务任务。
python3.15 --version
python3.15 -m profiling.sampling --help

为一次采集准备独立的本地目录，报告名称区分业务、采集口径与窗口。以下命令里的 report_job.py 和 PID 都是读者需要替换的对象。不要直接将示例数字当成目标进程，也不要为文章截图运行任何服务。

对于生产任务，建议先选一个代表性负载窗口，记录是否在预热、数据规模是否变化，以及是否有并行批任务。这些记录比单独一个“占比最高函数”更有助于解释后续差异。

用短窗口与固定口径采集

对于你可以自行启动的任务，先采集一个有限窗口。示例使用 18 秒，而不是无期限采集；时长是本例的限制条件，不是所有服务的推荐常数。

# 针对计算热点启动自己的脚本；输出HTML只保存到受控的本地目录。
python3.15 -m profiling.sampling run --mode cpu -d 18 --flamegraph -o job-cpu.html report_job.py

如果目标已经运行，且你有读取该进程所需的权限，可以改用 attach。下面单独演示墙钟口径，便于检查调用路径中的等待；它与前面的 CPU 报告回答不同问题。

# 将24680替换为已核对且获授权的Python进程ID；到时结束本轮采样。
python3.15 -m profiling.sampling attach --mode wall -d 18 --flamegraph -o service-wall.html 24680

初次采集先保留默认采样率，不要为了更细的图立刻拉高频率。采样器自身仍会使用机器资源；即使对目标采用外部观察，也不能据此承诺整台机器没有额外成本。需要提高精度时，先评估样本是否足以支持判断，再决定延长窗口还是调整频率。

命令完成后的检查点是工具是否正常结束、报告是否对应预期目标及口径、采集期间业务是否具有代表性。本文没有提供伪造的终端输出；读者应以自己环境的实际反馈为准。

权限不足时停止并核对授权

attach 涉及读取目标进程内存，受操作系统和部署环境的权限约束。遇到拒绝访问时，先确认账户、目标 PID 和运行环境，再向负责该环境的管理员确认授权方式。不要把扩大权限当作采样的默认前置动作。

尤其不应为了分析一次热点而随手关闭整机防护、放宽共享主机的全局访问规则，或把调试能力长期留给所有容器。更稳妥的做法是在已批准的诊断环境重现负载，或由有权限的维护人员在限定范围完成采集。无法获得授权就保留问题与错误信息，停止附加。

能读取进程并不代表报告可以公开分享。文件路径、模块名、函数名以及调用结构本身都可能是内部信息。采样产物应按内部诊断资料管理，而不是直接上传到公共图床或在线转换服务。

把采样报告作为定位线索

采样报告记录的是周期性栈观察。频繁出现在样本中的路径值得进一步检查，但采样并不记录每一次调用。需要精确调用计数时，应另选跟踪分析；极短任务或细微性能差异，也不适合只凭一次采样就下结论。

阅读时先看报告采用的口径，再看调用者与被调用者关系，区分自身工作与下层工作。父调用路径出现得多，不意味着应该删除父函数；先沿业务意义追到具体的数据处理、等待或重复工作，再形成可以复测的修改假设。

注意占比的分母：其他路径的工作量变化，也会改变当前路径的相对占比。一次优化后，排名可能变化，但最终仍要回到任务总耗时、吞吐或业务延迟等原始目标，不能只以某个框变窄作为成功标准。

记录复测条件并妥善保管报告

每份报告旁保存解释器构建、应用版本、目标角色、采样口径、时长和负载说明。改变代码后，用可比的条件重新采集，并把业务结果与热点变化一起记录。这是一份建议流程，不代表本文已经执行或验证这些测试。

采样器会自动优化程序吗？不会。报告给出定位线索，仍需结合业务逻辑提出改动并复测。

为什么没有捕获到很短的函数？函数可能在两个采样时刻之间完成。不要把“未出现”写成“从未执行”。

为什么报告不同于本地开发环境？先核对负载、缓存状态、数据规模和构建条件。条件不同，报告不一致并不自动证明采样错误。

完成诊断后，结束本次采集，按团队保留策略归档或清理产物；需要删除时只针对已经确认的单份文件。核心做法是限制采集范围、固定观察口径、守住权限，再把样本当作线索而不是精确账本。

参考：Python 3.15 采样分析器文档；Python 3.15 新特性说明；PEP 799 profiling 包组织说明。