py-spy报permission denied的根本原因是需sys_ptrace权限读取进程内存，linux默认禁止非特权进程使用ptrace；解决方法包括：本地用sudo运行、docker加--cap-add=sys_ptrace、k8s在securitycontext中声明该能力，并确保/proc只读挂载。
py-spy 不需要“配置环境”——它不依赖目标程序安装任何包，也不修改 Python 解释器或 sys.path。你只需要在宿主机（或容器）上装好 py-spy，并确保它能读取目标进程的内存。
真正卡住人的从来不是安装，而是权限和路径这两关。
为什么 py-spy 启动就报 Permission denied？
这是最常见错误，错误信息通常是：Permission denied (os error 13) 或 Failed to attach to process。
根本原因是 py-spy 必须用 SYS_PTRACE 权限读取目标进程内存，而 Linux 默认禁止非特权进程这么做。
- 本地开发：用
sudo运行（仅调试时）：sudo py-spy top --pid 12345 - Docker 容器：启动时加
--cap-add=SYS_PTRACE，例如：docker run --cap-add=SYS_PTRACE -v /proc:/proc:ro your-python-app - Kubernetes：Deployment 中必须显式声明
securityContext.capabilities.add: ["SYS_PTRACE"]，且/proc需挂载为只读 - 注意：
ptrace_scope内核参数（/proc/sys/kernel/yama/ptrace_scope）值为1或更高时，即使有 cap 也可能失败；生产环境建议保持1，调试时临时设为0
record 模式下 profile.svg 打不开或内容为空？
不是生成失败，而是目标进程没跑起来、太快退出，或采样时间太短。
-
py-spy record默认只采样 30 秒，如果程序本身运行时间 - 加
-d参数延长采样时长，例如：py-spy record -d 60 -o profile.svg -- python myapp.py - 确认目标进程确实在运行：
ps aux | grep myapp.py，避免命令写错导致py-spy在子 shell 里空跑 - 火焰图是 SVG 格式，直接双击用浏览器打开即可；若显示空白，检查文件头是否含
<svg>，否则说明生成中断（常因权限或进程提前退出）</svg>
top 模式卡在 “Waiting for process…” 或刷新极慢？
py-spy top 是实时轮询模式，对进程状态变化敏感，容易受干扰。
- 不要对刚启动就退出的脚本用
top，改用record或dump - 加
--duration限制总监控时长，避免误操作锁死终端：py-spy top --pid 12345 --duration 20 - 默认每秒采样一次，如想更灵敏可调高频率：
--rate 10（每秒 10 次），但会略微增加开销 - 如果目标进程用了
fork()（比如某些 Web 服务器），py-spy top只监控主进程，子进程需单独指定--pid
如何让 dump 输出可读性强的线程快照？
py-spy dump 本质是抓当前所有 Python 线程的 CPython 栈帧，但默认输出不含源码行号或变量上下文。
- 确保目标 Python 进程启用了调试符号（即未用
-OO启动，且 .py 文件未被删） - 加
--native可同时显示 C 扩展调用栈（如 NumPy、Cython 模块），但需目标进程编译时保留 debug info - 输出重定向到文件更方便排查：
py-spy dump --pid 12345 > stack.txt 2>&1 - 重点关注状态为
Runnable或IOWait的线程；大量Waiting状态可能意味着 GIL 争抢或 I/O 阻塞
真正的难点不在命令怎么写，而在于你是否清楚自己要回答的问题：是找 CPU 热点？查卡死原因？还是比对两个版本的调用分布？选错命令模式（比如该用 dump 查 hang 却硬跑 record）比参数写错更浪费时间。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
