トレース (Trace) は、実行中のプロセスからインストルメンテーション イベントをトレースするための構造化されたログ フレームワークです。TraceLog および TraceAnalysis は、このフレームワークの主要な構成モジュールです。 Unreal Trace サーバー は単一のサーバー インスタンスとしてバックグラウンドで実行され、複数のプロジェクトまたはブランチ間で共有することができます。これはユーザー インターフェースを持たない最適化されたプログラムであり、パフォーマンスへの影響は最小限に抑えられます。
「Engine/Binaries/Win64
」ディレクトリ フォルダに格納されている個別のサーバー プロセス「UnrealTraceServer.exe
」によって Trace サーバーが自動的に起動します。
Trace サーバーには次の 2 つのコンポーネントがあります。
-
トレース レコーダー。受信するトレース接続をポート 1981 でリッスンし、ライブ トレース ストリームを記録します。
-
トレース ストア。記録されたトレースをファイルとしてフォルダに格納します。このフォルダで変更がないかを監視し、利用可能なトレースのリストを Unreal Insights の UI に公開します。
トレース フォルダへのパスの例は次のとおりです。
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/
Unreal Trace サーバー
Unreal トレース セッション ブラウザから接続を確立する際に Unreal Editor ビルドによって UnrealTraceServer.exe
を自動的に起動します。Unreal Trace サーバーは単一のサーバー インスタンスとしてバックグラウンドで実行され、複数のプロジェクトおよびブランチ間で共有することができます。
Unreal Trace サーバーは、システムのタスク マネージャーにアクセスすることで、シャットダウンすることができます。
システム タスク マネージャーの [Processes (プロセス)] タブに表示されている実行中のサーバー トレース。
Unreal Trace サーバーは、単一のインスタンスとしてバックグラウンドで実行されるため、新しいバージョンを起動するために既存のインスタンスを停止する必要はありません。複数のソースから同時にデータを受信して記録することができます。
現在、Unreal Trace サーバーを実行しているマシンごとにユーザー 1 名のみをサポートしています。複数のユーザーが同時にログインしている場合、トレースは最初のユーザーのトレース ディレクトリに格納されるため、他のユーザーがアクセスすることはできません。
Trace Insights ウィジェット
Trace Insights ウィジェット は、エディタのインターフェースを使用して トレース データ を制御および管理する方法を提供します。Trace Insights ウィジェット には、エディタの下部ツールバーからアクセスできます。
トレース データ
トレース は、大量のデータを記録することが可能です。トレース チャンネルを使用して、記録するデータのタイプを選択することができます。
チャンネル
チャンネル は、トレース時のデータ レートを制御します。各イベント タイプは 1 つ以上のチャンネルに関連付けられています。必要なチャンネルが有効になっていない場合、イベントはトレース ストリームに送信されません。
MemAlloc、MemTag、Moduleの各チャンネルは、コマンド プロンプトから実行する必要があるため、グレー表示されています。「コマンド プロンプトから」を参照してください。
チャンネル プリセットは、チャンネルをグループ化し、シナリオベースのエントリー ポイントを提供します。
チャンネル | 説明 |
---|---|
Animation | Animation Insights プラグイン |
AssetLoadTime | UObject::Serialize 用の名前付き CPU タイマーを格納する |
AssetMetadata | メモリ割り当てのメタデータとしてのアセット名とクラス名。メタデータ チャンネルが必要です。Memalloc チャネルで使用されます。 |
Audio | Audio Insights プラグイン。 |
AudioMixer | AudioMixer Insights プラグイン。 |
Bookmark | 重要な遷移を示す低周波のマーカー。ブックマークは、レベルのローディングやエンジンのブート フェーズなの機能の概要をすばやく示します。 |
Callstack | コールスタックの説明。割り当てをコールスタックに関連付けることができます。 |
ContextSwitch | コンテキスト スイッチ イベントをトレースします。Windows では、ゲーム / エディタのランタイムは管理者として実行する必要があります。 |
Cook | クックに固有の名前付き CPU タイマーを表示します。この場合、CPU チャネルを有効にする必要があります。クックは、CookByTheBook およびSaveCookedPackage CPU の両方のタイミング イベントを追加します。 |
Counters | 汎用カウンター。時間の経過に伴い浮動小数点数および整数値をトレースします。Counters Trace API です。CSV プロファイラ トレースを有効にします。 |
Cpu | 名前付きの Cpu タイマー。Insights Widget から Stat Named Events チャンネルを有効にするか、-statnamedevents コマンドライン引数を使用することで、タイマーを追加することができます。 |
File | Open、ReOpen、Read、Write、Close イベントを格納するファイル I/O トレース チャンネル。 |
Frame | ゲームとレンダリングのフレーム。 |
Gpu | 名前付きの Gpu タイマー。GpuProfiler データに基づいています。 |
LoadTime | Asset Loading Insights トレース チャンネル。pak/iostore からのランタイム ロード時のみ動作します。[#INCLUDE:testing-and-optimizing-your-content/unreal-insights/trace-in-unreal-engine#LoadTimeChannelSettings] |
Log | ログ メッセージ。 |
MemAlloc | メモリの割り当て。モジュールとコールスタックを使用します。 |
MemTag | メモリ タグの統計。タグごとのメモリ使用量のスナップショットを通常の速度でトレースします。トレースは LLM サブシステムに依存します。「-llm」を示します。Init() の後で使用することができます。 |
Messaging | UDP Messaging プラグイン。 |
Metadata | 汎用メタデータ スコープをサポートします。 |
Module | モジュールのロード情報。 |
Net | ネットワーク トレース チャンネル。[#INCLUDE:testing-and-optimizing-your-content/unreal-insights/trace-in-unreal-engine#NetworkingCommand] |
Niagara | Niagara プラグイン。 |
Object | GameplayInsights/RewindDebugger プラグイン。UObject クラス、ワールド、インスタンス、およびイベントです。 |
Physics | Chaos Visual Debugger。 |
RDG | RDG Insights プラグイン。 |
RHICommands | RHI コマンド用の Cpu/Gpu 名前付きタイマー。 |
RenderCommands | レンダリング スレッドで実行されるコマンドの Cpu/Gpu 名前付きタイマー。 |
SaveTime | パッケージ保存に固有の名前付き CPU タイマー。 |
Screenshot | Trace.Screenshot コンソール コマンドによって、または TRACE_SCREENSHOT() API を使用してトリガーされたスクリーンショットをキャプチャします。 |
Slate | Slate Insights プラグイン。 |
StackSampling | Event Tracing for Windows (ETW) に基づくトレース スタック サンプリング イベント。 |
Stats | 統計カウンター。これは統計システムに基づいています。 |
Task | タスク グラフ トレース チャンネル。 |
VisualLogger | ビジュアル ロガーがファイルへのレコーディングを開始します。 |
[Trace.ChannelPresets]
カテゴリに追加するコンフィグ ファイルを使用して、独自のプリセットを定義できます。詳細については、「トレーシングのデベロッパー ガイド」を参照してください。
上の画像では、Bookmark、Cpu、Frame、Gpu、Log の各チャンネルが有効になっています。これらのチャンネルは、デフォルトで利用可能です。
Trace Screenshot (トレース スクリーンショット)
[Trace Screenshot] は、フレーム中のプロジェクトのビューポートの画像を撮影し、トレースに送信します。デフォルトでは、[Trace Screenshot] はチャンネル パネルから有効化されます。トレース スクリーンショットを撮影することができます。
- Insights/Trace ウィジェットをクリックし、Trace Screenshot (Ctrl+F9) をクリックします。
- コンソール コマンド
trace.screenshot
を使用します。
Trace Screenshot を使用しているときは、Timing Insights のタイムラインに、スクリーンショットの日時を使用して、現在のタイムスタンプに基づいて生成された名前を含む垂直ラインが表示されます。
Trace Bookmark (トレース ブックマーク)
[Trace Bookmark] は、指定された文字列の名前を持つ TRACE_BOOKMARK()
イベントを発行します。エディタから使用すると、スクリーンショットとブックマーク イベントの両方で、日時形式を使用して現在のタイムスタンプに基づいた名前が生成されます。
ブックマークとスクリーンショットは、Timing Insights ウィンドウに表示され、上部ツールバーの ルーラー トラック の下にある マーカー トラック で見つけることができます。ブックマークは、ログ ビューで利用できます。
名前付きイベントの統計
名前付きイベントの統計 は、追加のプロファイリング メトリクスを提供し、チェックボックスをクリックすることで有効または無効にすることができます。
トレースの出力先
トレースの出力先 を設定することで、トレース データの格納先を選択することができます。
トレース ストア ファイル
出力先 | 説明 |
---|---|
Trace Store (トレース ストア) | 出力先としてトレース ストアを設定します。これを使用すると、サーバーは管理されているトレース ストア ディレクトリ内のファイルにトレース データを書き込みます。 |
File (ファイル) | 出力先としてファイルを設定します。これを使用すると、トレース データは指定されたファイルに直接書き込まれます。 |
トレーシング
トレースの開始と停止
Start Trace (トレースを開始) | 選択したトレースの出力先にトレースを開始します。Trace Insights ウィジェットから [Start Trace] ボタンをクリックしてトレースを開始することができます。![]() |
Stop Trace (トレースを停止) | トレースが開始されると、トレース開始 UI アイコンが赤色で表示されます。トレースの記録を停止するには、[Stop Trace] ボタンをクリックします。![]() |
Save Trace Snapshot (トレース スナップショットを保存)
Insights Widget から トレース スナップショット を保存するには、次の操作を実行します。
- [Save Trace Snapshot] ボタンをクリックします。
- [Trace (トレース)] ドロップダウン メニューをクリックして、[Tracing (トレーシング)] > [Save Trace Snapshot] に移動します。
オプション
オプション | 説明 |
---|---|
Open Live Session on Trace Start (トレース開始時にライブセッションを開く) | 有効に設定すると、トレースが開始されたときにライブ セッションが Unreal Insights で自動的に開きます。 |
Open Insights after Trace (トレース後に Insights を開く) | 有効に設定すると、トレーシングが停止またはスナップショットが保存されたとき、このセッションが Unreal Insights で自動的に開きます。 |
Shown in Explorer after Trace (トレース後にエクスプローラーで表示) | 有効に設定すると、トレースが停止またはスナップショットが保存されたとき、記録されたセッションを含むフォルダが自動で開きます。 |
場所
オプション | 説明 |
---|---|
Open Trace Store Directory (トレース ストア ディレクトリを開く) | これは Trace サーバーに格納されるトレースが格納される場所です。 |
Open Profiling Directory (プロファイリング ディレクトリを開く) | 現在のプロジェクトのプロファイリング ディレクトリを開きます。これはファイルへのトレースが格納される場所です。 |
Insights
オプション | 説明 |
---|---|
Unreal Insights(Session Browser) (Unreal Insights (セッション ブラウザ)) | Unreal Insights セッション ブラウザを起動します。 |
Open Live Session (ライブ セッションを開く) | 現在のライブ セッションを開きます。これは、ストアにトレーシングする場合にのみ可能です。 |
Recent Traces (最近使用したトレース) | トレース ストアまたはファイルとして記録された最新のトレースを開きます。 |
トレース ステータス
接続、使用メモリ、重要なイベント キャッシュ、送信 データ、有効 および 利用可能な トレース チャンネルに関する情報を確認できます。このためには、次のコマンドを使用します。
Trace.Status
コマンド プロンプトで Insights を実行する
- 「
Engine\Binaries\Win64
」フォルダに移動して、「UnrealInsights.exe」をダブルクリックします。

- オペレーティング システムから コマンド プロンプト を起動し、プロジェクトを実行します。
cd C:\MyEngineInstallLocation\ Samples\Games\Binaries\Win64\YourProject.exe
ファイル ディレクトリのパスは、ローカルのインストール パスに合わせて変更する必要がある場合があります。
Tail Tracing (テール トレーシング)
[Tail Tracing] では、バッファ サイズに応じて過去数秒間のイベントをトラックするため、あらゆるマシンで下準備となる要素を表示できます。
デフォルトのバッファ サイズは「4MB」ですが、これを変更または無効にする場合は、コマンドラインに次のコマンドを入力します。
`-tracetailmb=x`
「X」の部分を「0 MB」に置き換えるとトレーシングが無効になり、その他の値に置き換えると、その値に応じてバッファ サイズが変更されます。
遅延接続
Important イベント は Unreal Engine のクライアント側にキャッシュされるため、接続の際はこれらのイベントは遅延接続のマシンに送信されます。そのため、接続を確立する前に一度限りのイベント (Important イベント) が見過ごされてしまうことはありません。
Insights では、そのローカル UI インスタンスから (そのローカル マシンを実際に使用することなく)、リモートで実行されている Unreal Engine インスタンスに対して、リモート トレース サーバーに接続するよう指示することができます。
遅延接続は、Unreal Insights の [Connect (接続)] を使用するか、エディタのコマンド コンソール に次のコマンドを入力することで開始できます。
`"trace.send [ip]" / "trace.start [filename]"
-trace.start[file][channelSet] -tracehost=[ip]
-tracefile = [filepath]
Unreal Insights にはファイルベースのキャッシュ システムが備わっており、これによってアプリケーションでトレースに追加情報をアタッチすることができます。これを使って以前の計算結果をすばやく取得したり、このシステムなしでは失われるデータ (シンボルなど) を格納したりできます。キャッシュは、トレース ファイルと同じ名前の .ucache
ファイルに格納されます。
トレース ユーザー ガイド
さまざまなワークフローを使用して、Unreal Insights でトレースを実行することができます。詳細については、「Trace User Guide (トレース ユーザー ガイド)」を参照してください。
トレーシングのデベロッパー ガイド
Unreal Insights では、独自のトレースを開発することができます。詳細については、「トレーシングのデベロッパー ガイド」を参照してください。