diagnosing-missing-recordings

セッション録画が見つからない場合の診断

ユーザーから「なぜこのセッションは録画されなかったのですか？」や「録画が一つもないのはなぜですか？」と聞かれた場合は、 以下のワークフローに沿って原因を体系的に診断してください。

利用可能なツール

ツール	用途
posthog:execute-sql	診断に役立つシグナルを得るため、セッションイベントのプロパティを照会します
posthog:session-recording-get	セッションの録画が実際に存在するかを確認します
posthog:query-session-recordings-list	条件に一致する録画を検索します

診断シグナル

PostHog SDK は、録画の状態を説明する診断プロパティをすべてのイベントに出力します。 一覧については、診断シグナルのリファレンスをご覧ください。

主なシグナルは次のとおりです。

• $has_recording — PostHog にセッションの録画が保存されているかどうか
• $recording_status — SDK の状態：active、buffering、disabled、sampled、paused
• $session_recording_start_reason — 録画が開始された、または開始されなかった理由
• $sdk_debug_recording_script_not_loaded — 録画スクリプトがブロックされている（広告ブロッカー）
• $sdk_debug_replay_*_trigger_status — トリガーの状態（URL、イベント、リンク済みフラグ）
• $replay_sample_rate — キャプチャ時に設定されていたサンプルレート

ワークフロー

ステップ 1 — 録画が存在するか確認する

ユーザーがセッション ID を指定した場合は、まず録画が実際に存在するか確認します。

posthog:session-recording-get
{
  "id": "<session_id>"
}

recording_not_found という理由で found: false が返された場合、アクティブなプロジェクトにはこのセッションの録画が存在しません。 原因を診断するため、ステップ 2 に進みます。 録画のメタデータが返された場合、録画は存在します。問題はキャプチャではなく、UI またはフィルタリングにある可能性が高いです。 それ以外のエラー（たとえば、プロジェクトが見つからない、または権限エラー）は、録画の有無を示すものではありません。 まずそのエラーを解決してください。

ステップ 2 — イベントから診断シグナルを照会する

セッションの最新イベントを照会し、SDK の診断プロパティを取得します。

posthog:execute-sql
SELECT
    properties.$has_recording AS has_recording,
    properties.$recording_status AS recording_status,
    properties.$session_recording_start_reason AS start_reason,
    properties.$sdk_debug_recording_script_not_loaded AS script_not_loaded,
    properties.$sdk_debug_replay_url_trigger_status AS url_trigger,
    properties.$sdk_debug_replay_event_trigger_status AS event_trigger,
    properties.$sdk_debug_replay_linked_flag_trigger_status AS flag_trigger,
    properties.$replay_sample_rate AS sample_rate,
    properties.$sdk_debug_replay_internal_buffer_length AS buffer_length,
    properties.$sdk_debug_replay_flushed_size AS flushed_size,
    properties.$lib AS sdk_library,
    properties.$lib_version AS sdk_version
FROM events
WHERE $session_id = '<session_id>'
ORDER BY timestamp DESC
LIMIT 1

ステップ 3 — 判定を診断する

シグナルの解釈には、診断ロジックのリファレンスを使用します。 判定結果は優先度の高い順に次のとおりです。

1. 録画あり（$has_recording = true）— 録画はキャプチャされています。問題は別の箇所にあります
2. 広告ブロッカーによるブロック（スクリプト）（$sdk_debug_recording_script_not_loaded = true）— ブラウザー拡張機能が録画スクリプトの読み込みをブロックしています
3. 無効（$recording_status = 'disabled'）— 設定または SDK の構成でリプレイが無効になっています
4. トリガー待機中（トリガーの状態が trigger_pending で、一致したものがない）— 一度も発火しなかったトリガーが録画開始の条件になっています
5. サンプル対象外（$session_recording_start_reason = 'sampled_out'）— サンプルレートにより除外されています
6. バッファリング中で空（$recording_status = 'buffering'、バッファー長 = 0、フラッシュなし）— 初期化されていますが、スナップショットは生成されていません
7. フラッシュがブロックされている（イベントをまたいでバッファー長が増加している一方、flushed_size は 0 のまま）— スナップショットは生成されていますが、/s/ 取り込みエンドポイントが広告ブロッカーまたは設定ミスのあるリバースプロキシによってブロックされています。これを検出するには、セッションのイベントを通じた推移を照会する必要があります。examples.md の例 3をご覧ください
8. 不明 — シグナルが既知のパターンに一致しません

