このガイドでは、Unreal のアプリケーションまたはゲームを Backtrace プラットフォームに統合し、クラッシュレポートが送信されるように設定する方法について説明します。

Backtrace には、Unreal Engine のクラッシュレポートのネイティブ形式のファーストクラスサポートが備わっています。すべてのメタデータ属性が自動的に抽出されるため、それら（グラフィックスカードからゲームバージョンまで）に対してクエリを実行できるほか、ゲームのログ、オリジナルのレポートの XML ファイル（ユーザー入力あり）などのファイルアタッチメントが含まれます。基本のインテグレーションは、設定ファイルの設定を変更すること、または Backtrace の UE4 エディタープラグインを使用して、エディターからゲームをビルド/コンパイルするときの設定を自動化することで構成されます。

サポートされているプラットフォーム

Unreal Engine: 4.16 - 5.0 Early Access

Windows：ネイティブなクラッシュレポーターを使用する。設定ファイルを編集する（推奨）か、このガイドで説明するプラグインメソッドを使用します。
iOS ユーザー：「iOS - backtrace-cocoa ライブラリ」を参照。
Android：「Android - backtrace-android ライブラリ」を参照。
macOS ユーザー：PLCrashReporter を使用する。現時点では Unreal 固有の手順はありません。
Linux ユーザー：Crashpad を使用する。
ゲームコンソール（PS4、PS5、Xbox One、Xbox Series X | S、Nintendo Switch）：Backtrace のゲームコンソールのインテグレーションを使用する
オンプレミス（セルフホステッド）ユーザー：Unreal のクラッシュを取り込むには、特定のパッケージが必要です。詳細と手順については、サポートにお問い合わせください。

統合する方法

Backtrace アカウントに登録する

まだ登録していない場合は、こちらから Backtrace アカウントに登録してください。サブドメイン付きの専用テナントとともに、クラッシュ送信用のトークンが提供されます。

サーバーインスタンスのドメインは、次のような形式になります。

https://<AAAA>.sp.backtrace.io

送信トークンには、「プロジェクト設定」メニューからアクセスできます（こちらを参照）。次のような形式になります。

45e44f361045ae4343e4113e77e0ea3eee1043367342c3f03c3a273cb3e433ae

Unreal Engine のクラッシュレポーターを利用する必要がある場合でも、アプリケーションを Backtrace に統合するのにかかる時間はわずか数分で済みます。

Windows - 設定ファイルの編集（推奨）

Windows 上で実行される Unreal アプリケーションで推奨されるインテグレーションメソッドは、設定ファイルを使用する方法です。クラッシュレポートを Backtrace のようなクラッシュレポートサーバーにルーティングすることを担う UE4 の設定ファイルを手動で編集することで、さまざまな状況に柔軟に対応できます。この方法は、UE4 のすべてのバージョンでサポートされています。

まず、プロジェクト設定でクラッシュレポートが有効になっていることを確認します。「プロジェクト > パッケージ（Project > Packaging）」に移動し、「クラッシュレポーターを含める（Include Crash Report）」チェックボックスをオンにします。

注：コマンドラインからビルドしている場合は、このフラグでは不十分であり、ビルドの際に -crashreporter フラグも追加する必要があります。

次に、2 つの設定ファイルを更新する必要があります。 1 つは、Unreal エディター内でゲームが実行されるときのクラッシュレポーターを設定します。もう 1 つは、ゲームのパッケージビルドで効果を発揮します。

For crashes in the Editor

プロジェクトディレクトリの Config フォルダー内に、DefaultEngine.ini という名前の設定ファイルがあります。このファイルのコピーを [UNREAL_ENGINE]\Engine\Config\ フォルダー（注：これらの親フォルダーはまだ存在していない可能性があります。必要に応じて作成してください）に作成し、UserEngine.ini にします（注：ファイルの名前を変更します）。

注：Unreal Engine の場所は、デフォルトでは %USERPROFILE%\Unreal Engine ですが、%USERPROFILE%\Documents\Unreal Engine や C:\Program Files\Epic Games\UE_4.26\ にある場合もあります。

この UserEngine.ini の中に、次のセクションを追加します。

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/<universe>/<token>"

たとえば、Backtrace インスタンスがhttps://AAAA.sp.backtrace.io、送信トークンが0123456789abcdef の場合、セクションは次のようになります。

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/AAAA/0123456789abcdef"

これが設定された後に、Unreal エディター内でゲームがクラッシュすると、クラッシュレポートのダイアログが表示され、Backtrace インスタンスにクラッシュレポートが送信されます。インスタンスにログインすることで、クラッシュを確認できます。

