investigating-replay

セッション録画の調査

ユーザーから「このセッションで何が起きましたか？」と聞かれたり、調査用の録画／セッション ID が提示されたりした場合は、ユーザーに個別に尋ねさせるのではなく、関連するコンテキストをすべて並行して収集します。

利用可能なツール

ツール	目的
posthog:session-recording-get	録画のメタデータ（期間、件数、ステータス）
posthog:persons-retrieve	人物プロフィール（プロパティ、個別 ID）
posthog:execute-sql	セッション内のイベント、エラー、ページビューをクエリ
posthog:query-error-tracking-issues-list	セッションに関連付けられたエラートラッキングの課題を検索
posthog:vision-observations-list	既存の Replay Vision AI 要約を確認
posthog:vision-observations-get	観測結果を完全な形式（scanner_result）で読み取る
posthog:vision-scanners-inline-scan	セッションの AI 要約を生成（低速、任意）
posthog:vision-scanners-list	保存済みの要約スキャナーを検索（scanner_type=summarizer）
posthog:vision-scanners-scan-session	保存済みの要約スキャナーをセッションで実行（低速）

ワークフロー

ステップ 1 — 録画のメタデータと人物プロフィールを取得する

録画から始めて、メタデータと人物の個別 ID を取得します。

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

録画の id とイベントの $session_id は同じ値です。ここでは録画を選択し、ステップ 2 では同じセッションのイベントを選択します。レスポンスには、distinct_id、person、start_time、end_time、期間、インタラクション数、コンソールエラー数、視聴ステータスが含まれます。distinct_id を使って完全な人物プロフィールを取得します。

posthog:persons-retrieve
{
  "id": "<person_uuid_from_recording>"
}

ステップ 2 — 同じセッションのイベントをクエリする

ステップ 1 で取得した録画の id を $session_id の値として使います。セッション中にユーザーが行った操作のタイムラインを取得します。

posthog:execute-sql
SELECT
    timestamp,
    event,
    properties.$current_url AS url,
    properties.$browser AS browser,
    properties.$os AS os,
    properties.$device_type AS device_type,
    properties.$screen_width AS screen_width
FROM events
WHERE $session_id = '<session_id>'
ORDER BY timestamp ASC
LIMIT 200

イベント数が多いセッションでは、特に有用なイベントに絞り込みます。

posthog:execute-sql
SELECT
    timestamp,
    event,
    properties.$current_url AS url,
    if(event = '$exception', properties.$exception_values[1], null) AS exception_message,
    if(event = '$exception', properties.$exception_types[1], null) AS exception_type
FROM events
WHERE $session_id = '<session_id>'
    AND event IN ('$pageview', '$pageleave', '$autocapture', '$exception', '$rageclick')
ORDER BY timestamp ASC
LIMIT 100

行が返されない場合？イベントのセッション ID を特定する

録画の id がセッション ID です。行が返されない場合、セッションのイベントはその ID なしで取り込まれています。リプレイイベントのクエリと同様に、録画の時間範囲に前後 100 秒を加えて、人物のイベントから候補を探します。person_id は、その人物のすべての個別 ID を対象にします。

posthog:execute-sql
SELECT
    properties.$session_id AS session_id,
    count() AS event_count,
    min(timestamp) AS first_seen,
    max(timestamp) AS last_seen
FROM events
WHERE person_id = '<person_uuid>'
    AND timestamp >= toDateTime('<start_time>') - INTERVAL 100 SECOND
    AND timestamp <= toDateTime('<end_time>') + INTERVAL 100 SECOND
    AND properties.$session_id IS NOT NULL
GROUP BY session_id
ORDER BY event_count DESC
LIMIT 10

セッション ID が明確に一致する場合に限り、先へ進みます。その ID はステップ 2 とステップ 3 のクエリでのみ使います。リプレイ URL とすべての Replay Vision 呼び出しには、録画の id を使います。

ステップ 3 — 関連付けられたエラートラッキングの課題を確認する

録画にコンソールエラーや例外がある場合は、関連するエラートラッキングの課題を検索します。

posthog:execute-sql
SELECT DISTINCT
    properties.$exception_fingerprint AS fingerprint,
    properties.$exception_types[1] AS type,
    properties.$exception_values[1] AS message,
    count() AS occurrences
FROM events
WHERE $session_id = '<session_id>'
    AND event = '$exception'
GROUP BY fingerprint, type, message
ORDER BY occurrences DESC
LIMIT 10

フィンガープリントが見つかった場合は、対応するエラートラッキングの課題を検索し、リンクとステータスを提示します。

posthog:query-error-tracking-issues-list
{
  "searchQuery": "<exception_type or message>"
}

