monitoring-capture-service

Grafana MCP でキャプチャサービスを監視する

キャプチャサービス (rust/capture/) は、PostHog の Rust 製 HTTP インジェストエンドポイントです。 SDK からイベントを受信し、クォータ/レート制限を適用して、Kafka にプロデュースします。 5 つのデプロイメントが、それぞれ異なる CAPTURE_MODE 設定で同じバイナリを実行しており、各デプロイメントは独自の K8s 名前空間にあります。

このスキルでは、コードの進化に伴って変化するメトリクス名を暗記するのではなく、Grafana MCP ツールを使ってライブメトリクスを発見する方法を学びます。

環境コンテキスト

Grafana MCP は、単一の Grafana インスタンスに接続されており、1 つの環境にスコープされています。 ユーザーが指定していない場合は、どの環境を調査したいかを尋ねてください:

• prod-us — 米国本番環境 (us-east-1)
• prod-eu — EU 本番環境 (eu-central-1)

ほとんどのキャプチャアプリのメトリクス (例: capture_*、http_requests_*、envoy_cluster_*) は、 接続している Grafana に応じて環境固有です。つまり、environment ラベルを持ちません。MSK および CloudWatch のメトリクスは environment ラベルを持ちますが、 それでも接続している Grafana の AWS アカウントにスコープされています。

環境間の比較には Grafana インスタンスの切り替えが必要です (1 つのセッションでは不可能です)。

オブザーバビリティの全体像

キャプチャは 7 つのテレメトリドメインにまたがっています。 それぞれに Grafana データソースと検出エントリポイントがあります。

ドメイン	データソース UID	検出ツール	スコープフィルター
アプリメトリクス (VictoriaMetrics)	victoriametrics	list_prometheus_metric_names	regex: "capture_.*"
アプリメトリクス (リアルタイム)	victoriametrics-realtime	同上	同上 (保持期間は短く、解像度は高い)
ログ	P44D702D3E93867EC (Loki-logs)	list_loki_label_names	app=~"capture.*"
プロファイリング	pyroscope	list_pyroscope_profile_types	service_name="capture-analytics/capture-analytics"
ダッシュボード	n/a	search_dashboards	クエリ "capture" または "ingestion"
CloudWatch (ElastiCache, MSK)	P034F075C744B399F	query_prometheus	environment="prod-us"
CloudWatch Root (prod-us のみ)	PAAE47F430CFD1449	同上	ルートアカウントの AWS メトリクス (prod-eu には存在しません)

安定したウェイポイント

これらの事実はめったに変化せず、動的に発見するのが困難です。

デプロイメントの役割

各キャプチャバリアントは、それぞれ独自の namespace 内で個別の K8s デプロイメントとして実行されます。 主なスコープラベルは namespace と container です（role ではありません — このラベルには Pod 名が含まれており、フィルタリングには役立ちません）。

Deployment	Namespace	capture_mode	Pipeline	Notes
capture-analytics	capture-analytics	events	メインイベント	最も量が多い。/e、/i/v0/e などをルーティングします
capture-ai	capture-ai	events	AI/LLM イベント	/i/v0/ai をルーティングします。OTel はポート 4318 で待ち受けます
capture-replay	capture-replay	recordings	セッション録画	/s/ をルーティングします。CAPTURE_MODE=recordings
capture-mirrored	capture-mirrored	events	ミラー/カナリア	常に実行されているわけではありません。analytics と同じメトリクスです
capture-logs	capture-logs	—	ログ取り込み	OTel ログはポート 4318 で待ち受けます

すべてのバリアントは同じ Rust バイナリ（ghcr.io/posthog/posthog/capture）を共有しています。

キャプチャメトリクスのスコープは namespace=~"capture-.*" または container=~"capture-.*" で指定します。 単一のパイプラインの場合は、namespace でスコープを指定します（例: namespace="capture-analytics"）。

Envoy クラスタの命名

Envoy メトリクスは、上流のバックエンドを識別するために envoy_cluster_name を使用します。 パターン: posthog_{deployment}_{port}。

キャプチャ関連のクラスタ: posthog_capture-analytics_3000、posthog_capture-ai_3000、posthog_capture-replay_3000、 posthog_capture-mirrored_3000、posthog_capture-logs_4318、posthog_capture-logs-canary_4318。

capture-replay には、KEDA オートスケーリングで使用される proxy-as-a-service クラスタもあります: proxy-as-a-service_capture-replay_3000。

スコープの指定: envoy_cluster_name=~"posthog_capture-.*"。

Redis インスタンスのトポロジー

キャプチャは最大 3 つの論理 Redis インスタンスに依存し、 さらに Envoy レイヤーに 1 つの外部インスタンスがあります（キャプチャバイナリには含まれません）。 いずれも capture_redis_* メトリクスを出力しません — Redis の健全性はキャプチャ側の メトリクスと CloudWatch ElastiCache メトリクスから推測されます。

