linking-errors-to-traces

エラーをトレースやログに関連付ける

共通の ID を使ってレコードを関連付けます。サービスと時刻が一致しても、ログやスパンがエラーに属する証拠にはなりません。

例外を見つける

イシュー ID または URL がある場合は、include: ["exception", "correlation"]、filterTestAccounts: false、小さな limit を指定して posthog:query-error-tracking-issue-events を呼び出します。ユーザーが複数件を求めていない限り、発生例を 1 件選びます。結果がサンプルである場合は、その旨を伝えます。

発生例 ID またはセッション ID がある場合は、正確な検索方法について finding-exceptions.md を読みます。指定があれば、ユーザーの時間範囲を使います。イベントが見つからなかった場合は、確認した時間範囲を明記します。範囲が限定された検索に基づいて、イベントが一度も存在しなかったと断言してはいけません。

ID をたどる

1. リプレイ： イベントに $session_id がある場合は、その ID を指定して posthog:session-recording-get を呼び出します。found: false は録画が見つからなかったことを意味しますが、エラーやセッションが存在する可能性はあります。録画が存在する場合は、/replay/{id} を指定して posthog:generate-app-url を使います。
2. 正確なトレース： 一意でゼロではない 32 文字の 16 進数 $trace_id ごとに、その ID と excludeAttributes: true を指定して posthog:apm-trace-get を呼び出します。トレースへのリンクには _posthogUrl を使います。イベントに $span_id がある場合は、返されたスパン ID と大文字・小文字を区別せずに 16 進数として比較します。結果が空の場合は、そのトレース ID に該当する保持済みスパンが見つからなかったことを意味します。ログは存在する可能性があります。
3. セッションのトレース候補： イベントに $trace_id がなく、ユーザーがセッションのトレースについて尋ねている場合は、posthog:apm-attributes-list を使って、セッション ID を格納するスパン属性を探します。明確なキーが見つかった場合は、正確な span_attribute フィルター、エラー前後の短い時間範囲、flatSpans: true、小さな limit を指定して posthog:query-apm-spans を呼び出します。これにより、ルートスパンだけでなく、一致する子スパンも見つかります。リンクが必要な候補については posthog:apm-trace-get を呼び出します。これらはセッション一致として明記します。時刻だけでは、どのリクエストがエラーを起こしたかは証明できません。
4. 同一トレースのログ： イベントにトレース ID がある場合は、範囲を限定したサービス検索と正確なログフィルターについて finding-trace-logs.md を読みます。info を含むすべての重大度を対象にします。スパンが保持されていなくても、トレースにログが存在することがあります。

イシュー ID がわかっている場合は、/error-tracking/{id} を指定して posthog:generate-app-url を使います。PostHog のリンクを手作業で作成してはいけません。

結果を報告する

確認した発生例ごとに、エラーの時刻、照合に使った ID、利用可能な場合はイシュー、リプレイ、保持済みトレースへのリンクを示します。一致したログは、時刻と重大度を添えて要約します。ログの抜粋から、秘密情報や不要な個人データを除外します。

該当しない項目はそれぞれ個別に明記します。イベントにトレース ID がない、トレース ID はあるが保持済みスパンがない、スパンにセッション属性がない、録画がない、または確認した時間範囲内にそのトレース ID のログがない、といった項目です。セッション ID で一致したスパンは、正確なトレース ID またはスパン ID でエラーと関連付けられるまでは候補です。検索を完全なものにできなかった行数上限や時間範囲があれば明記します。検索に失敗した場合は、一致するデータがないと報告するのではなく、結果は不明であると伝えます。