オンプレミス（セルフホステッド）ユーザー：DataRouterUrl の値は異なる値になります。詳細と手順については、サポートにお問い合わせください。

For crashes in packaged builds - DefaultEngine.ini (UE4 4.16-UE5 Early Access)

オプション A - すべてのビルドのグローバルデフォルト

デバイス上の「すべてのビルド」の設定をオーバーライドできます。前のセクションの手順に従い、ただし今度は DefaultEngine.ini ファイルを次のディレクトリにコピーします。

[ENGINE_DIR]\UnrealEngine\Engine\Programs\CrashReportClient\Config
- Note that default for this is%USERPROFILE%\Unreal Engine but it can be under %USERPROFILE%\Documents\Unreal Engine or C:\Program Files\Epic Games\UE_4.26\ or C:\Program Files\Epic Games\UE_5\

これは、CICD 環境で役立ちます。

上の UserEngine.ini セクションと同じように、[CrashReportClient] セクションを追加します。

オプション B - パッケージビルドでオーバーライドする

パッケージビルド用のクラッシュレポーターを設定するには、前のセクションの手順に従い、ただし今度は DefaultEngine.ini ファイルを次のディレクトリにコピーします。

Unreal 4.25 以前
- [build_dir]\WindowsNoEditor\Engine\Programs\CrashReportClient\Config\NoRedist
- まだ存在していないサブディレクトリをクレジットします。
Unreal 4.26 以降
- [build_dir]\WindowsNoEditor\Engine\Restricted\NoRedist\Programs\CrashReportClient\Config
- まだ存在していないサブディレクトリをクレジットします。

上の UserEngine.ini セクションと同じように、[CrashReportClient] セクションを追加します。

シンボルをアップロードする

次は、デバッグシンボルが生成されるようビルド環境が設定されていることを確認する必要があります。プラグインには、シンボルファイルを Backtrace にアップロードするようエディターを設定するオプションが用意されています。または、デバッグシンボルを生成し、それが Backtrace インスタンス、接続されたシンボルサーバー、Amazon S3、または Google Cloud Bucket にアップロードされるよう、ビルドシステムが設定されていることを確認する必要があります。詳細については、シンボル化ガイドを参照してください。これは、エディター内で実行することも、Visual Studio で直接実行することもできます。

Android - backtrace-android ライブラリ

ゲームの Build.cs を探す
BacktraceAndroid_UPL.xml を、ゲームの Build.cs がある同じディレクトリに配置します。Android インテグレーションガイドの手順に従って、BacktraceCredentials を置き換えます。

これらの行をそのゲームの Build.cs で ModuleRules クラスコンストラクターの最後に追加します。

if (Target.Platform == UnrealTargetPlatform.Android) 
{
	string PluginPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
	AdditionalPropertiesForReceipt.Add("AndroidPlugin", System.IO.Path.Combine(PluginPath, "BacktraceAndroid_UPL.xml"));
}

GameInstance に BacktraceWrapper.h を含めます。
BacktraceIO::FInitializeBacktraceClient を使用して Backtrace クライアントを起動します。これはゲームの GameInstance::OnStart() メソッドから起動することを推奨していますが、このメソッドがない場合は、ゲームのインスタンス化プロセス中に使用する任意のメソッドでクライアントを起動してもかまいません。カスタム属性や、Backtrace レポートとともに送信するファイルアタッチメントのパスを指定できます。
- 注：ファイルアタッチメントのパスは、Android のパスとして指定する必要があります。たとえば、ProjectSavedDir() にファイルアタッチメントのパスを指定するには、以下を使用します。
```
#include "Misc/App.h"
#if PLATFORM_ANDROID
extern FString GFilePathBase;
FString FileAttachmentPath = GFilePathBase + FString("/UE4Game/") + FApp::GetName() + TEXT("/") + FApp::GetName() + TEXT("/Saved") + TEXT("MyFileName.txt");
#endif
```
UE4 のリフレクションが原因で、UE4 のパスを Android のパスに変換することが簡単でないことがあります。そのため、Epic では Android から UE4 のファイルパスに変換する機能を非公開にしています。AndroidPlatformFile.cpp の FAndroidPlatformFile::PathToAndroidPaths を参照してください
これで Unreal Engine のゲームで backtrace-android を利用できるようになり、クラッシュレポートと監視が改善されます。
詳細については、こちらのドキュメントと、Backtrace の Android に関するドキュメントへのその他のリンクを参照してください。BacktraceAndroid_UPL.xml を調整することで、Backtrace クライアントの設定を変更できます。

