pyroscope

Grafana Pyroscope

ドキュメント：https://grafana.com/docs/pyroscope/latest/

継続的プロファイリング — CPU、メモリ、割り当て、ミューテックスの競合、ゴルーチンのフレームグラフです。

前提条件

• Pyroscope サーバー（OSS）または Grafana Cloud Profiles のエンドポイント
• Cloud の場合：数値形式の Pyroscope ユーザー（スタック 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 に POST し、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 コンポーネントが BPF エラーで unhealthy になる → カーネルが 5.8 未満か、BTF がありません。ls /sys/kernel/btf/vmlinux を実行してください
• Cloud へのプッシュで 401 が返る → basic_auth_username が誤っています（slug ではなく、数値形式のスタック ID が必要です）
• プロファイルは表示されるものの、フレームがない → Java の場合は PYROSCOPE_FORMAT=jfr を設定してください。Alpine 上の Python の場合は、procfs と glibc の互換性を確認してください

リソース

• Pyroscope ドキュメント
• Grafana Cloud Profiles
• references/sdks.md — Java／Node／Ruby／.NET／Rust のインストール、設定、環境変数の表、プロファイルタイプの一覧
• references/ebpf-and-query.md — Alloy eBPF パイプライン全体と ProfileQL