1. プライマリ Redis（REDIS_URL 環境変数）

• ElastiCache: posthog-solo（prod-us）または posthog-prod-redis-encripted（prod-eu、原文ママ — 実際のクラスタ名のタイポ）
• 両環境ともトークンキャッシュには読み取り専用エンドポイントを使用（REDIS_READER_URL）
• 支えるもの: 請求/クォータ制限（CaptureQuotaLimiter）、セッションリプレイのオーバーフローリミッター
• キャプチャメトリクス: capture_billing_limits_loaded_tokens（cache_key 別）、 capture_quota_limit_exceeded（resource 別）
• クォータリソース: events、exceptions、llm_events、recordings、survey_responses
• キャッシュキー: @posthog/quota-limits/{resource}、@posthog/capture-overflow/replay

2. グローバルレートリミッター Redis（GLOBAL_RATE_LIMIT_REDIS_URL、任意）

• ElastiCache: capture-globalratelimit-{env}-redis（prod-us、prod-eu、dev にはなし）
• 支えるもの: (token, distinct_id) 単位のスライディングウィンドウレートリミッター
• URL が未設定の場合はプライマリ Redis にフォールバック
• 任意の読み取りレプリカ: GLOBAL_RATE_LIMIT_REDIS_READER_URL
• トグル: GLOBAL_RATE_LIMIT_ENABLED（ロールアウト中は一部の環境でオフの場合あり）
• メトリクス: global_rate_limiter_*（直接）、capture_events_rerouted_overflow{reason="rate_limited"}（プロキシシグナル）
• global_rate_limiter_window_seconds{scope} は各プロセスのウィンドウを公開します。capture-analytics と capture-ai は AI バイトバジェットを共有するため、このゲージで両者が一致しない場合、共有バジェットが分裂しています
• CloudWatch クラスタ ID: capture-globalratelimit-prod-redis

3. イベント制限 Redis（EVENT_RESTRICTIONS_REDIS_URL）

• ElastiCache: ingestion-prod-redis（両環境で別個の書き込み可能クラスタ）
• Django から同期された取り込み制限設定を保存
• URL が未設定の場合はプライマリ Redis にフォールバック
• キャプチャメトリクス: capture_event_restrictions_redis_fetch（ラベル: restriction_type、 result は success/not_found/error/parse_error）、 capture_event_restrictions_stale、capture_event_restrictions_loaded_count

4. Contour レート制限 Redis（ratelimit-{env}-redis） — キャプチャバイナリには含まれません

• キャプチャの前段にある Envoy イングレスレイヤーでの IP 単位の DoS 対策
• メトリクス: ratelimit_service_*（ラベル: domain="posthog"）

メトリクスのプレフィックス

ここにあるすべてのプレフィックスは、list_prometheus_metric_names を使用して、datasourceUid: "victoriametrics" と regex: "<prefix>.*" を指定することでライブで検出できます。

プレフィックス	ドメイン	スコープラベル
capture_*	アプリメトリクス（約80メトリクス）	namespace, container
http_requests_*	HTTP レイヤー（共有）	namespace=~"capture-.*"
capture_kafka_*	Kafka プロデューサー（17メトリクス）	namespace, container
capture_billing_*	読み込まれた課金/クォータトークン	namespace, cache_key
capture_event_restrictions_*	イベント制限（6メトリクス）	namespace, restriction_type
capture_ai_otel_*	AI/OTel キャプチャ（12メトリクス）	namespace="capture-ai"
envoy_cluster_*	L7 プロキシ	envoy_cluster_name=~"posthog_capture-.*"
aws_msk_*	MSK ブローカー側（JMX）	environment="prod-us" または "prod-eu"
ratelimit_service_*	Contour レート制限	domain="posthog"
overflow_redirect_*	Node.js インジェストオーバーフロー（ダウンストリーム）	ingestion_pipeline
kube_* / container_*	K8s リソース	namespace=~"capture-.*", pod=~"capture-.*"

Kafka トピック

トピックはプロデュース先をキャプチャします（capture_kafka_produce_avg_batch_size_bytes の topic ラベルでライブ検出できます）。 パーティション数はトピック名にエンコードされており、環境ごとに異なります（EU は一般的にパーティション数が少なくなります）。

キャプチャはパイプラインに応じて 2 つの異なる Kafka バッキングシステム に書き込みます:

• MSK 取り込みクラスター — アナリティクスイベント（メイン、オーバーフロー、ヒストリカル、ターボ）、ヒートマップ、エラートラッキング、クライアント警告
• WarpStream — セッションリプレイ（warpstream-replay-v2 VC）、ログ（warpstream-logs VC）、トレース（warpstream-traces VC）

