トレース

Unreal Insights におけるトレース ログ フレームワークの使用方法の概要です。

トレース (Trace) は、実行中のプロセスからインストルメンテーション イベントをトレースするための構造化されたログ フレームワークです。TraceLog および TraceAnalysis は、このフレームワークの主要な構成モジュールです。 Unreal Trace サーバー は単一のサーバー インスタンスとしてバックグラウンドで実行され、複数のプロジェクトまたはブランチ間で共有することができます。これはユーザー インターフェースを持たない最適化されたプログラムであり、パフォーマンスへの影響は最小限に抑えられます。

「Engine/Binaries/Win64」ディレクトリ フォルダに格納されている個別のサーバー プロセス「UnrealTraceServer.exe」によって Trace サーバーが自動的に起動します。

insights-major-components-diagram

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 サーバーは単一のサーバー インスタンスとしてバックグラウンドで実行され、複数のプロジェクトおよびブランチ間で共有することができます。

trace-executable

Unreal Trace サーバーは、システムのタスク マネージャーにアクセスすることで、シャットダウンすることができます。

task-manager

システム タスク マネージャーの [Processes (プロセス)] タブに表示されている実行中のサーバー トレース。

Unreal Trace サーバーは、単一のインスタンスとしてバックグラウンドで実行されるため、新しいバージョンを起動するために既存のインスタンスを停止する必要はありません。複数のソースから同時にデータを受信して記録することができます。

現在、Unreal Trace サーバーを実行しているマシンごとにユーザー 1 名のみをサポートしています。複数のユーザーが同時にログインしている場合、トレースは最初のユーザーのトレース ディレクトリに格納されるため、他のユーザーがアクセスすることはできません。

Trace Insights ウィジェット

Trace Insights ウィジェット は、エディタのインターフェースを使用して トレース データ を制御および管理する方法を提供します。Trace Insights ウィジェット には、エディタの下部ツールバーからアクセスできます。

insights-widget

トレース データ

トレース は、大量のデータを記録することが可能です。トレース チャンネルを使用して、記録するデータのタイプを選択することができます。

チャンネル

チャンネル は、トレース時のデータ レートを制御します。各イベント タイプは 1 つ以上のチャンネルに関連付けられています。必要なチャンネルが有効になっていない場合、イベントはトレース ストリームに送信されません。

trace-channels

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] カテゴリに追加するコンフィグ ファイルを使用して、独自のプリセットを定義できます。詳細については、「トレーシングのデベロッパー ガイド」を参照してください。

channels

上の画像では、Bookmark、Cpu、Frame、Gpu、Log の各チャンネルが有効になっています。これらのチャンネルは、デフォルトで利用可能です。

Trace Screenshot (トレース スクリーンショット)

[Trace Screenshot] は、フレーム中のプロジェクトのビューポートの画像を撮影し、トレースに送信します。デフォルトでは、[Trace Screenshot] はチャンネル パネルから有効化されます。トレース スクリーンショットを撮影することができます。

  • Insights/Trace ウィジェットをクリックし、Trace Screenshot (Ctrl+F9) をクリックします。

  • コンソール コマンド trace.screenshot を使用します。

trace-screenshot

Trace Screenshot を使用しているときは、Timing Insights のタイムラインに、スクリーンショットの日時を使用して、現在のタイムスタンプに基づいて生成された名前を含む垂直ラインが表示されます。

Trace Bookmark (トレース ブックマーク)

[Trace Bookmark] は、指定された文字列の名前を持つ TRACE_BOOKMARK() イベントを発行します。エディタから使用すると、スクリーンショットとブックマーク イベントの両方で、日時形式を使用して現在のタイムスタンプに基づいた名前が生成されます。

trace-bookmark

ブックマークとスクリーンショットは、Timing Insights ウィンドウに表示され、上部ツールバーの ルーラー トラック の下にある マーカー トラック で見つけることができます。ブックマークは、ログ ビューで利用できます。

log-window

名前付きイベントの統計

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

stat-named-events

トレースの出力先

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

trace-destination

トレース ストア ファイル

出力先

説明

Trace Store (トレース ストア)

出力先としてトレース ストアを設定します。これを使用すると、サーバーは管理されているトレース ストア ディレクトリ内のファイルにトレース データを書き込みます。

File (ファイル)

出力先としてファイルを設定します。これを使用すると、トレース データは指定されたファイルに直接書き込まれます。

トレーシング

トレースの開始と停止

Start Trace (トレースを開始)

選択したトレースの出力先にトレースを開始します。Trace Insights ウィジェットから [Start Trace] ボタンをクリックしてトレースを開始することができます。 start-trace-button

Stop Trace (トレースを停止)

トレースが開始されると、トレース開始 UI アイコンが赤色で表示されます。トレースの記録を停止するには、[Stop Trace] ボタンをクリックします。 stop-trace-button

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

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

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

save-snapshot-button

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

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

trace-status

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

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

unreal-insights-executable-in-binaries-folder

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

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

Unreal Engine のドキュメントを改善するために協力をお願いします！どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
キャンセル