mcpField
P
pyroscope

pyroscope

github.com/grafana云与 DevOps2954.8k 次安装1 天前更新
代码仓库

关于 pyroscope

用于配置 Grafana Pyroscope 持续剖析的技能，面向应用开发与运维场景。内容涵盖 SDK 和 Alloy eBPF 采集、ProfileQL 查询及故障排查。

主要功能

  1. 01SDK 应用埋点配置
  2. 02Alloy eBPF 集群剖析
  3. 03ProfileQL 查询
  4. 04采集验证与故障排查

适用场景

  1. 01为应用接入 CPU 与内存剖析
  2. 02通过 eBPF 采集集群配置文件
  3. 03使用 ProfileQL 筛选性能数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/grafana/skills --skill pyroscope

安装后在 Claude Code 中输入/pyroscope确认已加载。

附带文件references/ebpf-and-query.mdreferences/sdks.md

详细介绍

Grafana Pyroscope

文档：https://grafana.com/docs/pyroscope/latest/

持续性能分析——展示 CPU、内存、分配、互斥锁争用和 goroutine 的火焰图。

前置条件

  • Pyroscope 服务（OSS）或 Grafana Cloud Profiles 端点
  • 对于 Cloud：数字形式的 Pyroscope 用户名（stack id）+ API 密钥
  • 通过 Alloy 使用 eBPF：root 权限 + 主机 PID + 启用了 BTF 的 Linux ≥ 5.8（或 RHEL 4.18+）

接入方式

  1. Alloy eBPF（推荐）——自动接入，无需更改代码
  2. SDK 直接推送——应用调用 Pyroscope API
  3. SDK → Alloy——SDK 向 pyroscope.receive_http 发送请求，由 Alloy 转发

常见工作流

1. 使用 SDK 为应用接入性能分析（示例：Python）
pip install pyroscope-io==1.0.11

import pyroscope, os
pyroscope.configure(
    application_name="my.python.app",
    server_address="http://pyroscope:4040",
    sample_rate=100, oncpu=True,
    tags={"region": os.getenv("REGION"), "env": "prod"},
)
# Dynamic tag for a hot path
with pyroscope.tag_wrapper({"controller": "slow_controller"}):
    slow_code()

# Verify the app is pushing — Pyroscope ingests samples in a few seconds
curl -s http://pyroscope:4040/ready                                    # → "ready"
curl -s http://pyroscope:4040/api/v1/labels | jq '.data | index("service_name")'  # → not null

# Verify the service shows up in Grafana → Explore → Profiles → service dropdown.

其他 SDK（Java agent、Node、Ruby、.NET、Rust）、Cloud 身份验证和可调环境变量：references/sdks.md。

2. 使用 Alloy 进行集群范围的 eBPF 性能分析
# config.alloy — full block in references/ebpf-and-query.md
pyroscope.ebpf "local_pods" {
  forward_to       = [pyroscope.write.cloud.receiver]
  targets          = discovery.relabel.local_pods.output
  sample_rate      = 97
  collect_interval = "15s"
}
pyroscope.write "cloud" {
  endpoint {
    url = "https://profiles-prod-xxx.grafana.net"
    basic_auth { username = sys.env("PYROSCOPE_USER")
                 password = sys.env("GRAFANA_API_KEY") }
  }
}

# 1. Reload Alloy
curl -X POST http://localhost:12345/-/reload

# 2. Verify the eBPF component is healthy
curl -s http://localhost:12345/api/v0/web/components \
  | jq '.[] | select(.id|contains("pyroscope.ebpf")) | {id,health:.health.state}'
# Expect: health.state == "healthy"

# 3. Verify profiles arriving in Pyroscope
#    Grafana → Explore → Profiles datasource → query:
#      {namespace="default", __profile_type__="process_cpu:cpu:nanoseconds:cpu:nanoseconds"}
#    Expect flame graph to render with frames from the target pods.
3. 使用 ProfileQL 查询
{service_name="myapp", env="prod",
 __profile_type__="process_cpu:cpu:nanoseconds:cpu:nanoseconds"}

性能分析类型列表和完整的 ProfileQL 语法：references/ebpf-and-query.md。

故障排查

  • SDK 已启动，但没有火焰图 → 检查应用是否确实调用了 start() / configure()（某些 SDK 会延迟执行）；检查容器内是否可以访问 server_address
  • Alloy eBPF 组件状态为 unhealthy，并报告 BPF 错误 → 内核版本低于 5.8 或缺少 BTF；运行 ls /sys/kernel/btf/vmlinux 检查
  • 推送到 Cloud 时返回 401 → basic_auth_username 错误（必须使用数字形式的 stack id，而不是 slug）
  • 性能分析结果已显示，但没有调用栈帧 → 对于 Java，设置 PYROSCOPE_FORMAT=jfr；对于 Alpine 上的 Python，确保 procfs 和 glibc 兼容

资源

评论

支持 Markdown