このセクションの記事

もっと見る

シンボル化概要

  • 更新

 

minidump のファイルを送信する場合は、分類、重複排除、コールスタックレンダリングを正確に実行するために、Backtrace にデバッグシンボルがアップロードされていることを確認する必要があります。

シンボルの生成

Windows

Visual Studio では、デバッグビルドによって .pdb シンボルファイルが生成されます。リリースビルドやカスタム設定にシンボルファイルを生成する場合は、プロジェクトの「構成プロパティ」で「デバッグ情報の生成」がオンになっていることを確認してください。

C++

  1. ソリューションエクスプローラーで、プロジェクトを選択します。
  2. 「プロパティ」アイコンを選択します。
  3. 「構成」リストで、「デバッグ」または「リリース」を選択します。
  4. サイドペインで、「リンカー」 > 「デバッグ」を選択し、「デバッグ情報の生成」のオプションを選択します。
  5. C++ でのデバッグ構成のプロジェクト設定の詳細については、「C++ デバッグ構成のプロジェクト設定」を参照してください。
  6. プログラムデータベースファイルを生成するためのオプションを設定します。

C#、.NET

  1. ソリューションエクスプローラーで、プロジェクトを選択します。
  2. 「プロパティ」アイコンを選択します。
  3. サイドペインで、「ビルド」を選択します。
  4. 「構成」リストで、「デバッグ」または「リリース」を選択します。
  5. 「詳細」ボタンを選択します。
  6. 「デバッグ情報」リストで、「完全」を選択します。

Linux

Backtrace は、ELF および .sym ファイル形式に対応しています。

Breakpad を使用する

  1. Breakpad のスクリプトを実行すると、正しいディレクトリ構造 components/crash/content/tools/generate_breakpad_symbols.py --build-dir=out/gnand --symbols-dir=/tmp/my_symbols/ --binary=out/gnand/lib.unstripped/libchrome.so --clear --verbose が生成されます。
  2. 問題のライブラリが /lib/libfoo.so であり、デバッグシンボルが /usr/debug/lib/libfoo.so であると仮定し、次を実行します。dump_syms /lib/libfoo.so /usr/debug/lib /tmp/libfoo.so.sym

追加情報については、Breakpad のドキュメントを確認してください。

Mac と iOS

Backtrace は、dSYM 形式に対応しています。

macOS の Xcode

  1. プロジェクトの「Build Settings（ビルド設定）」をクリックします。
  2. 「Debug Information Format（デバッグ情報の形式）」を検索して選択し、「DWARF with dSYM File（DWARF（dSYM ファイル））」に設定します。
  3. この設定を有効にしてビルドすると、dSYM ファイルが保存されます。
  • スキーマベースのビルド：Xcode の「Preferences（詳細設定）」にある「Locations（場所）」セクションの「Derived Data（派生データ）」の設定
  • アーカイブされたアプリ：xcarchive ファイルのパッケージコンテンツ内
  • 不明な場合は、mdfind コマンド（mdfind ）をお試しください。

その他

ご不明な点がある方は、画面右下のアプリ内チャットでサポートチームにお問い合わせください。

Backtrace によって自動的にプルされたシンボル

ユーザーがアップロードする必要があるシンボルの量を最小限に抑えるために、Backtrace は公開されている以下のシンボルサーバーからシンボルをプルするように設定されています。

  • Microsoft
    • Windows OS シンボル
  • Mozilla
    • macOS シンボル
  • AMD
    • ATI（gpu）シンボル
  • Electron
    • Electron フレームワークシンボル

    • Linux や macOS の注意点：シンボル化プロセスはアプリケーションの名前に依存しているため、これらのシンボルは Electron という名前の Electron のアプリケーションとのみ一致します。これを回避する方法についてサポートが必要な場合は、画面右下のアプリ内チャットからサポートチームにお問い合わせください（シンボルを調整するか、名前が変更されたものを手動でアップロードする必要があります）。

  • Unity
    • Unity ゲームエンジンシンボル
  • Intel
  • NVIDIA

追加/プライベートシンボルサーバー

追加のパブリックシンボルサーバーや、プライベートシンボルサーバーからプルするように Backtrace を設定できます。Backtrace のシンボルサーバーへの接続に関するドキュメントを参照してください。

シンボルの形式とアップロード方法

プロジェクトの設定ページに移動し、「シンボル」をクリックして、シンボルに関するすべての記録（アップロード履歴、検索機能、シンボルのアクセストークンなど）を確認します。Backtrace では、クラッシュが発生することが見込まれるビルドごとに、シンボルのアーカイブ（1 つ以上の .sym、ELF、dSYM ファイルが含まれる .tar.gz または .zip ファイル）をアップロードすることを推奨しています。 これらのシンボルファイルは、手動でアップロードすることも、ビルドシステムに接続して、自動的にアップロードされるよう設定することもできます。

シンボルは、ウェブブラウザー、morgue、curl、HTTP を介してアップロードできます。

注：上の表には、ウェブブラウザー、curl、HTTP を介してアーカイブとしてアップロードできる .elf ファイルと dSYM ファイルは含まれていません。

