py-spy：不改动代码就能分析 Python 性能
文章目录
- py-spy：不改动代码就能分析 Python 性能
- 三个命令覆盖日常需求
- 跨平台和多版本支持
- 工作原理
- 权限相关
- 什么时候用它
py-spy：不改动代码就能分析 Python 性能
Python 程序跑得慢，定位瓶颈是个常见需求。常规做法是在代码里插入分析逻辑，或者重启程序挂上分析器。py-spy 提供了一条不同的路径：直接读取运行中的 Python 进程，不用改一行代码，也不用重启服务。
这个项目用 Rust 写成，核心目标是低侵入。它不和被分析的 Python 进程跑在同一个空间里，而是通过操作系统提供的内存读取接口，直接采样目标进程的调用栈。这意味着你可以在生产环境直接用它，对正在服务的程序影响极小。
三个命令覆盖日常需求
py-spy 的命令行接口很简洁，只有三个子命令。
record用于生成性能报告。指定目标进程的 PID，或者直接跟 Python 命令，它会持续采样并输出火焰图 SVG 文件。输出格式也支持 speedscope 和原始数据，方便用其他工具二次分析。
top提供一个实时视图，类似系统自带的 top 命令，但显示的是 Python 层面的函数耗时排名。适合快速定位当前最热的代码路径。
dump则是一次性输出所有线程的调用栈。程序卡住的时候，用这个命令看一眼各线程停在哪儿，往往就能定位问题所在。
跨平台和多版本支持
py-spy 支持 Linux、macOS、Windows 和 FreeBSD。Python 版本覆盖 2.3 到 2.7，以及 3.3 到 3.14。这个范围相当宽， legacy 项目和新项目都能用。
安装方式也灵活。PyPI 上有预编译的 wheel，一条 pip 命令就能装好。macOS 用户可以用 Homebrew，Arch Linux 用户可以从 AUR 安装。如果你是 Rust 开发者，也可以直接 cargo install 从源码编译。
工作原理
py-spy 直接读取目标进程的内存来还原 Python 调用栈。在 Linux 上通过 process_vm_readv，macOS 上用 vm_read，Windows 上用 ReadProcessMemory。
具体做法是：先找到 PyInterpreterState 的位置，拿到所有线程列表，再逐个遍历 PyFrameObject 来还原调用链。由于 CPython 的内存布局随版本变化，项目用 bindgen 为每个支持的版本生成对应的 Rust 结构体，确保能正确解析。
ASLR（地址空间布局随机化）会带来一些麻烦。如果 Python 解释器带有符号表，可以直接从 interp_head 或 _PyRuntime 变量定位解释器地址。但很多发行版会剥离符号，这时 py-spy 会扫描 BSS 段，寻找符合 PyInterpreterState 特征的内存地址。
权限相关
读取其他进程的内存通常需要特定权限。macOS 上必须 root 运行。Linux 的默认配置更细：如果由 py-spy 启动目标进程，一般不需要 root；但附加到已有进程通常需要 sudo。这个限制可以通过调整 ptrace_scope 参数来放宽。
Docker 和 Kubernetes 环境里也常见权限问题，需要给容器添加 SYS_PTRACE 能力。文档里对这些场景都有具体说明。
什么时候用它
如果你需要分析一个已经在跑的 Python 服务，又不想重启或修改代码，py-spy 是个直接的选择。它的开销足够低，对线上服务的影响在可接受范围内。
火焰图输出对理解程序热点很直观。GIL 检测功能可以帮你判断多线程程序里哪些线程在争用全局锁。子进程分析功能则对用了 multiprocessing 或 gunicorn 的架构有用。
这个项目目前有 15,236 个 Star，解决的是一个具体的工程问题：在生产环境安全地分析 Python 性能。
,236 个 Star，解决的是一个具体的工程问题：在生产环境安全地分析 Python 性能。