Trace は、実行中のプロセスからインストルメンテーション イベントをトレースするための構造化されたログ フレームワークです。 TraceLog および TraceAnalysis は、このフレームワークの主要な構成モジュールです。 Unreal Trace Server は単一のサーバー インスタンスとしてバックグラウンドで実行され、複数のプロジェクトまたはブランチ間で共有することができます。 これはユーザー インターフェースを持たない最適化されたプログラムであり、パフォーマンスへの影響は最小限に抑えられます。
「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 サーバーをシャットダウンするには、システムのタスク マネージャーにアクセスし、[プロセス] タブに移動します。
Unreal Trace サーバーは、単一のインスタンスとしてバックグラウンドで実行されるため、新しいバージョンを起動するために既存のインスタンスを停止する必要はありません。 複数のソースから同時にデータを受信して記録することができます。
現在、Unreal Trace サーバーは、マシンあたり 1 人のユーザーに限りサポートしています。 複数のユーザーが同時にログインしている場合、トレースは最初のユーザーのトレース ディレクトリに格納されるため、他のユーザーがアクセスすることはできません。
Trace Insights ウィジェット
Trace Insights ウィジェットは、エディタのインターフェースを使用してトレース データを制御および管理する方法を提供します。 Trace Insights Widget には、エディタの下部ツールバーに移動して、 [Trace (トレース)] ボタンをクリックすることでアクセスできます。
次のセクションでは、[Trace (トレース)] メニューの各カテゴリ内の設定について説明します。
トレースデータ
[Trace Data (トレース データ)] カテゴリには、データ チャンネルの設定、トレース ブックマーク、トレース スクリーンショットなどが含まれています。
チャンネル
トレースは、大量のデータを記録することができます。 トレース チャンネルを使用して、記録するデータのタイプを選択することができます。
チャンネルは、トレース時のデータ レートを制御します。 各イベント タイプは 1 つ以上のチャンネルに関連付けられています。 必要なチャンネルが有効になっていない場合、イベントはトレース ストリームに送信されません。
チャンネル プリセットは、チャンネルをグループ化し、シナリオベースのエントリ ポイントを提供します。
| Channel | Description |
|---|---|
Animation | Animation Insights Plugin. |
AssetLoadTime | Contains named CPU timers for |
AssetMetadata | Asset Names and Class Names as metadata for memory allocations. Requires Metadata channel. Used by Memalloc channel. |
Audio | Audio Insights Plugin. |
AudioMixer | AudioMixer Insights Plugin. |
Bookmark | Low-frequency markers to signify important transitions. Bookmarks provide a quick overview of features such as level loading or engine boot phases. |
Callstack | Callstack descriptions. Allows allocations to be associated with callstacks. |
ContextSwitch | Trace context switch events. On Windows, game or editor runtime should be run as administrator. |
Cook | Displays named CPU timers specific to cooking. This requires the CPU channel to be enabled. Cook will add the both the |
Counters | Generic counters. Traces float and integer values over time. Counters Trace API. It enables the CSV Profiler Trace. |
Cpu | Named CPU timers. Additional timers can be added by enabling the Stat Named Events channel from the Insights Widget or using the |
File | File I/O trace channel that contains Open, ReOpen, Read, Write, Close events. |
Frame | Game and Rendering frames. |
Gpu | Named GPU timers. Based on GpuProfiler data. |
LoadTime | Asset Loading Insights trace channel. Only works for runtime loading from the pak/iostore. |
Log | Logs Messages. |
MemAlloc | Memory allocations. Uses Module and Callstack. |
MemTag | Memory tag statistics. Traces snapshots of memory usage per tag at regular rate. Relies on LLM subsystem for tracing. Implies "-llm". Available after |
Messaging | UDP Messaging plugin. |
Metadata | Support for generic metadata scopes. |
Module | Module loading information. |
Net | Networking trace channel. |
Niagara | Niagara Plugin. |
Object | GameplayInsights/RewindDebugger plugin. |
Physics | |
RDG | RDG Insights Plugin. |
RHICommands | CPU or GPU named timers for RHI commands. |
RenderCommands | CPU or GPU named timers for commands executed on the rendering thread. |
SaveTime | Named CPU timers specific to package saving. |
Screenshot | Captures screenshots triggered with |
Slate | Slate Insights Plugin. |
StackSampling | Trace stack sampling events based on Event Tracing for Windows (ETW). |
Stats | Stats counters. Based on the Stats system. |
Task | Task Graph trace channel. |
VisualLogger | Visual Logger starts recording to file. |
デフォルトで次のチャンネルが有効になっています。
Bookmark
Cpu
フレーム
Gpu
ログ
領域
Screenshot
MemAlloc、MemTag、Moduleの各チャンネルは、コマンド プロンプトから実行する必要があるため、グレー表示されています。 コマンド プロンプトを使用するを参照してください
[Trace.ChannelPresets] カテゴリに追加するコンフィグ ファイルを使用して、独自のプリセットを定義できます。 詳細については、「トレーシングのデベロッパー ガイド」デベロッパー を参照してください。
スクリーンショットトレース
[Trace Screenshot] は、フレーム中のプロジェクトのビューポートの画像を撮影し、トレースに送信します。 デフォルトでは、[Trace Screenshot] はチャンネル パネルから有効化されます。
トレース スクリーンショットを撮影するには、次の 2 つの方法があります。
下のツールバーで、[Trace (トレース)] > [Trace Screenshot] をクリックします。
コンソールで、コマンド
trace.screenshotを入力します。
Trace Screenshot を使用しているときは、Timing Insights のタイムラインに、スクリーンショットの日時を使用して、現在のタイムスタンプに基づいて生成された名前を含む垂直ラインが表示されます。
ブックマークトレース
トレース ブックマークは、指定された文字列名を持つ TRACE_BOOKMARK() イベントを発行します。 エディタから使用すると、スクリーンショットとブックマーク イベントの両方で、日時形式を使用して現在のタイムスタンプに基づいた名前が生成されます。
トレース ブックマークは次の 2 つの方法で設定できます。
下部のツールバーで、Trace (トレース) > Trace Bookmark をクリックします。
コンソールで、コマンド
trace.bookmarkを入力します。
ブックマークとスクリーンショットは、[Timing Insights] タブに表示されます。 ルーラー トラックの下の、上部ツールバーにドッキングされているマーカー トラックにあります。 ブックマークは、ログ ビューで利用できます。
名前付きイベントの統計
名前付きイベントの統計 には、追加のプロファイリング メトリクスが用意されています。 [State Named Events (ステートの名前付きイベント)] チェックボックスをクリックすると、これらの機能を有効または無効にすることができます。
トレースの出力先
[Trace Destination (トレースの出力先)] カテゴリで、トレース データの格納先を選択できます。
| オプション | 説明 |
|---|---|
Trace Store (トレース ストア) | 管理されているトレース ストア ディレクトリ内のファイルにトレース データを書き込みます。 |
File (ファイル) | 指定されたファイルにトレース データを直接書き込みます。 |
トレーシング
Tracing (トレーシング) カテゴリには、レコーディングの開始と停止、およびトレース スナップショットの保存のための設定が含まれています。
レコーディングの開始/停止
| オプション | 説明 |
|---|---|
Start Trace (トレースを開始) | 選択したトレースの出力先にトレースを開始します。 Trace Insights ウィジェットから [Start Trace (トレースを開始)] ボタンをクリックしてトレースを開始することができます。 |
Stop Trace (トレースを停止) | トレースが開始されると、トレース開始 UI アイコンが赤色で表示されます。 Stop Trace (トレースを停止) ボタンをクリックすると、トレースのレコーディングを停止することができます。 |
トレーススナップショットを保存
Trace Snapshot (トレース スナップショット)を保存するには次の 2 つの方法があります。
下のツールバーで、Save Trace Snapshot (トレース スナップショットを保存) ボタンをクリックします。
下のツールバーで、[Trace (トレース) ] > [Save Trace Snapshot (トレース スナップショットを保存)] をクリックします。
オプション
[Options (オプション)] カテゴリは、Unreal Insights や移動先フォルダを自動的に開くなど、自動化を制御します。
| オプション | 説明 |
|---|---|
Open Live Session on Trace Start (トレース開始時にライブセッションを開く) | トレーシングが開始されると、ライブ セッションが Unreal Insights で自動的に開きます。 このオプションは、トレース ストアでトレースする場合にのみ適用されます。 |
Open Insights after Trace (トレース後にInsightsを開く) | トレーシングが停止されたとき、またはスナップショットが保存されたときは、記録されたセッションが Unreal Insights で自動的に開きます。 |
Shown in Explorer after Trace (トレース後にエクスプローラーで表示) | トレーシングが停止されたとき、またはスナップショットが保存されたときは、記録されたセッションを含むフォルダが自動的に開きます。 |
場所
[Locations (場所)] カテゴリは、トレース (ファイルと Trace サーバーに保存) の格納場所を制御します。
| オプション | 説明 |
|---|---|
Open Trace Store Directory (トレース ストア ディレクトリを開く) | これは Trace サーバーに格納されるトレースが格納される場所です。 |
Open Profiling Directory （プロファイリング ディレクトリを開く） | 現在のプロジェクトのプロファイリング ディレクトリを開きます。 これはファイルへのトレースが格納される場所です。 |
Insights
Insights カテゴリには、Unreal Insights、ライブ セッション、および記録されたファイルを開く設定が含まれています。
| オプション | 説明 |
|---|---|
Unreal Insights(Session Browser (Unreal Insights(セッション ブラウザ))) | Unreal Insights セッション ブラウザを起動します。 |
Open Live Session (ライブ セッションを開く) | 現在のライブ セッションを開きます。 これは、ストアにトレーシングする場合にのみ可能です。 |
Recent Traces (最近使用したトレース) | トレース ストアまたはファイルとして記録された最新のトレースを開きます。 |
トレース ステータス
接続, 使用メモリ, 重要イベント キャッシュ, 送信 データ、Enabled および 利用可能な トレース チャンネルに関する情報をTrace.Statusを使用して、確認することができます。
コマンド プロンプトで Insights を実行する
コマンド プロンプトから Unreal Insights を実行するには、次の手順を実行します。
Engine\Binaries\Win64フォルダに移動し、UnrealInsights.exeをダブルクリックします。オペレーティング システムからコマンド プロンプトを起動し、プロジェクトを実行します。 次の例では、インストール パスとプロジェクト名を実際のものに置き換えます。
C++cd C:\[MyEngineInstallLocation]\ Samples\Games\Binaries\Win64\[YourProject].exe
テール トレーシング
Tail Tracing (テール トレーシング)では、(バッファ サイズに応じて) 過去数秒間のイベントをトラックします。 したがって、あらゆるマシンで下準備となる要素を表示できます。
デフォルトのバッファ サイズは 4MB ですが、変更または無効にする場合は、コンソール コマンド -tracetailmb=X を使用して入力します。
X を 0 MB に設定するとバッファが無効になり、その他の値を設定するとバッファ サイズが変更されます。
遅延接続
Important events (重要なイベント)は Unreal Engine のクライアント側にキャッシュされますが、接続の際は遅延接続のマシンに送られます。 そのため、接続を確立する前に一度限りのイベント (Important events (重要なイベント)) が見逃されることはありません。
Insights では、そのローカル UI インスタンスから (そのローカル マシンを実際に使用することなく)、リモートで実行されている Unreal Engine インスタンスに対して、リモート トレース サーバーに接続するよう指示することができます。
遅延接続は、[Unreal Insights (Unreal Insights)] > [Connect (接続)] に移動するか、次のコマンドまたは引数のいずれかを入力してエディタ コンソールから開始できます。
"trace.send [ip]" / "trace.start [filename]"-trace.start [file] [channelSet] -tracehost=[ip]-tracefile = [filepath]
Unreal Insights にはファイルベースのキャッシュ システムが備わっており、これによってアプリケーションでトレースに追加情報をアタッチすることができます。 これを使って以前の計算結果をすばやく取得したり、このシステムなしでは失われるデータ (シンボルなど) を格納したりできます。 キャッシュは .ucache ファイルに格納されます。隣に追加する必要があります
トレース ユーザー ガイド
さまざまなワークフローを使用して、Unreal Insights でトレースを実行することができます。 詳細については、「トレース ユーザー ガイド」を参照してください。
トレーシングのデベロッパー ガイド
Unreal Insights では、独自のトレースを開発することができます。 詳細については、「トレーシングのデベロッパー ガイド」デベロッパー を参照してください。