また、シンボルをグループ化して管理しやすくするために、アップロードされたシンボルに tag クエリ文字列パラメーターを指定することもできます。タグとはシンボルのグループのことで、ファイルシステムにおけるフォルダーのようなものです。アプリケーションのバージョンやプラットフォームごとに異なるタグを指定することをお勧めします。タグが指定されていないシンボルは、anon タグに配置されます。

アップロード方法に関係なく、Backtrace ではシンボルの状態を容易に確認できます。Backtrace は、.pdb + .sym（Breakpad のシンボルファイル）、ELF + dSYM ファイルとシンボルアーカイブ（それらのファイルが含まれる圧縮または非圧縮アーカイブ）に対応しています。ファイルのレイアウトに制限はありませんが、相対パスが使用されていない、かつファイルに正しいベース名が指定されていることを確認する必要があります。たとえば、Editor.exe のデバッグ情報は、Editor.pdb または Editor.sym という名前のファイルにある必要があります。

NOTE: Make sure that your symbols files (.pdb .sym, etc) are uploaded before their corresponding .exe and .dll files, or included in the same archive, to ensure proper processing. 

シンボル管理

Breakpad と Socorro

Backtrace は、Breakpad や Socorro の既存のユーザーと完全に互換性があります。HTTP POST を介して、または sym_upload ツールを使用して、.sym ファイルをアップロードするだけです。インスタンスにアップロードするには、「アクセストークン（Access Token）」が必要です。（シンボルのアクセストークンを参照している）token と、値が symbols の format クエリ文字列パラメーターを指定する必要があります。

シンボルのアップロードに使用されるアクセストークンは、エラー送信トークンとは異なります。シンボルをアップロードする際には、「プロジェクト設定」 > 「シンボル」 > 「アクセストークン」にあるシンボルのアクセストークンを使用していることを確認してください。

以下に示すのは、sym_upload ツールを使用したシンボルアップロードの呼び出し例です。

sym_upload null_read_av.sym 'http://yourcompany.sp.backtrace.io:6098/post?format=symbols&token=57f2126dcef18bb0d2af35ec1d813f3775ee8228d1d886de522b2aedceff8b87'

HTTP API

ビルドプロセスやリリースプロセスとのインテグレーションなど、シンボルのアップロードを自動化するには、Backtrace から提供される HTTP API と直接接続することをお勧めします。

HTTP POST を に発行するだけです。アクセストークンは、「プロジェクト（Projects）」 > 「自分のプロジェクト（Your Project）」 > 「シンボル（Symbols）」 > 「アクセストークンを管理（Manage Access Tokens）」に移動し、「新しいアクセストークンを作成（Create a new access token）」ボタンをクリックして作成できます。

以下に示すのは、シンボルアーカイブを送信する curl の呼び出し例です。

curl --data-binary @symbols.tar -H "Expect: gzip" "https://yourcompany.sp.backtrace.io:6098/post?format=symbols&token=5ae2136d4ef181b0d2afa5ef1d81ff377eea8228d1d883d4552621ed1eff8b87"

HTTP シンボルアップロード用の curl のサンプルコマンド

注：アップロードのサイズが大きい場合は、フラグ -H "Expect: gzip" を curl の呼び出しに指定します。

ウェブブラウザー

ウェブブラウザーを介してシンボルを管理するには、プロジェクトの設定ページに移動して、「シンボル（Symbols）」をクリックします。.pdb または .sym、および .sym、.pdb、ELF、dSYM ファイルの圧縮されたアーカイブをウェブブラウザーに直接アップロードできます。個々のファイルではなく、すべてのシンボルファイルの .zip ファイルをアップロードすることをお勧めします。詳細については、画面の指示に従ってください。

トラブルシューティング

コマンドラインからのシンボルのアップロードがブロックされている場合は、ウェブブラウザーから直接アップロードしてみてください。手順は上で確認できます。

無効なトークン

HTTP を介してシンボルをアップロードするときに、応答で「無効なトークン」エラーを受け取った場合は、プロジェクトトークンではなく、シンボルトークンを使用していることを確認してください。シンボルトークンは、「プロジェクト設定」ページで「シンボル」セクションをクリックし、ページ中央の「Manage Access Tokens（アクセストークンを管理）」タブで作成できます。

欠落しているシンボル

シンボルのアップロードプロセス中にシンボルが欠落することがあります。ダンプから欠落しているシンボルのリストは、ウェブデバッガーの「アノテーション」ペインで確認できます。このリストを取得する方法の詳細については、ウェブデバッガーガイドを参照してください。

欠落しているシンボルをアップロードした後は、「オブジェクトを再処理（Reprocess Objects）」によって、シンボルが欠落しているダンプを再処理できます。欠落しているシンボルがアップロードされた後に、ダンプのグループ分けが変更される場合があるので注意してください。 オブジェクトを再処理するには、いくつかの方法があります。

  1. システム管理者は、画面の右上からメニューを開き、「プロジェクト設定」を選択し、「オブジェクトを再処理」セクションに移動することで、プロジェクト内のすべてのオブジェクトをウェブブラウザーから直接再処理できます。
  2. システム管理者と Backtrace のサポートは、morgue ツールを使用してクラッシュのより具体的なグループを再処理できます。