iOS - backtrace-cocoa ライブラリ

Backtrace_PLCrashReporter.framework と Backtrace.framework を（こちらから）ダウンロードし、（ファイルを解凍してから）ゲームに指定します。
ゲームの Build.cs を探す

これらの行をそのゲームの Build.cs で ModuleRules クラスコンストラクターの最後に追加します。パスには、両方のフレームワークを配置した、ゲームプロジェクト内の場所が反映されるようにしてください。

if (Target.Platform == UnrealTargetPlatform.IOS)
{
  PublicAdditionalFrameworks.AddRange(
    new Framework[] 
    {
      new Framework("Backtrace", "/Library/Frameworks/Backtrace.framework", "", true),
      new Framework("Backtrace_PLCrashReporter", "/Library/Frameworks/Backtrace_PLCrashReporter.framework", "", true)
    }
  );
}

（Backtrace.framework/Headers から）Backtrace-Swift.h をインポートして、ゲームに初期化ロジックを含めます。

最小限の例はこちらです。

#if PLATFORM_IOS
#import <Backtrace/Backtrace-Swift.h>
#endif

void UYourGameInstanceBase::OnStart()
{
#if PLATFORM_IOS

  BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                     initWithSubmissionUrl: [NSURL URLWithString: @"https://submit.backtrace.io/{universe}/{token}/plcrash"]];
  BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                                 initWithCredentials: credentials
                                                 dbSettings: [[BacktraceDatabaseSettings alloc] init] 
                                                 reportsPerMin: 3 
                                                 allowsAttachingDebugger: NO
                                                 detectOOM: TRUE]; 
  BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];
#endif
}

これで Unreal Engine のゲームで backtrace-cocoa を利用できるようになり、クラッシュレポートと監視が改善されます。
Backtrace cocoa に関する完全なドキュメントについては、こちらを参照してください。

Windows - UE4 Editor Plugin (alternative integration method; up to UE 4.24)

設定ファイルの更新やシンボルのアップロードを自動化するプラグインは、Unreal マーケットプレイスからも入手できます。このプラグインは現在、UE 4.24 までに対応しており、2021 年第 2 四半期により新しいバージョンの UE4 エディターのサポートを追加する予定です。

要件

x86 ベースの Windows 7 から 10
Unreal Engine 4.16 - 4.24 (4.25, 4.26 & UE5 coming in Q3 2021)
Visual Studio Community 2017 以降
Backtrace インスタンス（こちらからサインアップ）。

プラグインは古いバージョンの Unreal でも動作する可能性はありますが、それらのバージョンでは広範囲にわたってはテストされていません。

機能

プラグインにより .ini ファイルが更新され、クラッシュが Backtrace アカウントに転送されるようになります。
プラグインを使用すると、シンボルが自動でアップロードされるように設定できます。こうすることで、シンボルファイルを手動でアップロードする必要がなくなります。こちらは独自のビルドシステムや分散ビルドを使用しているユーザーには適用されないため、その場合は .ini 設定メソッドを使用することをお勧めします。

プラグインのインストール

プラグインの最新バージョンは、Unreal マーケットプレイスからダウンロードできます。

ファイルを解凍し、BacktraceIntegration フォルダーをプロジェクトフォルダー内の Plugins フォルダーにコピーします。ディレクトリ構造は次のようになります。PROJ\my_game.uproject PROJ\Plugins\BacktraceIntegration\BacktraceIntegration.uplugin

プロジェクトがすでに Unreal エディターで開かれている場合は、再起動してプラグインが検出されるようにしてください。

プロジェクトファイルを右クリックして、Visual Studio のファイルを再生成します。プラグインがビルドプロセスに統合され、必要に応じてシンボルが自動的にアップロードされるようになります。

ブループリントのみのプロジェクトの場合でも、Visual Studio のプロジェクトファイルを生成する必要があります。Visual Studio のプロジェクトファイルを生成する方法については、こちらで確認してください。

この時点で、プラグインのインテグレーションは完了です。Backtrace プラグインを開き、ウィザードの手順に従って開始します。すべてのプロンプトに従って進め、正しい情報がすべて指定されていることを確認します。

プロジェクト設定でクラッシュレポートが有効になっていることを確認します。「プロジェクト > パッケージ（Project > Packaging）」に移動し、「クラッシュレポーターを含める（Include Crash Report）」チェックボックスをオンにします。

