diagnosing-stacktrace-symbolication

スタックトレースのシンボリケーションの診断

シンボリケーションとは、JavaScript のソースマップ検索、Hermes の関数オフセット解決、Proguard／R8 の難読化解除、dSYM のアドレスから行への検索を横断して指す名称です。これらはいずれも、圧縮または難読化されたフレームを、読みやすいファイル、関数、行に変換します。

ユーザーのビルドと PostHog のシンボルセットを、ビルド設定 -> 生成されたシンボルアーティファクト（JavaScript ソースマップ、Hermes マップ、Proguard マッピング、または dSYM バンドル）-> PostHog にアップロードされたシンボルセット -> キャプチャされたエラーフレームというひとつのパイプラインとして順に確認します。この4つを順番に確認すれば、ほとんどの問題はすぐに明らかになります。

プラットフォーム

プラットフォーム	シンボルデータの種類	リファレンス
JavaScript / TypeScript web	source-and-map	javascript.md
React Native (Hermes)	hermes	近日公開
Android (Proguard / R8)	proguard	近日公開
iOS / macOS (dSYM)	apple-dsym	近日公開

ワークフローのステップ3（PostHog でのシンボルセット検索）は、すべてのプラットフォームで同じです。posthog-cli symbol-sets extract は、4種類すべてのコンテナ形式を処理します。ステップ1、2、およびプラットフォーム固有の失敗要因については、各プラットフォームのリファレンスを参照してください。

ワークフロー

ステップ1 - シンボルデータの生成方法とアップロード方法を確認する

アプリのリポジトリにあるビルドスクリプトと PostHog のアップロード設定を確認します。アップロードを処理する PostHog パッケージ（@posthog/rollup-plugin、@posthog/webpack-plugin、@posthog/nextjs-config、@posthog/nuxt、または直接の posthog-cli）と、そのパッケージが処理するディレクトリまたはアセットを確認してください。ビルドツール固有の設定の確認方法については、プラットフォームのリファレンスを参照してください。

デバッグでは、アップロード後もシンボルアーティファクトがディスク上に残るビルドを使用し、ローカルのアーティファクトと PostHog が受け取ったものを比較できるようにしてください。Vite プラグインを使う JavaScript の例です（他のビルドツールで同等の設定を行う方法については、プラットフォームのリファレンスを参照してください）。

sourcemaps: {
  enabled: true,
  deleteAfterUpload: false,
}

ステップ2 - ローカルのアーティファクトをビルドして確認する

シンボルをアップロードする本番ビルドを実行し、生成されたファイルをローカルで確認します。対象ファイルとヘルパーの呼び出し方はプラットフォームによって異なります。ヘルパーコマンド、想定されるファイル形式、よくあるビルド時の落とし穴（特に、アップロードのバグに見えて実際はバンドラーの設定の問題である、マッピングが空になる誤検知）については、プラットフォームのリファレンスを参照してください。

ローカルのアーティファクトがすでに正しくない場合は、PostHog のアップロードをデバッグする前にビルドを修正してください。

ステップ 3 - PostHog のシンボルセットを確認する

専用の MCP ツールを使って、ref が取得したフレームの chunk_id と一致するシンボルセットを検索します。認証、プロジェクトのスコープ設定、ページネーションは自動的に処理されます。

• posthog:error-tracking-symbol-sets-list に ref=<chunk_id> を指定すると、一致する行が返されます。
• posthog:error-tracking-symbol-sets-retrieve に ID を指定すると、同じ形式のデータが返されます（権限も確認できます）。
• posthog:error-tracking-symbol-sets-download-retrieve は、アップロードされたシンボルデータファイルを指す、1 時間有効の署名付き URL を返します。すぐにダウンロードしてください。ユーザーから明示的に求められない限り、URL をそのまま返さないでください。

MCP にアクセスできない場合、同じデータは PostHog UI の Project settings > Error tracking > Symbol sets で確認できます。

行の内容を解釈します。

• ref は、取得したフレームの chunk_id と一致する必要があります。
• last_used が更新されていれば、PostHog がそのシンボルセットを見つけて読み込んだことを意味します。ただし、フレームのシンボル解決が成功したとは限りません。
• has_uploaded_file: false は、アップロードが完了していないことを意味します。
• failure_reason が null 以外の場合、PostHog がアップロードされたシンボルデータを解析または読み込みできなかったことを意味します。

