mcpField
D
debugging-local-replay

debugging-local-replay

github.com/posthog開発95126 回インストール1 日前に更新
リポジトリ

debugging-local-replay について

ローカル環境のPostHogセッションリプレイを調査する開発者向けのトラブルシューティングスキルです。録画が始まらない、一覧に表示されない、再生が止まるといった問題をパイプラインに沿って切り分けます。

主な機能

  1. 01パイプラインに沿った障害調査
  2. 02ブラウザーのリクエストと設定の確認
  3. 03ローカルサービスとポートの確認
  4. 04Kafkaのイベントフロー確認
  5. 05SeaweedFSの稼働確認

活用シーン

  1. 01ローカル画面に録画が表示されない場合
  2. 02再生がバッファリング中のまま止まる場合
  3. 03録画リクエストは成功するが一覧に出ない場合

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/posthog/ai-plugin --skill debugging-local-replay

インストール後、Claude Code で/debugging-local-replayを入力して読み込まれたか確認します。

同梱ファイルreferences/common-failures.md

詳細

ローカルセッションリプレイのデバッグ

開発者から「ローカルリプレイが動作しない」または「録画が表示されない」と言われた場合は、 以下のレイヤーを順番に確認してください。 ローカルリプレイのパイプラインには複数の要素があり、障害は通常、何も表示されずに発生します。

症状のクイックガイド

症状考えられる原因
Network タブに /s の呼び出しがないSDK が記録していない — トリガー、設定、またはレコーダースクリプトの問題（ステップ 1）
/s の呼び出しは 200 を返すが、一覧に録画がない取り込みパイプラインの障害 — capture-replay、Kafka、または ingestion-sessionreplay（ステップ 2〜3）
録画は一覧に表示されるが、再生が「Buffering...」で止まるrecording-api（ポート 6741）が起動していない（ステップ 2）
コンソールにレコーダースクリプトの MIME タイプまたは CORS エラーが表示されるフロントエンドのビルドが古い — pnpm build + pnpm copy-scripts が必要（ステップ 1）

ローカルリプレイのパイプライン

Browser SDK  →  /s endpoint (Caddy proxy :8000)
             →  capture-replay (Rust, :3306)
             →  Kafka (session_recording_snapshot_item_events topic)
             →  ingestion-sessionreplay (Node, :6740, PLUGIN_SERVER_MODE=recordings-blob-ingestion-v2)
             →  SeaweedFS (blob storage, :8333)
             →  recording-api (Node, :6741, PLUGIN_SERVER_MODE=recording-api)
             →  Frontend

このチェーンのどこかで問題が起きると、UI に録画が表示されなくなります。 診断では、チェーンのどこで問題が起きているかを特定します。

ステップ 1 — SDK はそもそも記録しようとしているか？

開発者にブラウザーの DevTools の Network タブを開いて、/s でフィルターするよう依頼してください。

/s の呼び出しがまったくない場合： SDK は録画データを送信しようとしていません。クライアント側の原因を調査してください。

  • プロジェクト設定でトリガーが設定されています。 URL トリガー、イベントトリガー、またはリンクされたフラグのトリガーが設定されている場合、トリガーが発動するまで記録は開始されません。トリガー機能をテストしていた開発者の場合、これが最もよくある原因です。ローカル UI のセッションリプレイ設定（Project settings > Session replay）を確認してください。記録を開始できるよう、トリガーを削除するか調整してください。
  • プロジェクト設定で記録が無効になっています。 セッションリプレイがオフになっている可能性があります。
  • サンプルレートが低すぎます。 $replay_sample_rate が 1.0 未満の場合、セッションがサンプリング対象外になることがあります。
  • SDK が記録を有効にして初期化されていません。 ローカルアプリの PostHog 初期化を確認してください。 session_recording が明示的に無効化されていてはいけません。
  • PostHog のホストが間違っています。 ローカルアプリは http://localhost:8000（またはローカルの Caddy プロキシが実行されている場所）を指定する必要があります。
  • 広告ブロッカー。 ローカル開発環境でも、ブラウザー拡張機能がレコーダースクリプトや /s エンドポイントをブロックすることがあります。
  • レコーダースクリプトの読み込みに失敗しました（MIME タイプ / CORS エラー）。 ブラウザーコンソールに、posthog-recorder.js に対する MIME type ('text/html') is not executable や、lazy-recorder.js に対する CORS エラーが表示されることがあります。これは、Django が JS ファイルの代わりに HTML ページ（通常はログインリダイレクト）を配信していることを意味します — 静的レコーダースクリプトが古いか、見つかりません。 レコーダースクリプトのビルド失敗を参照してください。