ステップ 4 — 調査結果をまとめる

調査結果を一貫した説明として提示します。

1. 誰が — 人物のプロパティ（名前、メールアドレス、国、プランなど）
2. 何をしたか — 訪問したページの順序と実行した主要な操作
3. 問題 — 例外、コンソールエラー、レイジクリックとその頻度
4. 関連する課題 — 関連付けられたエラートラッキングの課題とそのステータス（アクティブ／解決済み）
5. コンテキスト — セッションの期間、デバイス／ブラウザー、アクティビティスコア

オプション：Replay Vision による AI 要約

イベントを手動で読み進めずに、より詳しい分析をユーザーが希望する場合は、Replay Vision による要約を提案してください。「確認してからスキャン」の手順に従います。むやみにスキャンしないでください。スキャナーが観測できるのは、指定されたセッションにつき一度だけです。

1. 既存の要約を確認します。 スケジュールされたスキャナーが、すでに要約を作成している場合があります。

   posthog:vision-observations-list
   {
     "session_id": "<session_id>"
   }
   

   結果の行は id、session_id、status、summary_line、scanner_id に絞られます。status が succeeded のものを探し、その id を指定して vision-observations-get で全文を読みます。scanner_snapshot.scanner_type で summarizer かどうかがわかり、scanner_result.model_output には title、summary、intent、outcome、friction_points、keywords が含まれます。見つかったら完了です。新たなスキャンは不要です。

2. 組み込みの要約をインラインスキャンして、要約を生成します。プレイヤーの「Summarize」ボタンと同じスキャンが実行されるため、どちらかが開始した要約は共有されます。一方、独自のプロンプトを使うと、別のスキャナーと別の要約が作成されます。

   posthog:vision-scanners-inline-scan
   {
     "session_ids": ["<session_id>"],
     "built_in": "summarize_recording"
   }
   

   サーバーのデフォルトが適用されるよう、model は指定しません。これは非同期処理で、数分かかること（ラスター化＋LLM）をユーザーに伝えてください。スケジュールは設定されず、後片付けも不要です。インラインスキャンで作成されたスキャナーは、自動で再実行されることはありません。ここで 400 が返される場合、通常は組織が AI によるデータ処理をまだ承認していません。

3. ポーリングする前に results[0].scan_outcome を読みます。started はポーリングを意味します。新しい観測が succeeded になるまで、vision-observations-list（手順 1）をポーリングしてください。already_scanned は、すでに終了状態の観測が存在することを意味します。手順 1 で読み取り、ステータスが failed または ineligible の場合は、ポーリングせずにその旨を伝えてください。scan_id が null の場合や skipped_quota の場合は、何も実行されていません。クォータを報告し、ポーリングしないでください。

プロジェクトにすでに summarizer スキャナーがある場合

その場合でも、単発の要約にはインラインスキャンを使います。保存済みスキャナーを使うのは、ユーザーが組み込みのプロンプトではなく、そのスキャナー独自のプロンプトを希望する場合に限ります。

posthog:vision-scanners-list
{
  "scanner_type": "summarizer"
}

スキャナー（名前＋プロンプト）をユーザーに提示し、どれを使うか確認してから、セッションに対して実行します。観測が succeeded になるまで vision-observations-list をポーリングしてください。

posthog:vision-scanners-scan-session
{
  "id": "<scanner_id>",
  "session_id": "<session_id>"
}

1 つの質問に答えるためだけに、スキャナーを作成してはいけません。vision-scanners-create は、インラインスキャンでは発生しない、スケジュール済みのスイープを残します。

ヒント

• 可能であれば、手順 1～3 を並行して実行してください。これらは独立したクエリです。
• 記録されたイベントがごく少ない場合、セッションは非常に短かった可能性があります。何かが壊れていると示唆するのではなく、その旨を伝えてください。
• 記録のメタデータにあるコンソールエラー数は、例外を詳しく調べるべきかどうかを判断する良い手がかりです。0 の場合は手順 3 を省略してください。
• 記録の start_url はユーザーの行動の始点を示します。これを使って説明の流れを組み立ててください。
• 記録の person が null の場合、ユーザーは匿名です。人物プロパティは利用できませんが、イベントは引き続き確認できます。

関連スキル

• finding-sessions-to-watch — まず、調査する価値のあるセッションを選ぶ
• finding-replay-for-issue — エラートラッキングの課題を起点に、関連する記録を探す
• diagnosing-missing-recordings — 存在するはずの記録が見つからない場合に使う
• creating-replay-vision-scanners — この種の監視を、スケジュールされたスキャナーとして自動化する