ダウンロードしたファイルは PostHog のシンボルデータコンテナ（圧縮された Rust エンコードのペイロード）で、プレーンな JSON ではありません。posthog-cli で展開します。

posthog-cli symbol-sets extract symbolset.bin -o ./extracted
# or, without installing globally:
#   npx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted
#   bunx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted

posthog-cli symbol-sets extract は、4 種類すべてのシンボルセット（source-and-map、hermes、proguard、dSYM）に対応し、展開したファイルを出力ディレクトリに書き込みます。展開後、プラットフォームリファレンスのヘルパーを使って内容を要約します。

ステップ 4 - ローカル、アップロード済み、配信中のファイルを比較する

失敗箇所に応じて、比較対象を決めます。

• ローカルの成果物とアップロード済みの成果物がどちらも空の場合：ビルドツールが使用できないシンボルを出力しました。
• ローカルの成果物は有効だが、アップロード済みの成果物が空の場合：アップロード処理で誤ったデータが選択またはパッケージ化されました。
• アップロード済みの成果物は有効だが、本番環境のスタックがミニファイまたは難読化されたままの場合：デプロイ済みバイナリのバイト列と、シンボルと一緒にアップロードされたバイナリのバイト列を比較します。
• Token not found の場合：PostHog はシンボルデータを読み込みましたが、取得した生成位置に一致するトークンがアップロード済みの成果物内にありません。通常は、アップロード後にバイナリが変更された、取得した行番号／列番号が誤っている（JavaScript）、フレームオフセットが誤っている（Hermes／dSYM）、またはシンボルのカバレッジに問題があることを示します。

ステップ 5 - 最も可能性の高い層を修正する

プラットフォームに依存しない修正方法：

• 後続のステップで書き換えられる前ではなく、最終的なビルド出力の生成後にシンボルをアップロードします。
• 最新の PostHog ビルドプラグインと posthog-cli を使用します。
• 同じ ref に異なる内容が以前アップロードされている場合は、変更されたアセットを意図的に再アップロードします。
• アップロード後に配信バイナリを変更するデプロイ時の変換（CDN によるミニファイ、エッジでの書き換え、圧縮）を取り除きます。

プラットフォーム固有の修正方法は、プラットフォームリファレンスを参照してください。

取得したフレームの確認

影響を受けている PostHog エラーイベントから、ミニファイされたアプリケーションフレームを 1 つ収集します。

• filename
• line または lineno
• column または colno
• function
• chunk_id（またはプラットフォームに相当するシンボルセットの ref）
• resolve_failure（特に Token not found）

フレームの filename は、デプロイ済みバイナリの URL と一致する必要があります。chunk_id はシンボルセットの ref と一致する必要があります。取得した生成位置は、シンボルデータと一緒にアップロードされたものと同じバイナリ内を指している必要があります。

失敗マトリックス（クロスプラットフォーム）

証拠	考えられる原因	次の確認
フレームに chunk_id がない	チャンク ID の挿入漏れ、または SDK のフレームパーサーがファイル名をマッピングしていない	デプロイ済みバイナリと生のフレームファイル名を確認します。
シンボルセットの行がない	アップロード先が別の PostHog プロジェクト／ホスト、またはこのアセットがスキップされた	プラグインの projectId、host、ref を比較します。
has_uploaded_file: false	アップロードが完了していない	ビルドログを確認し、posthog-cli の出力とシンボルセットの行を比較します。
null 以外の failure_reason	PostHog がアップロードされたシンボルデータを解析できなかった	ステップ 3 でダウンロードし、展開した内容を確認します。
アップロード済みのアーティファクトは有効だが、デプロイ済みバイナリが異なる	デプロイ／CDN／ビルド後の変換によって、アップロード後にバイナリが変更された	デプロイ済みのバイト列とローカルのビルド出力を比較します。
Token not found	キャプチャした位置に対応するトークンが、アップロード済みのシンボルデータにない	キャプチャした位置、デプロイ済みバイナリの識別情報、シンボルデータのカバレッジを確認します。

プラットフォーム固有の失敗要因（空の mappings、sourcesContent の欠落、Hermes の関数オフセットの不一致、Proguard のクラス名のずれ、dSYM の UUID の不一致）については、プラットフォームリファレンスを参照してください。