/s の呼び出しがあり、200 レスポンスが返される場合： SDK は記録を行っており、capture はデータを受信しています。問題は下流にあります — ステップ 2 に進んでください。

/s の呼び出しでエラー（4xx/5xx）が返される場合： capture サービスが停止しているか、設定に問題がある可能性があります。phrocs の capture-replay を確認してください。

ステップ 2 — 必要なプロセスは実行されていますか？

以下の phrocs プロセスが実行中で、正常であることを確認してください。 tsx watch src/index.ts の後に一度も出力がない「実行中」のプロセスは、事実上停止しています。

主要なプロセスとポート
プロセスポート処理内容
capture-replay3306/s を受信し、Kafka に書き込む Rust サービス
ingestion-sessionreplay6740Kafka から録画データを処理する Node コンシューマー
recording-api6741フロントエンドにリプレイデータを提供する Node サービス

次のコマンドで確認します。

lsof -nP -i :3306 -i :6740 -i :6741

ポートがリッスンしていない場合： プロセスが起動していないか、停止しています。よくある障害を参照してください。

ポートがリッスンしている場合： パイプラインのプロセスは実行中です。ステップ 3 に進んでください。

Docker の依存関係

次の Docker コンテナが実行中で、正常な状態である必要があります。

コンテナ用途
posthog-kafka-1録画イベント用のメッセージバス
posthog-db-1メタデータ用の Postgres
posthog-redis7-1状態管理用の Redis
posthog-clickhouse-1セッションデータ用の ClickHouse
seaweedfs-main録画データ用の Blob ストレージ

次のコマンドで確認します。

docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "kafka|db|redis7|clickhouse|seaweed"

seaweedfs を除き、すべて (healthy) と表示されるはずです。seaweedfs にはヘルスチェックがありません。 seaweedfs-main が見つからない場合は、replay Docker プロファイルが有効になっていない可能性があります。 docker-compose phrocs プロセスの出力で --profile replay を確認してください。

ステップ 3 — Kafka を通じてデータが流れていますか？

capture-replay が実行中で、/s 呼び出しを受信している場合、データは Kafka トピック session_recording_snapshot_item_events に書き込まれるはずです。Kafka UI （debug_tools intent が有効な場合は http://localhost:8080）で確認するか、kcat を使用してください。

kcat -b localhost:9092 -t session_recording_snapshot_item_events -C -c 5 -e

トピックが空、または存在しない場合： capture-replay が Kafka に書き込んでいません。Kafka 接続エラーがないか、capture-replay の phrocs ログを確認してください。

トピックにデータがあるのに録画が表示されない場合： ingestion-sessionreplay がデータを消費していません。停止中またはクラッシュしていないか、孤立したプロセスがコンシューマーグループを保持していないか確認してください（「よくある障害」を参照）。

ステップ 4 — SeaweedFS を確認する

取り込み処理は録画の Blob を SeaweedFS に書き込みます。アクセスできることを確認してください。

curl -s http://localhost:8333/ | head -5

SESSION_RECORDING_V2_S3_ENDPOINT 環境変数が正しく設定されている必要があります。 bin/start では、デフォルトで http://seaweedfs:8333（Docker ホスト名）に設定されています。 ホスト上のプロセスは Docker ネットワーク経由でこのホスト名を解決します。

よくある障害の参照先

詳しい診断については、よくある障害を参照してください。

  • Kafka コンシューマーグループを保持している孤立した Node プロセス
  • bin/wait-for-docker で停止しているプロセス
  • クラッシュを通知せずに握りつぶす tsx watch
  • Docker とホスト上のプロセス間のポート競合
  • 起動時の Cargo ビルドロックの競合

コメント

Markdown 対応