トピック (prod-us / prod-eu)	バッキング	パイプライン
ingestion-analytics-main-1024 / -512	MSK	メインイベント
ingestion-analytics-overflow-128	MSK	オーバーフロー（レート制限 / 高ボリュームトークン）
ingestion-analytics-historical-128	MSK	ヒストリカルバックフィルイベント
ingestion-analytics-turbo-1024	MSK	一般ターボ（prod-us のみ）
ingestion-heatmaps-main-128	MSK	ヒートマップ
ingestion-errortracking-main-128	MSK	エラートラッキング
ingestion-errortracking-overflow-32	MSK	エラートラッキングのオーバーフロー
ingestion-clientwarnings-main-16 / -32	MSK	クライアント警告
ingestion-sessionreplay-main-512 / -256	WarpStream	セッションリプレイ
ingestion-sessionreplay-overflow-64 / -32	WarpStream	セッションリプレイのオーバーフロー
ingestion-logs	WarpStream	ログの取り込み
ingestion-traces	WarpStream	トレースの取り込み
ingestion-analytics-main-dlq (+ パイプラインごとの DLQ トピック)	MSK	デッドレターキュー

Pyroscope サービス

サービス名	デプロイメント
capture-analytics/capture-analytics	メインキャプチャ
capture-ai/capture-ai	AI キャプチャ
capture-replay/capture-replay	リプレイキャプチャ
capture-mirrored/capture-mirrored	ミラー/カナリア（実行時）
capture-logs/capture-logs	ログキャプチャ

プロファイルタイプ: process_cpu:cpu:nanoseconds:cpu:nanoseconds, wall:wall:nanoseconds:wall:nanoseconds, memory:inuse_space:bytes:inuse_space:bytes, memory:inuse_objects:count:inuse_space:bytes.

Grafana ダッシュボード

UID	タイトル	用途
capture	Capture	キャプチャの各デプロイ全体の概要 — まずここから
capture-v1-details	V1 Details	v1 パイプライン (/i/v1/analytics/events) のパネルごとの詳細
ddfkdj56ds11xce	Legacy Details	レガシー v0 パイプライン (/e/、/batch/、/i/v0/e/) のパネルごとの詳細
ingestion-health	Ingestion - Health	サービス横断のインジェスション健全性
ingestion-analytics	Ingestion - Analytics	下流の分析パイプライン、レーンごと
ingestion-pipelines	Ingestion - Pipelines	エンドツーエンドのパイプラインスループットと遅延
ingestion-reliability	Ingestion - Reliability	インジェストされたイベントのトレンド、処理遅延の SLO、ポッドの再起動
ingestion-sessionreplay	Ingestion - Session Replay	セッションリプレイのインジェスション
contour	Contour Ingress	Envoy L7 プロキシ (envoy_cluster_name=posthog_capture-analytics_3000 を設定)
AWSRedis	AWS ElastiCache Redis	クラスターごとの CloudWatch Redis メトリクス (cacheclusterId でフィルター)

2 つの詳細ボードは Capture/Ingestion/ 配下にあり、互いにリンクし合い、 さらに概要ボードにもリンクしています。両方のパイプラインで共有される仕組み (Global Rate Limiter、Event restrictions、Hyper サーバー、Contour、billing/quota) のセクションは 両方 の詳細ボードに表示されるため、すでに開いている方を使用してください。

search_dashboards で見つかりますが、依存すべきではないボードが 1 つあります: capture-3000-envoy-codes は個人的な US 専用の Envoy 調査用ボードです (EU には 同期されていません)。

ディスカバリーワークフロー

Prometheus / VictoriaMetrics

1. list_prometheus_metric_names — datasourceUid: "victoriametrics"、regex: "capture_.*" でアプリメトリクスを列挙
2. メトリクスを選び、それにスコープした list_prometheus_label_names — 利用可能なディメンションを確認
3. list_prometheus_label_values — ラベルの実際の値を発見 (例: capture_events_dropped_total の labelName: "cause")
4. PromQL を使った query_prometheus — 常に namespace (または container) でスコープし、時間範囲を設定

Loki (ログ)

1. list_loki_label_names — datasourceUid: "P44D702D3E93867EC" (Loki-logs; 断続的に 502 を返すプライマリ Loki P8E80F9AEF21F6940 は使用しないでください)
2. app または namespace の list_loki_label_values — capture コンテナを見つける
3. query_loki_logs — 例: {app=~"capture.*"} |= "error"

Pyroscope (プロファイリング)

1. list_pyroscope_profile_types — data_source_uid: "pyroscope"
2. fetch_pyroscope_profile — matchers: '{service_name="capture-analytics/capture-analytics"}'、 profile_type: "process_cpu:cpu:nanoseconds:cpu:nanoseconds"

ダッシュボード

