Trace (トレース)

トレース (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/
Copy full snippet

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 ウィンドウに表示され、上部ツールバーの ルーラー トラック の下にある マーカー トラック で見つけることができます。ブックマークは、ログ ビューで利用できます。

名前付きイベントの統計

名前付きイベントの統計 は、追加のプロファイリング メトリクスを提供し、チェックボックスをクリックすることで有効または無効にすることができます。

トレースの出力先

トレースの出力先 を設定することで、トレース データの格納先を選択することができます。

トレース ストア ファイル

トレーシング

トレースの開始と停止

Save Trace Snapshot (トレース スナップショットを保存)

Insights Widget から トレース スナップショット を保存するには、次の操作を実行します。

• [Save Trace Snapshot] ボタンをクリックします。

• [Trace (トレース)] ドロップダウン メニューをクリックして、[Tracing (トレーシング)] > [Save Trace Snapshot] に移動します。

オプション

場所

Insights

トレース ステータス

接続、使用メモリ、重要なイベント キャッシュ、送信 データ、有効 および 利用可能な トレース チャンネルに関する情報を確認できます。このためには、次のコマンドを使用します。

		Trace.Status
Copy full snippet

Trace.Status

コマンド プロンプトで Insights を実行する

1. 「Engine\Binaries\Win64」フォルダに移動して、「UnrealInsights.exe」をダブルクリックします。

1. オペレーティング システムから コマンド プロンプト を起動し、プロジェクトを実行します。

        cd C:\MyEngineInstallLocation\
   	
        Samples\Games\Binaries\Win64\YourProject.exe
   Copy full snippet

   cd C:\MyEngineInstallLocation\ Samples\Games\Binaries\Win64\YourProject.exe

ファイル ディレクトリのパスは、ローカルのインストール パスに合わせて変更する必要がある場合があります。

Tail Tracing (テール トレーシング)

[Tail Tracing] では、バッファ サイズに応じて過去数秒間のイベントをトラックするため、あらゆるマシンで下準備となる要素を表示できます。

デフォルトのバッファ サイズは「4MB」ですが、これを変更または無効にする場合は、コマンドラインに次のコマンドを入力します。

			`-tracetailmb=x`
Copy full snippet

`-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]
Copy full snippet

`"trace.send [ip]" / "trace.start [filename]" -trace.start[file][channelSet] -tracehost=[ip] -tracefile = [filepath]

Unreal Insights にはファイルベースのキャッシュ システムが備わっており、これによってアプリケーションでトレースに追加情報をアタッチすることができます。これを使って以前の計算結果をすばやく取得したり、このシステムなしでは失われるデータ (シンボルなど) を格納したりできます。キャッシュは、トレース ファイルと同じ名前の .ucache ファイルに格納されます。

トレース ユーザー ガイド

さまざまなワークフローを使用して、Unreal Insights でトレースを実行することができます。詳細については、「Trace User Guide (トレース ユーザー ガイド)」を参照してください。

トレーシングのデベロッパー ガイド

Unreal Insights では、独自のトレースを開発することができます。詳細については、「トレーシングのデベロッパー ガイド」を参照してください。