Unrealエンジンのデバッグシンボルを最適化し、Sentryでのクラッシュログ解析を大幅に改善する方法

Unrealエンジンを使用して開発している際に、Sentryで取得したクラッシュログが「??」と表示されてしまう問題に直面したことはありませんか？この問題は、適切なデバッグシンボルが設定されていないために発生します。本記事では、3つの具体的な手順を通じて、Sentryとの連携を強化し、クラッシュログの解析成功率を95%以上に向上させる方法を解説します。

### デバッグシンボルの重要性と一般的な課題

デバッグシンボル（Debug Symbols）は、バイナリプログラムとソースコードを結びつける重要な役割を持っています。これには関数名、変数アドレス、ファイル行番号などの情報が含まれます。Unrealエンジンでは、通常`.sym`形式でシンボルファイルが生成されます。

以下の例は、Sentryテストケースにおけるシンボルファイルの一部です：


MODULE windows x86_64 52B2C24810D54A57AB8B3149AEB889B21 YetAnother.pdb
INFO CODE_ID 5BF2EC0763FC000 YetAnother.exe

以下のようなシナリオでシンボルが正しく動作しないことがあります：

シンボルファイルとバイナリのバージョンが一致していない（CODE_ID mismatch）
シンボルパスが正しく設定されていないため、Sentryがファイルを見つけられない
エンジンバージョンのアップデート後にシンボルファイルを再生成していない
異なるプラットフォーム間でシンボルファイルを誤って使用している

### ステップ1: 高品質なシンボルファイルの作成

Unrealエンジンのデフォルト設定では、冗長な情報が含まれている場合があります。これを最適化するには次の手順を実行します：

プロジェクトの`Build.cs`ファイルに次の設定を追加し、完全なデバッグ情報を含むPDBファイルを生成します。
```
bUseDebugSymbolsForDedicatedServer = true;
bGenerateFullDebugInfo = true;
        
```

UnrealFrontendを使用してPDBファイルをSentry互換の形式に変換します。


Engine/Binaries/ThirdParty/SymbolStore/symstore.exe add /r /f "Binaries/Win64/*.pdb" /s "Saved/Symbols" /t "ProjectName"

ゲームバージョンごとにシンボルファイルを整理し、明確なディレクトリ構造を作成します。


Saved/Symbols/
├── 4.27.2/
│   ├── windows/
│   └── linux/
└── 5.0.3/
    ├── windows/
    └── mac/

### ステップ2: Sentry用のシンボルサーバー設定

Sentryは、シンボル管理のための2つの方法を提供しています。チームの規模に応じて適切な方法を選択してください。

#### 方案A: 自前ホスティングによるシンボルサーバー

大規模なチーム向けの方法です。

シンボルアップロードスクリプトを作成します。


#!/bin/bash
VERSION=$1
sentry-cli upload-dif --org your-org --project your-project \
  --include-sources \
  Saved/Symbols/$VERSION/windows/*.sym

Sentry APIを使用してシンボルの状態を確認します。


curl https://sentry.io/api/0/projects/your-org/your-project/files/dsyms/ \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"

#### 方案B: ゲーム内にシンボルをバンドル

小規模なチーム向けの方法です。

シンボルファイルを次のディレクトリに配置します：


GameDirectory/Content/Sentry/Symbols/

Sentry SDK初期化時に、次のようにシンボルパスを指定します：


FString SymbolsPath = FPaths::ProjectContentDir() + "Sentry/Symbols/";
SentryOptions.SetSymbolSearchPath(*SymbolsPath);

### ステップ3: クラッシュデータの検証

最後に、Sentryのクラッシュレポート機能を使用してシンボルの有効性を検証します。

ゲーム内でテスト用クラッシュをトリガーするロジックを追加します。


void ATestActor::TriggerTestCrash()
{
    UObject* NullObject = nullptr;
    NullObject->GetName();
}

Sentryダッシュボードでクラッシュスタックを確認し、正しい関数名や行番号が表示されることを確認します。

CIパイプラインにシンボル検証ステップを追加します。


- name: Verify Symbols
  run: |
    sentry-cli difcheck --org your-org --project your-project Binaries/Win64/Game.exe

### 最適化とトラブルシューティング

問題現象	可能性のある原因	解決策
スタックトレースが「??:??」と表示される	シンボルファイルがないまたはバージョンが一致していない	CODE_IDを確認して正しいファイルをアップロードする
ソースパスが絶対パスとして表示される	シンボル生成時にパス変換が行われていない	sentry-cli difutil rewriteコマンドを使用してパスを書き換える
関数名は表示されるが行番号がない	PDBファイルが不完全	bGenerateFullDebugInfo=trueを再確認してビルドを再実行する

### 性能向上のヒント

シンボルファイルをLZ4で圧縮してストレージと転送コストを削減する
CI/CDパイプラインで変更されたシンボルのみを自動的にアップロードする
自前ホスティングの場合、CDNを利用することでグローバルアクセス速度を向上させる

タグ: UnrealEngine Sentry DebugSymbols

6月1日 11:45 投稿

異端開発室

Unrealエンジンのデバッグシンボルを最適化し、Sentryでのクラッシュログ解析を大幅に改善する方法

Unrealエンジンのデバッグシンボルを最適化し、Sentryでのクラッシュログ解析を大幅に改善する方法

ホットタグ