1. search_dashboards — "capture" または "ingestion" をクエリ
2. get_dashboard_by_uid — 既知の UID (例: "capture") を使ってパネルの詳細を取得
3. get_dashboard_panel_queries — 既存のパネルから PromQL を抽出

Redis / ElastiCache

• Capture 側: VictoriaMetrics で capture_billing_*、capture_event_restrictions_*、 capture_quota_* メトリクスを発見
• インフラストラクチャ: ElastiCache 用の CloudWatch データソース P034F075C744B399F (CPU、メモリ、接続数、レイテンシー)。 クラスター ID: capture-globalratelimit-prod-redis、posthog-solo (prod-us プライマリ)

主要なメトリクスドメイン

何を探すべきかのカテゴリです。上記のプレフィックスを使って、具体的なメトリクスをライブで発見してください。

HTTP レイヤー — リクエストレート、レイテンシ分布（p50/p99）、アクティブ接続数、 ステータスコード別のエラー率。メトリクス: http_requests_*（namespace でスコープ）、capture_active_connections。

イベントライフサイクル — 受信から取り込み、そしてドロップ/再ルーティングに至るファネル。 capture_events_received_total -> capture_events_ingested_total -> capture_events_dropped_total。 ドロップ時の cause ラベルには 20 以上の値があります（ライブで発見してください）。golden-chart 移行以降に追加された主なもの: event_restriction_drop、event_too_big、otel_quota_drop、oversize_event、 ai_opt_in、gathering、invalid_session、no_session_id、no_snapshot。 再ルーティング: capture_events_rerouted_overflow（reason ラベル付き） （rate_limited、force_limited、event_restriction）。 また: トピックリダイレクト制限用の capture_events_rerouted_custom_topic。

Kafka プロデューサー — ブローカー接続性（capture_kafka_any_brokers_down、 capture_kafka_broker_connected）、キューの飽和（_queue_depth / _queue_depth_limit）、 produce RTT（capture_kafka_produce_rtt_latency_us、quantile と broker 別）、 配信エラー（capture_kafka_produce_errors_total）。

請求とクォータ — capture_billing_limits_loaded_tokens（cache_key 別）、 capture_quota_limit_exceeded（resource 別: events、exceptions、llm_events、recordings、survey_responses）。

イベント制限 — Redis フェッチの健全性、鮮度、ロード済み件数、適用された制限（restriction_type 別）に関する capture_event_restrictions_* （drop_event、force_overflow、redirect_to_topic、skip_person_processing）。

Envoy プロキシ — アップストリームのレイテンシ、レスポンスコード（2xx/4xx/5xx）、接続の健全性、 サーキットブレーカー（_open ゲージ）、バックエンドのメンバーシップ（healthy と total）、 タイムアウト、リトライ。常にフィルタリング: envoy_cluster_name=~"posthog_capture-.*"。 capture-replay については、proxy-as-a-service_capture-replay_3000 も確認してください。

Contour レート制限 — IP ごとの DoS 保護用の ratelimit_service_*。 ratelimit_service_rate_limit_over_limit = 実際にレート制限されている IP。

MSK ブローカー側 — capture-analytics、capture-ai、その他の MSK ベースのトピック向けの aws_msk_* JMX メトリクス。 主要なシグナル: スロットル時間、ネットワークプロセッサのアイドル率、メモリプールの枯渇、リクエストキューサイズ。 両環境とも、イベントクラスターとは別に専用の取り込み MSKクラスターがあります （prod-us: c21、prod-eu: posthog-prod-eu-ingestion-2026-05-04）。

WarpStream — capture-replay、capture-logs、traces 向けの warpstream_agent_* メトリクス。 これらのパイプラインは MSK ではなく、クラスター内の WarpStream エージェントに produce します。 主要なシグナル: warpstream_agent_control_plane_operation_counter（operation 別）、 warpstream_agent_file_cache_client_fetch_local_or_remote_counter（キャッシュヒット/ミス率）。 ダッシュボード: warpstream（Agent Overview）、dbfj5c31spa1ogf（MSK vs WarpStream — Active Produce Topics）。 米国限定のパーソナルダッシュボード（EU には同期されません）: ws-coarse-lag-explore（Coarse Lag）、8e93b023-…（CH Consumer Lag）。 VC ごとの KMinion インスタンス: kminion-warpstream-replay、kminion-warpstream-logs、kminion-warpstream-traces。

K8s リソース — CPU、メモリ、再起動、HPA 状態に関する container_* と kube_*。 スコープ: namespace=~"capture-.*"、pod=~"capture-.*"。

調査プレイブック

よくある質問に対する手順別のワークフローについては、references/investigation-playbooks.md を参照してください: ヘルスチェック、イベント損失、レイテンシ、Kafka のバックプレッシャー、レート制限、Redis、環境間の比較。