オブジェクトの再処理に関する詳細情報やサポートが必要な場合は、画面右下のアプリ内チャットを使用して、Backtrace のサポートにお問い合わせください。

欠落しているシンボルの場所の特定

欠落しているシンボルファイルの場所を特定するには、まずそのシンボルファイルの名前とデバッグ識別子を特定します。デバッガー UI を介してこれを行う方法は、2 つあります。

  1. シンボルが欠落しているエラーを表示すると、Backtrace によって画面下部の「アノテーション」セクションにシンボルが欠落しているブランチが追加されます。エントリ番号を展開すると、対応する実行ファイルへのパス、シンボルファイルの名前、デバッグ識別子、実行ファイルまたはモジュール（「パス」として表示される）、バージョン情報が表示されます。

2.エラーのシンボルが欠落している場合、これはコールスタックでも確認できます。影響を受けているフレームに、通常であれば関数シグネチャが存在するメモリアドレスとともに、三角形の警告シンボルが表示されます。これらのフレームの 1 つにカーソルを合わせると、シンボルが欠落していることを示す黄色の警告のポップアップが表示されます。デバッグ識別子とシンボルファイルの名前は、見出しで確認できます。

morgue ツールがインストールされている場合は、morgue symbol コマンドを使用して、シンボルアップロードの状態を確認し、欠落しているシンボルの一覧を取得できます。 詳細については、https://github.com/backtrace-labs/backtrace-morgue を参照してください。

これで、社内のシンボルアーカイブから欠落しているシンボルファイルをチェックするのに必要な情報が得られました。シンボルファイルを識別する方法は、使用しているシンボルファイルの種類によって異なります。

.sym ファイル - Breakpad の .sym ファイルを使用している場合、これは非常に簡単です。Breakpad の sym ファイルの最初の行は MODULE レコードで、pdb の名前とデバッグ識別子の一覧が表示されます（例：MODULE windows x86_64 D0489F894E07424AAB5E626FF8C943DD1 advapi32.pdb）。

.pdb ファイル - （より一般的なケース）.pdb ファイルを使用している場合は、次のいずれかの方法を使用して .pdb ファイルからデバッグ識別子を抽出し、一致するものを見つける必要があります。

  • dia2dump - Microsoft MSDN サイトより
  • 通常、.exe ファイルと .pdb ファイルは同じ場所に保存されるため、Windows のビルドツール dumpbin.exe を使用して、一致するシンボルの名前とデバッグ識別子が含まれる、実行ファイルのヘッダーをダンプできます。たとえば、次のコマンドによって、ID が 5C82DF990DA04C46A2B22ABB82D6B66A1 のシンボル bcrypt.pdb が提案されます。

dumpbin.exe /headers bcrypt.dll

  Debug Directories

        Time Type       Size      RVA  Pointer
    -------- ------ -------- -------- --------
    584A7C7E cv           23 00021A80    20C80    Format: RSDS, {5C82DF99-0DA0-4C46-A2B2-2ABB82D6B66A}, 1, bcrypt.pdb

On Windows, the executable, libraries, and PDB files must be uploaded as some unwinding information required for symbolification is contained exclusively in the executable objects.

.dsym ファイル - MacOS の .dsym ファイルがサポートされています。

.elf ファイル - ELF ファイルがサポートされています。

欠落しているシンボルの場所を特定してアップロードしたら、前の欠落しているシンボルに関するセクションで説明したように、必ずオブジェクトを再処理してください。

モジュール名が一致しない

適切なシンボルファイルがアップロードされていないことに加えて、取り違えが発生するもう 1 つの原因は、モジュール名の不一致です。 欠落しているシンボル情報を表示すると、Backtrace にはそのシンボルファイルが一致すると見込まれる、そのモジュール（実行ファイルまたは dll/ライブラリファイル）の名前が表示されます。 これは、デバッガーのアノテーションの欠落しているシンボルのセクション内の「パス」であるか、欠落しているシンボルとして表示されているフレームのツールチップに「ライブラリ」として表示されます。

モジュールの名前が一致しない場合、Backtrace ではそのシンボルが欠落していると表示されます。そのため、対象のシンボルファイルに正しいモジュール名が反映されていることを確認し、exe/dll ファイルをアップロードする場合は、それらの名前が正しいことを確認してください。

不正確なコールスタック

Windows

On Windows, applications store some unwinding information exclusively in the executable object (.exe or .dll file). For this reason, we advise to include the executable code of your application and library during symbol upload. These files can be uploaded as stand-alone files, but you must ensure that the file base name matches the base name of the .pdb file. For example, the debug information for Editor.exe is expected to be in Editor.pdb. It is important that the name of the executable is Editor.exe in this context to pair with Editor.pdb. If the executable was uploaded as Word.exe, then you are unable to pair with Editor.pdb. It is recommended that a symbol archive is used.

Visual Studio

Visual Studio を使用している場合は、シンボルが正しく生成されていることを確認する必要があります。追加の詳細は、Crashpad に関する Visual Studio のドキュメントで確認できます。

関連記事