注：コマンドラインからビルドしている場合は、このフラグでは不十分であり、ビルドの際に -crashreporter フラグも追加する必要があります。

機能

属性

Unreal Engine のクラッシュレポートインフラストラクチャでは、クラッシュレポートの一部として送信されたすべての属性とメタデータが抽出されます。これにより、Backtrace のクエリビルダーを使用して、このデータをフィルタリング、集計、ファセット化できます。

いくつかの属性は、Backtrace システムのビルトインの属性にマップされます。他のすべての属性はそのまま出力されます。このデータをフィルタリング、集計、またはファセット化する場合は、クラッシュレポートの XML ファイルに指定された属性に対応する属性を作成できます。たとえば、GameName のある属性が必要な場合は、それに対応する GameName という名前の Backtrace 属性を作成できます。属性の詳細については、プロダクトガイドをご覧ください。

以下に示すのは、アプリケーション用に作成されたデフォルトの属性です。最初の列は Unreal Engine のネイティブなプロパティ名で、2 番目の列は Backtrace に格納されている属性、最後の列は説明です。欠落している属性は後で作成し、そのオブジェクトを「プロジェクト設定」ページで再処理できます。

Unreal のプロパティ Backtrace の属性説明
--------------------------------------------------------------------
MachineID guid マシンの一意の識別子。
SecondsSinceStart process.ageアプリケーションが実行されている秒数。
ErrorMessage error.message 追加のエラーメッセージ。
MemoryStats.UsedPhysical vm.rss.size 常駐メモリの使用量。
MemoryStats.PeakUsedPhysical vm.rss.peak 常駐メモリのピーク時の使用量。MemoryStats.UsedVirtual vm.vma.size 仮想メモリの使用量。
MemoryStats.PeakUsedVirtual vm.vma.peak 仮想メモリのピーク時の使用量。MemoryStats.TotalPhysical vm.rss.available 使用可能な物理メモリ。
MemoryStats.TotalVirtual vm.vma.available 使用可能な仮想メモリ。

Backtrace の属性 説明
--------------------------------------------------------------------
application クラッシュするオブジェクトの名前。
callstack クラッシュするコールスタック。
classifiers ミニダンプの例外コード。
cpu.count システム上のプロセッサーの数。
fault.address クラッシュ時にアクセスされているメモリアドレス。
fingerprint 重複排除を目的としたコールスタックのフィンガープリント。
hostname クラッシュするシステムのホスト名。
uname.machine プロセッサーのアーキテクチャ。
uname.sysname オペレーティングシステムの名前。
uname.version オペレーティングシステムのバージョン。ほか

以下に示すのは、自分で追加できるその他の一般的な属性のリストです。Backtrace によって自動的にインデックスが付けられます。独自のプロパティを追加する場合は、インデックスを付ける目的でそれらのプロパティの属性を作成できるようになります。

Unreal のプロパティ 推奨されるカラム型説明
DescriptionCrashGuid dictionary クラッシュレポートに関連付けられている GUID。
ProcessId uint64 プロセスの識別子。
IsInternalBuild bitmap Boolean クラッシュが内部エンジンビルドによるものであったかどうか。

IsPerforceBuild bitmap Boolean クラッシュが内部エンジンビルドによるものであったかどうか。

IsEnsure bitmap Boolean クラッシュが Ensure エラーであったかどうか。
IsAssert bitmap Boolean クラッシュがアサートエラーであったかどうか。
GameName dictionary Unreal ゲームの名前。
ExecutableName dictionary ゲームの実行ファイルの名前。

CrashDumpMode uint8 クラッシュダンプが完全ダンプか部分ダンプであるかどうかをマークします。

UserActivityHint dictionary エラー発生時のユーザーのアクティビティを表す文字列（わかっている場合）。 bAllowToBeContacted bitmap ユーザーにエラーについて問い合わせて問題ないかどうか。

他にも多数あります。詳細については、CrashDescription.h を参照してください...

個々のクラッシュレポートには、デフォルトですべてのクラッシュプロパティが含まれます。それらは、ウェブデバッガーの「アノテーション（Annotations）」ペインで確認できます。

高度なインテグレーション

カスタムダイアログ、よりカスタマイズされたファイルアタッチメント、Unreal のネイティブなクラッシュレポーターでサポートされていないプラットフォームなど、クラッシュレポートの追加のカスタマイズが必要な場合は、より高度なインテグレーションのためにまとめられた言語とアプリケーションのインテグレーションガイドを参照してください。

