Pyroscope 与 Grafana Alloy 的 Linux eBPF 性能剖析环境部署、配置与排查实战指南【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope本指南以 Pyroscope 仓库中 eBPF 部署文档 为主线完整讲解如何在 Linux 机器上通过 Grafana Alloy 的pyroscope.ebpf组件实现零侵入的连续性能剖析Continuous Profiling从内核版本要求、Alloy 安装配置、进程发现与目标筛选到数据上报与结果验证。读完本文你将掌握一套可直接落地的 Linux eBPF 剖析部署流程并理解其背后的组件协同机制、参数语义与常见故障排查方法。eBPF 剖析架构一条从进程到火焰图的数据链路在深入部署细节之前先厘清整个剖析链路的组成部分。Grafana Alloy 的 eBPF 剖析由四个核心组件协同完成discovery.process发现宿主机上的进程生成包含 PID、可执行文件路径、命令行等元信息的目标discovery.relabel对发现的目标进行筛选与标签改写决定剖析谁、如何分组pyroscope.ebpfeBPF 剖析引擎本体运行在宿主机上按周期采集被选中进程的栈轨迹pyroscope.write将采集到的 profile 数据推送到 Pyroscope 服务器或 Grafana Cloud。其中pyroscope.ebpf运行在宿主机上采集与当前主机上进程关联的栈轨迹再通过forward_to参数把数据交给pyroscope.write组件发送。官方文档的架构图清晰地展示了这一数据流前置准备在开始配置之前你需要具备两样东西一个可供 Alloy 发送剖析数据的 Pyroscope 服务器可访问 Grafana并已配置好 Grafana Pyroscope 数据源。如果你手头既没有 Grafana 也没有 Pyroscope 服务器可以先用 Grafana Cloud 免费套餐起步等确认链路正常后再迁移到自建服务器。若使用自建的 Pyroscope 服务器Alloy 配置中的basic_auth认证段可以直接移除见下文配置示例。验证系统满足内核要求eBPF 剖析器要求 Linux 内核版本 4.9原因是它依赖BPF_PROG_TYPE_PERF_EVENT类型的 eBPF 程序——这种程序可以挂载到硬件或软件事件如性能监控计数器或 tracepoint上是性能采样能力的基础。查看当前机器内核版本uname -r确认输出的大版本号不低于 4.9 即可继续。如果你的发行版内核过旧需要先升级内核或换用较新的发行版。安装 Alloy按照 Grafana Alloy 官方针对你当前 Linux 发行版的安装说明下载并安装 Alloy 二进制。安装完成后Alloy 提供run子命令来加载并执行配置文件这也是后续启动剖析任务的入口。配置 Alloy一个完整的 Linux 本机剖析配置为了让 Alloy 剖析本机进程官方推荐组合使用discovery.process组件与pyroscope.ebpf组件前者负责发现进程后者为其添加默认目标——所有进程在默认目标下被统一剖析并分组。创建一个名为alloy.config的文件内容如下discovery.process all { } discovery.relabel alloy { targets discovery.process.all.targets // Filter needed processes rule { source_labels [__meta_process_exe] regex .*/alloy action keep } } pyroscope.ebpf instance { forward_to [pyroscope.write.endpoint.receiver] targets discovery.relabel.alloy.output } pyroscope.scrape local { forward_to [pyroscope.write.endpoint.receiver] targets [ {__address__ localhost:12345, service_namegrafana/alloy}, ] } pyroscope.write endpoint { endpoint { basic_auth { password PASSWORD username USERNAME } url URL } external_labels { env prod, instance env(HOSTNAME), } }逐段拆解这个配置① 进程发现discovery.process all {}使用空配置即可发现宿主机全部进程。每个发现目标会携带以下元标签meta labels标签含义__process_pid__进程 PID__meta_process_exe可执行文件路径__meta_process_cwd进程工作目录__meta_process_commandline完整命令行__meta_process_username运行用户名__meta_process_uid运行 UID__container_id__容器 ID② 目标筛选discovery.relabel以discovery.process.all.targets为输入用source_labels [__meta_process_exe]、regex .*/alloy、action keep只保留可执行文件路径匹配.*/alloy的进程即 Alloy 自身。实际使用时把正则替换成你真正想剖析的进程例如.*/myapp即可。③ eBPF 剖析引擎pyroscope.ebpf instance通过targets discovery.relabel.alloy.output接收筛选后的目标并把采集结果通过forward_to [pyroscope.write.endpoint.receiver]交给pyroscope.write组件。④ 补充抓取 Alloy 自身指标pyroscope.scrape local以localhost:12345为目标、service_name grafana/alloy抓取 Alloy 自身的运行时指标与 eBPF 剖析形成互补。这里需要 Alloy 的 HTTP 监听端口与__address__保持一致启动时通过--server.http.listen-addr指定。⑤ 数据出口pyroscope.write endpoint定义数据上报目标。把URL占位符替换为合适的服务器地址——可以是 Grafana Cloud URL也可以是你自建的 Pyroscope 服务器地址。external_labels会附加到每份 profile 上这里的示例注入了envprod与instanceHOSTNAME取自环境变量便于在 Pyroscope UI 中按环境与实例维度筛选数据。说明原文档中指向 Grafana Alloy 官方手册安装、配置参考、discovery.process参考的链接为外部站点本文以仓库内可验证的资料为准。若需在 Kubernetes、Docker 等不同运行环境下部署可参考仓库内同目录的 Kubernetes 部署文档 与 Docker 部署文档。pyroscope.ebpf 组件参数详解pyroscope.ebpf是整套方案的核心组件其完整参数语义整理如下来源配置参考文档参数类型说明默认值是否必填targetslist(map(string))按容器 ID 分组的剖析目标列表—是forward_tolist(ProfilesReceiver)接收采集结果的 receiver 列表—是collect_intervalduration采集 profile 的周期15s否sample_rateint每秒采集 profile 样本的次数97否pid_cache_sizeintPID → proc 符号表 LRU 缓存大小32否build_id_cache_sizeintELF build ID → 符号表 LRU 缓存大小64否same_file_cache_sizeintELF 文件 → 符号表 LRU 缓存大小8否container_id_cache_sizeintPID → 容器 ID 表 LRU 缓存大小1024否collect_user_profilebool是否采集用户态 profiletrue否collect_kernel_profilebool是否采集内核态 profiletrue否demanglestringC 符号还原模式none、simplified、templates、fullnone否值得注意的默认值细节sample_rate默认 97而非整百这是 eBPF 剖析常用的非整数采样率技巧可避免与目标进程的周期性调度产生谐振减少采样偏差与采集周期collect_interval默认 15 秒配合sample_rate决定每个周期内采集的栈轨迹数量若只想剖析用户态或内核态可分别关闭collect_kernel_profile或collect_user_profile剖析 C 应用时把demangle设为simplified或full可得到可读的符号名。支持的语言pyroscope.ebpf组件支持以下语言前提是开启 frame pointersGo默认开启 frame pointersRust开启 frame pointersC/C开启 frame pointersPython权限要求pyroscope.ebpf组件正常工作需要以 root 身份运行 Alloy并处于宿主 PID 命名空间host PID namespace内。这一约束在 Docker/Kubernetes 场景下体现为容器必须设置privileged: true与pid: host详见下文示例。目标选择机制进程如何被关联到 targettargets列表中每个目标必须包含以下特殊标签之一用于把剖析目标对应到具体容器或进程__container_id__容器 ID__meta_docker_container_idDocker 容器 ID__meta_kubernetes_pod_container_idKubernetes Pod 容器 ID__process_pid__进程 PID。匹配规则如下若某进程的容器 ID 命中目标的容器 ID 标签则该进程的栈轨迹按容器 ID 聚合到对应目标若进程的 PID 命中目标的 PID 标签则按 PID 聚合两者都不匹配的进程不会被剖析。service_name 的自动推断service_name是每个目标必须携带的特殊标签。如果未显式指定组件会依次尝试从以下来源推断__meta_kubernetes_pod_annotation_pyroscope_io_service_name即pyroscope.io/service_namePod 注解__meta_kubernetes_namespace与__meta_kubernetes_pod_container_name__meta_docker_container_name__meta_dockerswarm_container_label_service_name与__meta_dockerswarm_service_name。若显式指定和推断都不可行则回退为unspecified。此外以下标签会被自动注入前提是你没有自定义它们标签说明service_namePyroscope 服务名优先从发现元标签选取否则默认unspecified__name__Pyroscope 指标名默认process_cpu__container_id__从 target 推导出的容器 ID启动 Alloy注意eBPF 剖析器需要 root 权限。以 root 身份启动 Alloyalloy run alloy.config若看到如下错误levelerror msgcomponent exited with error componentpyroscope.ebpf.local_pods errebpf profiling session start: load bpf objects: field DisassociateCtty: program disassociate_ctty: map events: map create: operation not permitted (MEMLOCK may be too low, consider rlimit.RemoveMemlock)说明当前进程权限不足加载 BPF 对象时创建 map 被拒绝请确认 Alloy 是以 root 权限运行的。这条报错在容器场景中尤为常见——容器必须privileged: true才能获得加载 eBPF 程序的权限参见下文仓库示例中docker-compose.yml的容器配置。验证 profile 已成功接收剖析数据开始流动后打开 Pyroscope UI 或 Grafana 的 Pyroscope 数据源在类型profile type与服务service下拉菜单中选择目标即可查看服务列表应出现配置中指定的service_name本示例为grafana/alloy或按external_labels过滤选择process_cpu类型可查看进程 CPU 火焰图若看到多帧深度的完整栈轨迹说明符号解析正常见下文排查章节。进阶发送到 Grafana Cloud Profiles若目标是 Grafana Cloud Profiles可以使用基于环境变量的pyroscope.write配置避免在配置文件中硬编码凭据pyroscope.write endpoint { endpoint { basic_auth { password env(GC_PASSWORD) username env(GC_USER) } url env(GC_URL) } }使用前需确保GC_URL、GC_USER、GC_PASSWORD三个环境变量已正确设置Grafana Cloud stack 地址、用户与 API Key。若使用自建 Pyroscope 服务器则可完全移除basic_auth段。剖析行为的观测暴露的 Prometheus 指标pyroscope.ebpf组件会暴露以下 Prometheus 指标可用于监控剖析任务自身的健康状况来源配置参考文档pyroscope_fanout_latencyhistogram向直接与间接组件发送数据的写入延迟pyroscope_ebpf_active_targetsgauge组件当前跟踪的活动目标数pyroscope_ebpf_profiling_sessions_totalcounter完成的剖析会话总数pyroscope_ebpf_profiling_sessions_failing_totalcounter失败的剖析会话数pyroscope_ebpf_pprofs_totalcountereBPF 组件采集到的 pprof 数量。在生产环境中建议为这些指标配置告警例如profiling_sessions_failing_total持续增长时及时介入。仓库示例Linux、Docker 与 Kubernetes 三种落地形态仓库 examples/grafana-alloy-auto-instrumentation/ebpf 提供了与本文配套的三种可运行示例可作为上述配置的对照实现本机local示例local/config.alloy 在官方配置基础上做了两点增强值得借鉴discovery.relabel alloy { targets discovery.process.all.targets // Filter needed processes rule { source_labels [__meta_process_exe] regex .*/alloy action keep } // provide arbitrary service_name label, otherwise it will be unspecified rule { source_labels [__meta_process_exe] target_label service_name regex .*/alloy action replace replacement ebpf/local/alloy } } pyroscope.ebpf instance { forward_to [pyroscope.write.endpoint.receiver] targets concat( discovery.relabel.alloy.output, [{__process_pid__ 1, service_name ebpf/local/init}], ) }第二个 relabel 规则用replace动作把service_name显式改写为ebpf/local/alloy避免落入unspecifiedtargets通过concat把 relabel 输出与一个静态目标PID 1即容器 init 进程合并演示了动态发现 静态指定的混合用法。配套的 local/docker-compose.yml 展示了 Alloy 容器在 Linux 上运行 eBPF 剖析所必需的容器参数user: root、privileged: true、pid: host并把 Alloy 的 HTTP 监听端口设为0.0.0.0:12345以配合pyroscope.scrape抓取Pyroscope 服务器与 Grafana 一并编排一条docker-compose up --build即可拉起完整演示环境注意该示例因权限要求仅支持 Linux amd64。Docker 示例docker/config.alloy 展示了基于容器的目标发现用discovery.docker连接unix:///var/run/docker.sock通过__meta_docker_container_name正则过滤容器并把service_name改写为ebpf/docker/pyroscope。其目标分组逻辑与 Linux 本机版完全同构仅把进程发现替换为容器发现。Kubernetes 示例kubernetes/alloy.yaml 是完整的 K8s 部署清单DaemonSet 形式其关键点包括以 DaemonSet 部署保证每个节点上都有一个 Alloy 实例hostPID: true与privileged: true满足 eBPF 的权限与命名空间要求通过 RBAC ClusterRole 授予discovery.kubernetes组件读取 Pod 的get/list/watch权限用discovery.kubernetes按spec.nodeNameHOSTNAME过滤本节点 Pod随后用一组 relabel 规则注入namespace、pod、node、container标签并用service_name规则把namespace/container组合成服务名最后以regex (.*alloy|.*pyroscope|.*fast-slow)的keep规则只剖析感兴趣的 Pod并通过python_enabled true开启 Python 剖析。部署方式见 kubernetes/README.mdkubectl apply -f alloy.yaml -f grafana.yaml -f pyroscope.yaml -f python-fast-slow.yaml后kubectl port-forward -n pyroscope-ebpf service/grafana 3000:3000即可在 Grafana 的 Profiles Drilldown 应用中查看剖析结果。常见问题排查以下排查要点整理自仓库 troubleshooting 文档覆盖了 eBPF 剖析上线后最常遇到的四类问题。解释型语言难以剖析Ruby、JavaScript 等解释型语言不适合用本实现剖析其 JIT 编译方法通常不在 ELF 文件格式中需要额外步骤例如 Java 场景下的 perf-map-agent 与开启 frame pointers。解释型方法在火焰图中通常显示为解释器函数名而非真实函数名。出现 unknown symbols未知符号profile 中出现未知符号说明剖析器无法访问与栈轨迹地址关联的 ELF 文件。常见原因进程已终止ELF 文件不可访问ELF 文件损坏或无法被识别/proc/pid/maps中不存在与该栈地址对应的 ELF 文件条目。符号本身从以下来源提取ELF 文件的.symtab与.dynsym段、debug ELF 文件的.symtab与.dynsym段、Go 语言 ELF 文件的.gopclntab段。debug 文件的查找遵循 gdb 的 Separate Debug Files 算法例如剖析器要查找/lib/x86_64-linux-gnu/libc.so.6.gnu_debuglink指向libc.so.6.debug、build ID 为0123456789abcdef的 debug 文件时会依次检查/usr/lib/debug/.build-id/01/0123456789abcdef.debug/lib/x86_64-linux-gnu/libc.so.6.debug/lib/x86_64-linux-gnu/.debug/libc.so.6.debug/usr/lib/debug/lib/x86_64-linux-gnu/libc.so.6.debug只显示模块名、无函数名未解析符号如果火焰图只有模块名如/lib/x86_64-linux-gnu/libc.so.6而没有函数名说明符号无法映射到函数原因通常是二进制被 stripELF 中已无.symtab、.dynsym或.gopclntab段debug 文件缺失或无法定位。修复方式确保你的二进制未 strip或提供独立的 debug 文件。可用如下命令生成并关联 debug 文件objcopy --only-keep-debug elf elf.debug strip elf -o elf.stripped objcopy --add-gnu-debuglinkelf.debug elf.stripped elf.debuglink对于系统库安装对应 debug 符号包即可。以 Ubuntu 为例为libc安装调试符号apt install libc6-dbg堆栈过浅扁平火焰图如果 profile 中大量栈轨迹只有 1~2 层深说明二进制在编译时未开启 frame pointers。在编译器选项中加入-fno-omit-frame-pointer后重新编译即可。这也是上文支持的语言一节中反复强调开启 frame pointers的原因。Python 进程数据不可发现若出现如下报错pyperf get python process data failed: missing symbols pyRuntimeAddr autoTLSkeyAddr说明 Pyroscope 无法定位 Python 运行时符号常见诱因是非标准库命名。例如自定义命名libpython3-custom.10.so.1.0会导致失败Pyroscope 期望的是libpython3.10.so.1.0这类标准命名。请确保 Python 库遵循标准命名约定。总结在 Linux 上通过 Grafana Alloy 启用 eBPF 剖析是一条零代码侵入的连续剖析路径内核 ≥ 4.9 满足运行前提discovery.processdiscovery.relabel完成目标发现与筛选pyroscope.ebpf以默认 97 Hz 的采样率采集用户态与内核态栈轨迹最终由pyroscope.write推送至 Pyroscope 服务器或 Grafana Cloud。部署时牢记两个硬性约束——root 权限与宿主 PID 命名空间遇到符号缺失、堆栈扁平等问题时按上文排查清单逐项核对二进制编译选项、debug 文件与 Python 库命名即可快速定位。仓库中的 local、docker、kubernetes 三套示例可作为不同运行环境下的直接参考。【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pyroscope 与 Grafana Alloy 的 Linux eBPF 性能剖析：环境部署、配置与排查实战指南
Pyroscope 与 Grafana Alloy 的 Linux eBPF 性能剖析环境部署、配置与排查实战指南【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope本指南以 Pyroscope 仓库中 eBPF 部署文档 为主线完整讲解如何在 Linux 机器上通过 Grafana Alloy 的pyroscope.ebpf组件实现零侵入的连续性能剖析Continuous Profiling从内核版本要求、Alloy 安装配置、进程发现与目标筛选到数据上报与结果验证。读完本文你将掌握一套可直接落地的 Linux eBPF 剖析部署流程并理解其背后的组件协同机制、参数语义与常见故障排查方法。eBPF 剖析架构一条从进程到火焰图的数据链路在深入部署细节之前先厘清整个剖析链路的组成部分。Grafana Alloy 的 eBPF 剖析由四个核心组件协同完成discovery.process发现宿主机上的进程生成包含 PID、可执行文件路径、命令行等元信息的目标discovery.relabel对发现的目标进行筛选与标签改写决定剖析谁、如何分组pyroscope.ebpfeBPF 剖析引擎本体运行在宿主机上按周期采集被选中进程的栈轨迹pyroscope.write将采集到的 profile 数据推送到 Pyroscope 服务器或 Grafana Cloud。其中pyroscope.ebpf运行在宿主机上采集与当前主机上进程关联的栈轨迹再通过forward_to参数把数据交给pyroscope.write组件发送。官方文档的架构图清晰地展示了这一数据流前置准备在开始配置之前你需要具备两样东西一个可供 Alloy 发送剖析数据的 Pyroscope 服务器可访问 Grafana并已配置好 Grafana Pyroscope 数据源。如果你手头既没有 Grafana 也没有 Pyroscope 服务器可以先用 Grafana Cloud 免费套餐起步等确认链路正常后再迁移到自建服务器。若使用自建的 Pyroscope 服务器Alloy 配置中的basic_auth认证段可以直接移除见下文配置示例。验证系统满足内核要求eBPF 剖析器要求 Linux 内核版本 4.9原因是它依赖BPF_PROG_TYPE_PERF_EVENT类型的 eBPF 程序——这种程序可以挂载到硬件或软件事件如性能监控计数器或 tracepoint上是性能采样能力的基础。查看当前机器内核版本uname -r确认输出的大版本号不低于 4.9 即可继续。如果你的发行版内核过旧需要先升级内核或换用较新的发行版。安装 Alloy按照 Grafana Alloy 官方针对你当前 Linux 发行版的安装说明下载并安装 Alloy 二进制。安装完成后Alloy 提供run子命令来加载并执行配置文件这也是后续启动剖析任务的入口。配置 Alloy一个完整的 Linux 本机剖析配置为了让 Alloy 剖析本机进程官方推荐组合使用discovery.process组件与pyroscope.ebpf组件前者负责发现进程后者为其添加默认目标——所有进程在默认目标下被统一剖析并分组。创建一个名为alloy.config的文件内容如下discovery.process all { } discovery.relabel alloy { targets discovery.process.all.targets // Filter needed processes rule { source_labels [__meta_process_exe] regex .*/alloy action keep } } pyroscope.ebpf instance { forward_to [pyroscope.write.endpoint.receiver] targets discovery.relabel.alloy.output } pyroscope.scrape local { forward_to [pyroscope.write.endpoint.receiver] targets [ {__address__ localhost:12345, service_namegrafana/alloy}, ] } pyroscope.write endpoint { endpoint { basic_auth { password PASSWORD username USERNAME } url URL } external_labels { env prod, instance env(HOSTNAME), } }逐段拆解这个配置① 进程发现discovery.process all {}使用空配置即可发现宿主机全部进程。每个发现目标会携带以下元标签meta labels标签含义__process_pid__进程 PID__meta_process_exe可执行文件路径__meta_process_cwd进程工作目录__meta_process_commandline完整命令行__meta_process_username运行用户名__meta_process_uid运行 UID__container_id__容器 ID② 目标筛选discovery.relabel以discovery.process.all.targets为输入用source_labels [__meta_process_exe]、regex .*/alloy、action keep只保留可执行文件路径匹配.*/alloy的进程即 Alloy 自身。实际使用时把正则替换成你真正想剖析的进程例如.*/myapp即可。③ eBPF 剖析引擎pyroscope.ebpf instance通过targets discovery.relabel.alloy.output接收筛选后的目标并把采集结果通过forward_to [pyroscope.write.endpoint.receiver]交给pyroscope.write组件。④ 补充抓取 Alloy 自身指标pyroscope.scrape local以localhost:12345为目标、service_name grafana/alloy抓取 Alloy 自身的运行时指标与 eBPF 剖析形成互补。这里需要 Alloy 的 HTTP 监听端口与__address__保持一致启动时通过--server.http.listen-addr指定。⑤ 数据出口pyroscope.write endpoint定义数据上报目标。把URL占位符替换为合适的服务器地址——可以是 Grafana Cloud URL也可以是你自建的 Pyroscope 服务器地址。external_labels会附加到每份 profile 上这里的示例注入了envprod与instanceHOSTNAME取自环境变量便于在 Pyroscope UI 中按环境与实例维度筛选数据。说明原文档中指向 Grafana Alloy 官方手册安装、配置参考、discovery.process参考的链接为外部站点本文以仓库内可验证的资料为准。若需在 Kubernetes、Docker 等不同运行环境下部署可参考仓库内同目录的 Kubernetes 部署文档 与 Docker 部署文档。pyroscope.ebpf 组件参数详解pyroscope.ebpf是整套方案的核心组件其完整参数语义整理如下来源配置参考文档参数类型说明默认值是否必填targetslist(map(string))按容器 ID 分组的剖析目标列表—是forward_tolist(ProfilesReceiver)接收采集结果的 receiver 列表—是collect_intervalduration采集 profile 的周期15s否sample_rateint每秒采集 profile 样本的次数97否pid_cache_sizeintPID → proc 符号表 LRU 缓存大小32否build_id_cache_sizeintELF build ID → 符号表 LRU 缓存大小64否same_file_cache_sizeintELF 文件 → 符号表 LRU 缓存大小8否container_id_cache_sizeintPID → 容器 ID 表 LRU 缓存大小1024否collect_user_profilebool是否采集用户态 profiletrue否collect_kernel_profilebool是否采集内核态 profiletrue否demanglestringC 符号还原模式none、simplified、templates、fullnone否值得注意的默认值细节sample_rate默认 97而非整百这是 eBPF 剖析常用的非整数采样率技巧可避免与目标进程的周期性调度产生谐振减少采样偏差与采集周期collect_interval默认 15 秒配合sample_rate决定每个周期内采集的栈轨迹数量若只想剖析用户态或内核态可分别关闭collect_kernel_profile或collect_user_profile剖析 C 应用时把demangle设为simplified或full可得到可读的符号名。支持的语言pyroscope.ebpf组件支持以下语言前提是开启 frame pointersGo默认开启 frame pointersRust开启 frame pointersC/C开启 frame pointersPython权限要求pyroscope.ebpf组件正常工作需要以 root 身份运行 Alloy并处于宿主 PID 命名空间host PID namespace内。这一约束在 Docker/Kubernetes 场景下体现为容器必须设置privileged: true与pid: host详见下文示例。目标选择机制进程如何被关联到 targettargets列表中每个目标必须包含以下特殊标签之一用于把剖析目标对应到具体容器或进程__container_id__容器 ID__meta_docker_container_idDocker 容器 ID__meta_kubernetes_pod_container_idKubernetes Pod 容器 ID__process_pid__进程 PID。匹配规则如下若某进程的容器 ID 命中目标的容器 ID 标签则该进程的栈轨迹按容器 ID 聚合到对应目标若进程的 PID 命中目标的 PID 标签则按 PID 聚合两者都不匹配的进程不会被剖析。service_name 的自动推断service_name是每个目标必须携带的特殊标签。如果未显式指定组件会依次尝试从以下来源推断__meta_kubernetes_pod_annotation_pyroscope_io_service_name即pyroscope.io/service_namePod 注解__meta_kubernetes_namespace与__meta_kubernetes_pod_container_name__meta_docker_container_name__meta_dockerswarm_container_label_service_name与__meta_dockerswarm_service_name。若显式指定和推断都不可行则回退为unspecified。此外以下标签会被自动注入前提是你没有自定义它们标签说明service_namePyroscope 服务名优先从发现元标签选取否则默认unspecified__name__Pyroscope 指标名默认process_cpu__container_id__从 target 推导出的容器 ID启动 Alloy注意eBPF 剖析器需要 root 权限。以 root 身份启动 Alloyalloy run alloy.config若看到如下错误levelerror msgcomponent exited with error componentpyroscope.ebpf.local_pods errebpf profiling session start: load bpf objects: field DisassociateCtty: program disassociate_ctty: map events: map create: operation not permitted (MEMLOCK may be too low, consider rlimit.RemoveMemlock)说明当前进程权限不足加载 BPF 对象时创建 map 被拒绝请确认 Alloy 是以 root 权限运行的。这条报错在容器场景中尤为常见——容器必须privileged: true才能获得加载 eBPF 程序的权限参见下文仓库示例中docker-compose.yml的容器配置。验证 profile 已成功接收剖析数据开始流动后打开 Pyroscope UI 或 Grafana 的 Pyroscope 数据源在类型profile type与服务service下拉菜单中选择目标即可查看服务列表应出现配置中指定的service_name本示例为grafana/alloy或按external_labels过滤选择process_cpu类型可查看进程 CPU 火焰图若看到多帧深度的完整栈轨迹说明符号解析正常见下文排查章节。进阶发送到 Grafana Cloud Profiles若目标是 Grafana Cloud Profiles可以使用基于环境变量的pyroscope.write配置避免在配置文件中硬编码凭据pyroscope.write endpoint { endpoint { basic_auth { password env(GC_PASSWORD) username env(GC_USER) } url env(GC_URL) } }使用前需确保GC_URL、GC_USER、GC_PASSWORD三个环境变量已正确设置Grafana Cloud stack 地址、用户与 API Key。若使用自建 Pyroscope 服务器则可完全移除basic_auth段。剖析行为的观测暴露的 Prometheus 指标pyroscope.ebpf组件会暴露以下 Prometheus 指标可用于监控剖析任务自身的健康状况来源配置参考文档pyroscope_fanout_latencyhistogram向直接与间接组件发送数据的写入延迟pyroscope_ebpf_active_targetsgauge组件当前跟踪的活动目标数pyroscope_ebpf_profiling_sessions_totalcounter完成的剖析会话总数pyroscope_ebpf_profiling_sessions_failing_totalcounter失败的剖析会话数pyroscope_ebpf_pprofs_totalcountereBPF 组件采集到的 pprof 数量。在生产环境中建议为这些指标配置告警例如profiling_sessions_failing_total持续增长时及时介入。仓库示例Linux、Docker 与 Kubernetes 三种落地形态仓库 examples/grafana-alloy-auto-instrumentation/ebpf 提供了与本文配套的三种可运行示例可作为上述配置的对照实现本机local示例local/config.alloy 在官方配置基础上做了两点增强值得借鉴discovery.relabel alloy { targets discovery.process.all.targets // Filter needed processes rule { source_labels [__meta_process_exe] regex .*/alloy action keep } // provide arbitrary service_name label, otherwise it will be unspecified rule { source_labels [__meta_process_exe] target_label service_name regex .*/alloy action replace replacement ebpf/local/alloy } } pyroscope.ebpf instance { forward_to [pyroscope.write.endpoint.receiver] targets concat( discovery.relabel.alloy.output, [{__process_pid__ 1, service_name ebpf/local/init}], ) }第二个 relabel 规则用replace动作把service_name显式改写为ebpf/local/alloy避免落入unspecifiedtargets通过concat把 relabel 输出与一个静态目标PID 1即容器 init 进程合并演示了动态发现 静态指定的混合用法。配套的 local/docker-compose.yml 展示了 Alloy 容器在 Linux 上运行 eBPF 剖析所必需的容器参数user: root、privileged: true、pid: host并把 Alloy 的 HTTP 监听端口设为0.0.0.0:12345以配合pyroscope.scrape抓取Pyroscope 服务器与 Grafana 一并编排一条docker-compose up --build即可拉起完整演示环境注意该示例因权限要求仅支持 Linux amd64。Docker 示例docker/config.alloy 展示了基于容器的目标发现用discovery.docker连接unix:///var/run/docker.sock通过__meta_docker_container_name正则过滤容器并把service_name改写为ebpf/docker/pyroscope。其目标分组逻辑与 Linux 本机版完全同构仅把进程发现替换为容器发现。Kubernetes 示例kubernetes/alloy.yaml 是完整的 K8s 部署清单DaemonSet 形式其关键点包括以 DaemonSet 部署保证每个节点上都有一个 Alloy 实例hostPID: true与privileged: true满足 eBPF 的权限与命名空间要求通过 RBAC ClusterRole 授予discovery.kubernetes组件读取 Pod 的get/list/watch权限用discovery.kubernetes按spec.nodeNameHOSTNAME过滤本节点 Pod随后用一组 relabel 规则注入namespace、pod、node、container标签并用service_name规则把namespace/container组合成服务名最后以regex (.*alloy|.*pyroscope|.*fast-slow)的keep规则只剖析感兴趣的 Pod并通过python_enabled true开启 Python 剖析。部署方式见 kubernetes/README.mdkubectl apply -f alloy.yaml -f grafana.yaml -f pyroscope.yaml -f python-fast-slow.yaml后kubectl port-forward -n pyroscope-ebpf service/grafana 3000:3000即可在 Grafana 的 Profiles Drilldown 应用中查看剖析结果。常见问题排查以下排查要点整理自仓库 troubleshooting 文档覆盖了 eBPF 剖析上线后最常遇到的四类问题。解释型语言难以剖析Ruby、JavaScript 等解释型语言不适合用本实现剖析其 JIT 编译方法通常不在 ELF 文件格式中需要额外步骤例如 Java 场景下的 perf-map-agent 与开启 frame pointers。解释型方法在火焰图中通常显示为解释器函数名而非真实函数名。出现 unknown symbols未知符号profile 中出现未知符号说明剖析器无法访问与栈轨迹地址关联的 ELF 文件。常见原因进程已终止ELF 文件不可访问ELF 文件损坏或无法被识别/proc/pid/maps中不存在与该栈地址对应的 ELF 文件条目。符号本身从以下来源提取ELF 文件的.symtab与.dynsym段、debug ELF 文件的.symtab与.dynsym段、Go 语言 ELF 文件的.gopclntab段。debug 文件的查找遵循 gdb 的 Separate Debug Files 算法例如剖析器要查找/lib/x86_64-linux-gnu/libc.so.6.gnu_debuglink指向libc.so.6.debug、build ID 为0123456789abcdef的 debug 文件时会依次检查/usr/lib/debug/.build-id/01/0123456789abcdef.debug/lib/x86_64-linux-gnu/libc.so.6.debug/lib/x86_64-linux-gnu/.debug/libc.so.6.debug/usr/lib/debug/lib/x86_64-linux-gnu/libc.so.6.debug只显示模块名、无函数名未解析符号如果火焰图只有模块名如/lib/x86_64-linux-gnu/libc.so.6而没有函数名说明符号无法映射到函数原因通常是二进制被 stripELF 中已无.symtab、.dynsym或.gopclntab段debug 文件缺失或无法定位。修复方式确保你的二进制未 strip或提供独立的 debug 文件。可用如下命令生成并关联 debug 文件objcopy --only-keep-debug elf elf.debug strip elf -o elf.stripped objcopy --add-gnu-debuglinkelf.debug elf.stripped elf.debuglink对于系统库安装对应 debug 符号包即可。以 Ubuntu 为例为libc安装调试符号apt install libc6-dbg堆栈过浅扁平火焰图如果 profile 中大量栈轨迹只有 1~2 层深说明二进制在编译时未开启 frame pointers。在编译器选项中加入-fno-omit-frame-pointer后重新编译即可。这也是上文支持的语言一节中反复强调开启 frame pointers的原因。Python 进程数据不可发现若出现如下报错pyperf get python process data failed: missing symbols pyRuntimeAddr autoTLSkeyAddr说明 Pyroscope 无法定位 Python 运行时符号常见诱因是非标准库命名。例如自定义命名libpython3-custom.10.so.1.0会导致失败Pyroscope 期望的是libpython3.10.so.1.0这类标准命名。请确保 Python 库遵循标准命名约定。总结在 Linux 上通过 Grafana Alloy 启用 eBPF 剖析是一条零代码侵入的连续剖析路径内核 ≥ 4.9 满足运行前提discovery.processdiscovery.relabel完成目标发现与筛选pyroscope.ebpf以默认 97 Hz 的采样率采集用户态与内核态栈轨迹最终由pyroscope.write推送至 Pyroscope 服务器或 Grafana Cloud。部署时牢记两个硬性约束——root 权限与宿主 PID 命名空间遇到符号缺失、堆栈扁平等问题时按上文排查清单逐项核对二进制编译选项、debug 文件与 Python 库命名即可快速定位。仓库中的 local、docker、kubernetes 三套示例可作为不同运行环境下的直接参考。【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考