ステップ 4 — プロジェクト単位の設定を確認する（セッション ID がない場合）

ユーザーがプロジェクト全体で録画が見つからないと問い合わせた場合（特定のセッションが指定されていない場合）は、 最近のセッションを照会して、傾向を確認します。

posthog:execute-sql
SELECT
    $session_id,
    properties.$recording_status AS recording_status,
    properties.$session_recording_start_reason AS start_reason,
    properties.$sdk_debug_recording_script_not_loaded AS script_not_loaded,
    properties.$replay_sample_rate AS sample_rate
FROM events
WHERE event = '$pageview'
    AND timestamp > now() - INTERVAL 1 DAY
GROUP BY
    $session_id,
    recording_status,
    start_reason,
    script_not_loaded,
    sample_rate
ORDER BY max(timestamp) DESC
LIMIT 10

次のような傾向を確認します。

• すべてが disabled → プロジェクト設定でリプレイが無効になっています
• サンプルレートが低く、すべてが sampled_out → サンプルレートが厳しすぎます
• すべてが script_not_loaded → 1 人のユーザーの広告ブロッカーではなく、CSP またはデプロイの問題である可能性が高いです
• 状態が混在している → セッションごとの問題です。詳細を調べてください

ステップ 5 — 実行可能な推奨事項を提示する

判定に基づいて、具体的な対応を推奨します。

判定	推奨事項
広告ブロッカーによるブロック	ユーザーのブラウザー拡張機能が rrweb をブロックしています。広告ブロッカーを無効にして試すか、レコーダースクリプトにプロキシまたはカスタムドメインを使用するよう提案します
無効	プロジェクトのリプレイ設定を確認します。記録がオフになっている可能性があります。設定 > セッションリプレイへのリンクを案内します
トリガー待機中	設定されたトリガー（URL パターン、イベント、またはフィーチャーフラグ）に一致しませんでした。トリガーの設定を見直します
サンプリング対象外	プロジェクト設定でサンプルレートを上げるか、トリガーを使用して重要なセッションが確実に記録されるようにします
バッファーが空	最初のスナップショットが記録される前にページが閉じられました。非常に短いセッションや、単一ページへのナビゲーションでよく発生します。最小時間を短くすることを検討します
不明	トラブルシューティングドキュメント（https://posthog.com/docs/session-replay/troubleshooting）をユーザーに案内します

例

実際の診断例では、シグナルの組み合わせが判定にどう結び付くかを確認できます。クエリ結果の解釈を調整する際に参考にしてください。

ヒント

• $lib_version が非常に古い場合、一部の診断シグナルは存在しません。 ユーザーにその旨を伝えてください。SDK をアップグレードすると、より適切な診断ができるようになります。
• セッションにイベントがあっても、保持期間のために記録が削除されている場合、記録が残っていないことがあります。 セッションのタイムスタンプをプロジェクトの保持期間と照らし合わせて確認します。
• $has_recording が true なのにユーザーが記録を見つけられない場合、再生時間、アクティビティのしきい値、またはプレイリストのフィルターによって除外されていないか確認します。

関連スキル

• diagnosing-sdk-health — SDK が古いことはよくある根本原因であり、診断シグナルも不十分になります
• finding-sessions-to-watch — 記録が機能したら、視聴する価値のあるセッションを選びます
• investigating-replay — 記録が存在する場合に分析します