トラブルシューティング

オンプレミスについてはどうすればよいですか？

オンプレミスのインストールに関する追加情報については、support@backtrace.io にお問い合わせください。Backtrace の Unreal クラッシュレポートサーバーにカスタムドメインマッピングを設定できます。

カスタムクラッシュプロパティを追加するにはどうすればよいですか？

現時点では、属性を個々のプラットフォームに追加する必要があります。

Windows と Linux

Unreal API FGenericCrashContext::SetGameData を使用してカスタム属性を追加できます。

static void SetGameData
(
    const FString & Key,
    const FString & Value
)

この API を使用すると、crashContext-runtime.xml にカスタムプロパティが追加され、それが Backtrace によって解析されます。プロパティを追加した後は、必ず「プロジェクト設定」の「属性」ページにアクセスし、それらがインデックス付けされるようにしてください。

Android

初期化に次のコードを追加します。

TMap<FString, FString> BacktraceAttributes;
BacktraceAttributes.Add("key", "value");

BacktraceIO::FInitializeBacktraceClient(BacktraceAttributes, Attachments);

iOS

カスタム属性を追加する Swift と ObjectiveC のサンプルコードについては、こちらを参照してください。

BacktraceClient.shared?.attributes = ["key": "value", "testing": true]

クラッシュレポートのエラーをトラブルシューティングするにはどうすればよいですか？

クラッシュレポートクライアントのログを確認してください。また、DefaultEngine.ini（パッケージビルドのクラッシュの場合）と [ENGINE_DIR]\Engine\Config\UserEngine.ini（エディター内のクラッシュの場合）の設定が正しいことを確認することを推奨します。

クック処理されたビルドを作成する（コンテンツのクック処理を参照）ときは、[ENGINE_DIR]\Engine\Programs\CrashReportClient\Config\DefaultEngine.ini のコンテンツが Engine\Programs\CrashReportClient\Config\DefaultEngine.ini としてクック処理されたビルドのパスに含まれます。

/Saved の下に生成された CrashReportClient.ini ファイルに Backtrace URL がある場合でも、Unreal のベースディレクトリのファイルを使用しているように表示されます。

そのファイルのコンテンツを Backtrace のバージョンに置き換えると、レポーターが期待どおりに機能するようになります。そのため、クック処理されたビルドでは、プロジェクトの ini の変更だけでなく、エンジンの変更が要求される可能性があるように見えます。

tcpdump や FiddlerAnywhere などのネットワーキングツールを使用して、クラッシュレポーターの送信先のホストが正しいかどうかを確認できます。
それでも問題が解決しない場合は、埋め込みのサポートチャットまたは support@backtrace.io 宛にメールでサポートにお問い合わせください。

BacktraceWrapper.h
8 KB Download
BacktraceAndroid_UPL.xml
2 KB Download

このセクションの記事

Unreal インテグレーションガイド

サポートされているプラットフォーム

統合する方法

Backtrace アカウントに登録する

Windows - 設定ファイルの編集（推奨）

For crashes in the Editor

For crashes in packaged builds - DefaultEngine.ini (UE4 4.16-UE5 Early Access)

シンボルをアップロードする

Android - backtrace-android ライブラリ

iOS - backtrace-cocoa ライブラリ

Windows - UE4 Editor Plugin (alternative integration method; up to UE 4.24)

要件

機能

プラグインのインストール

機能

属性

高度なインテグレーション

トラブルシューティング

オンプレミスについてはどうすればよいですか？

カスタムクラッシュプロパティを追加するにはどうすればよいですか？

Windows と Linux

Android

iOS

クラッシュレポートのエラーをトラブルシューティングするにはどうすればよいですか？

このセクションの記事

サポートされているプラットフォーム

統合する方法

Backtrace アカウントに登録する

Windows - 設定ファイルの編集（推奨）

For crashes in the Editor

For crashes in packaged builds - DefaultEngine.ini (UE4 4.16-UE5 Early Access)

シンボルをアップロードする

Android - backtrace-android ライブラリ

iOS - backtrace-cocoa ライブラリ

Windows - UE4 Editor Plugin (alternative integration method; up to UE 4.24)

要件

機能

プラグインのインストール

機能

属性

高度なインテグレーション

トラブルシューティング

オンプレミスについてはどうすればよいですか？

カスタムクラッシュプロパティを追加するにはどうすればよいですか？

Windows と Linux

Android

iOS

クラッシュレポートのエラーをトラブルシューティングするにはどうすればよいですか？

関連記事