Grafana Pyroscopeは継続的プロファイリング(Continuous Profiling)基盤で、アプリケーションのCPU・メモリ・I/Oの使用状況を関数・行レベルで可視化します。SDK・Grafana Alloy・OpenTelemetry eBPFプロファイラなど複数の経路からプロファイルデータを取り込み、サーバー側で保存・クエリして性能問題の原因箇所を特定できるようにします。v2アーキテクチャではオブジェクトストレージへ直接書き込む構成が既定になっています。
リポジトリは大きく`api/`(protoで定義されたgRPC/Connectサービス群)、`cmd/pyroscope`(サーバー本体)、`cmd/profilecli`(運用CLI)から構成されています。書き込み経路では、クライアントから送られたプロファイルがサービスごとにルーティングされ、ingesterやローカルディスクを介さずオブジェクトストレージへ直接書き込まれます。バックグラウンドではcompaction-workerが小さなセグメントを大きなブロックへ統合します。読み込み経路では、クエリがオブジェクトストレージ上のブロックへ分散して実行され、`phlaredb`パッケージのBlockQuerierなどがparquet形式の`profiles.parquet`「stacktraces.parquet」などを読み出し、Grafana Profiles Drilldownでフレームグラフとして表示されます。`cmd/profilecli/blocks.go`や`bucket.go`は、この保存済みブロックの一覧表示やオブジェクトストア閲覧用のWebツールを提供しており、内部データ構造が実際にどう保存されているかを外部から確認できます。設定は`dskit`ベースのフラグ・YAML(`.pyroscope.yaml`)で行われ、`Config.RegisterFlags`パターンがコード全体で使われています。
- STEP 01
`docker run -it -p 4040:4040 grafana/pyroscope`を実行すると、サーバーが起動しポート4040でHTTP待受を始める様子がログに出ます。
- STEP 02
ブラウザで`http://localhost:4040`を開くと、内蔵UIまたはプロファイル一覧の画面が表示されます(READMEにあるとおりGrafana Profiles Drilldownと連携するのが主な使い方です)。
- STEP 03
`go run ./cmd/pyroscope --target all,embedded-grafana`で単一プロセスに全コンポーネントを起動すると、Pyroscopeが4040番、埋め込みGrafanaが4041番で立ち上がります。
- STEP 04
`profilecli`をビルドして`blocks list`のようなサブコマンドを叩くと、`cmd/profilecli/blocks.go`のロジックに従い保存済みブロックのID・時間範囲・プロファイル件数などが表付きで出力されます。
- STEP 05
`bucket web-tool`系のコマンドを起動すると、`http://localhost:4201/ops/object-store/tenants`でテナントやブロックをブラウザから閲覧できるWeb UIが立ち上がります(`cmd/profilecli/bucket.go`のhandlers参照)。
- STEP 06
`make generate`を実行しないままprotoやconfigを変更すると、CIやlintで生成物との不整合を検出されるため、開発ルール(`.cursor/rules`)に従った再生成が必須になります。
サーバーを起動すればHTTPエンドポイント4040番でプロファイルの受信・保存・クエリが可能になり、Grafana Profiles Drilldown経由でフレームグラフを見られます。CLIの`profilecli`を使うと、実際に書き込まれたオブジェクトストレージ上のブロック(index.tsdb、profiles.parquetなど)の内容や件数を手元で確認できます。つまり「動いている継続的プロファイリング基盤」と「その内部データを検証できる運用ツール」の両方が手に入ります。
v2アーキテクチャはオブジェクトストレージへの直接書き込みが前提のため、ローカルファイルシステム以外(S3・GCS・Azure)を使う場合は`storage.backend`など追加設定が必要です。
フロントエンド開発には`ui/`ディレクトリでNode.jsとYarn 4が別途必要で、Dockerによるプロダクションビルド(`make frontend/build`)を経ないと`make build`が完了しません。
マルチテナント設計が前提のため、テナントIDの扱いを誤ると`.cursor/rules/go-backend.mdc`が警告するとおりデータ分離の問題が起きます。
READMEの説明とコード(v2の書き込み・コンパクション・読み込みパス)は整合していますが、v1からのアップグレードや移行手順の詳細は外部ドキュメントへのリンクに依存しており、本リポジトリ内だけでは完結しません。
継続的プロファイリングを既存のGrafanaスタック(Grafana Cloud・OSS)に組み込みたいチーム、あるいはCPU・メモリ・I/Oのボトルネックを行レベルで追いたい開発者に向いています。READMEのDockerコマンド1つで即座に起動できる手軽さと、`cmd/profilecli`という検証用CLIが同梱されている点から、実際に動かさなくても「保存形式(parquet+TSDBブロック)」「オブジェクトストレージ直書き」「compactionによる統合」という設計が一貫していることがソースから確認できます。大規模運用や本番導入を検討する場合は、対象のオブジェクトストレージ設定とマルチテナント運用ルールを事前に把握してから進めるのが安全です。