pyroscope客户端需在主模块顶层调用pyroscope.start()并传application_name，gunicorn/uvicorn须在worker钩子中调用；启用异步支持需设pyroscope_async_profiling=1或enable_async_profiling=true且uvloop.install()前置；容器需保留调试符号；上报必须用grpc://协议。
Pyroscope 客户端怎么初始化才不会漏数据
Pyroscope 的 pyroscope Python SDK 默认不自动采集，必须显式调用 pyroscope.start() 才会启动 profiling。漏掉这一步，火焰图里就全是空的——不是没数据，是根本没开采样。
常见错误现象：pyroscope.start() 被放在某个函数里、或写在 import 后但没执行（比如被 if False 包裹）、或在子进程里重复调用却没传 application_name 导致上报冲突。
- 必须在主模块顶层、所有业务逻辑开始前 调用
pyroscope.start() - 务必传
application_name，否则多服务共用同一 Pyroscope server 时会混在一起，查不出是谁的火焰 - 若用 Gunicorn / Uvicorn，需在 worker 启动钩子里调用，不能只在主进程调；否则只有 master 进程有 profile，worker 全是空白
-
sample_rate默认是 100（单位：Hz），对高吞吐服务可降到 50 或 25，但低于 10 就容易错过短生命周期函数
火焰图里看不到 async 函数？检查 event loop 集成方式
Python 的 asyncio 事件循环本身不触发 CPython 的帧栈回调，Pyroscope 默认的 setprofile 无法捕获 async def 内部的 await 切换点。结果就是：函数名显示为 <module></module> 或 <listcomp></listcomp>，真实调用链断掉。
解决办法是启用 Pyroscope 的异步支持，但不是加个 flag 就行——它依赖具体 event loop 实现。
立即学习“Python免费学习笔记（深入）”；
- 仅
asyncio（标准库）和uvloop被官方支持；trio/curio不兼容 - 必须在
pyroscope.start()前设置环境变量PYROSCOPE_ASYNC_PROFILING=1，或传参enable_async_profiling=True - 若用
uvloop，需确保uvloop.install()在pyroscope.start()之前完成，否则 async 栈仍不可见 - 注意：开启 async profiling 后 CPU 开销会上升约 15%～20%，生产环境建议先灰度验证
为什么本地跑出火焰图，K8s 里全是
Pyroscope agent 依赖符号表（symbol table）把内存地址映射回函数名。容器镜像里如果没有调试信息（debug symbols）或 Python 源码路径，就会显示 <unknown></unknown> ——不是上报失败，是解析失败。
典型场景：用 python:3.11-slim 构建镜像，删了 /usr/src/python 和 .so 的调试段，Pyroscope 就找不到源码位置。
- 构建阶段保留
python-dbg或安装python3-dbg包（Debian/Ubuntu） - Dockerfile 中避免
apt-get clean和rm -rf /var/lib/apt/lists/*，这些可能删掉调试符号依赖的元数据 - 确保容器内
sys.executable指向的 Python 二进制文件带符号（可用readelf -S $(which python3) | grep debug验证） - 如果用 pyinstaller 打包，需加
--debug参数，否则 .exe/.bin 里没有帧信息
HTTP 上报失败但日志没报错？检查 gRPC 与 HTTP 端口混淆
Pyroscope server 默认同时监听 gRPC（4040）和 HTTP（4040 也是它的 metrics 端口，但 profile 上报走的是 gRPC）。很多人配 server_address="http://pyroscope:4040"，看着 URL 对，实际 client 会尝试走 HTTP POST，而 server 在该端口只响应 gRPC，连接静默失败。
错误现象：无日志、无异常、火焰图一直空，pyroscope SDK 也不抛错——它默认容忍上报失败。
- 客户端必须用
grpc://pyroscope:4040（不是 http://），或留空协议让 SDK 自动选 gRPC - 若 server 启用了 TLS，必须配
tls_ca_path，且 CA 文件得挂进容器，路径要绝对 - K8s Service 类型要是
ClusterIP或NodePort，别用LoadBalancer直接暴露 gRPC 端口，多数云厂商 LB 不透传 gRPC 流量 - 用
grpcurl -plaintext pyroscope:4040 list可快速验证 gRPC 连通性，比 curl 更准
火焰图不是“开了就能看”，关键路径上每个环节都卡着一个隐性依赖：符号表、event loop 集成时机、gRPC 协议选择、worker 生命周期管理。少一个，图就断一层。
