Unreal Insights を使うと、デベロッパーはボトルネックを特定しやすくなり、パフォーマンスの最適化に役立ちます。Unreal Insights についておおまかに説明すると、Unreal Engine 4 (UE4) と統合されたスタンドアロン プロファイリング システムで、デベロッパーがエンジンから出力されたデータを収集、解析、可視化するのに役立ちます。Unreal Insights はエンジンの既存システムを確実にカバーするだけでなく、プロファイル データを簡単に追加できます。また、システムにはデータをリモートで記録する機能があり、プロジェクトの実行に与える影響を最小限に抑えることができます。

設定

Unreal Insights ツールは Unreal Engine 4 の出荷時に付属しています。場所は「Engine/Binaries/Win64」ディレクトリにあります。UE4 ソースコードをダウンロードしてローカルでコンパイルするユーザーは、UE4 ソリューション全体を開発モードまたは出荷モードでビルドするか、「UnrealInsights」プロジェクトを直接ビルドしてコンパイルできます。

コンパイル済みのプログラム (UnrealInsights.exe) を見つけたら、データの記録やライブ セッションの表示に使用するマシンで実行します。ツール自体のパフォーマンスへの影響を最小限に抑えるため、そのマシンはプロジェクトを実行するマシンとは異なるものを使用することをお勧めしますが、プロジェクトとツールの両方を 1 台のコンピュータで実行することもできます。ツールが最初に実行されていることが重要です。プロジェクトは起動するとすぐにツールへの接続を試みます。

ツールがリモートで実行されている場合は、コマンドライン オプション -tracehost=X の「X」を「IP」に置き換えて指定してプロジェクトを起動し、ツールの IP をプロジェクトに指定します。

ランタイム イベントをトレースする

ランタイムから Unreal Insights までのインストルメンテーション イベントのトレースは、 -trace[=channel0[,channel1...]] コマンドライン引数を使用すると有効になります。引数は、トレースするトレース チャンネルの任意のコンマ区切りのリスト、または .ini で定義されたチャンネル セットの名前を受け取ります (詳細は後述)。-trace に引数が与えられない場合は、デフォルトのチャンネル セットが使用されます (cpu、frames、log``bookmarks)。結果の 「.utrace」ファイルは、プロジェクトのデフォルトのプロファイリング ディレクトリ (通常は/Saved/Profiling)に表示されます。Unreal Insights はファイルを読みとり、ブラウザ ペインにドラッグアンドドロプしてロードすることができます。

trace.stop コマンドは、すべてのチャンネルのトレーシングを一時停止します。再度 trace.start コマンドを発行すると、トレーシングを再開できます。trace.stop はすべてのチャンネルに適用されるため、引数を取りません。

プロファイリング コマンドの詳細については、「Unreal Insights のリファレンス」を参照してください。

事前定義されたチャンネル セットは Trace.ChannelPresets セクションの .ini ファイルで定義することができます。Engine/Config/BaseEngine.ini の中にデフォルト セット(以前は「Default」という名前でした) があります。これは -trace と trace.start で使用されるデフォルトです。ユーザーは以下の手順で .ini ファイルに自分で簡単に追加することができます。

[Trace.ChannelPresets]
MyChannelSet=log,frame

このプリセットは -trace=MyChannelSet または trace.start MyChannelSet で使用することができます。

トレーサーのワーカー スレッドの詳細については、「トレース」のリファレンスをご覧ください。

Unreal Insights — ブラウザ

Browser モード (4.25 の新機能) でアプリケーションを起動した後、Trace Sessions (1)、Trace Recorder Directory (2) コントロール、New Connection (3) メニューが表示されます。

ツールが起動すると、[Unreal Insights] ウィンドウが開きます。ウィンドウの上部セクションには、[Trace Sessions] というラベルが付いており、解析用にロードできるすべての記録済みセッションのリストが表示されます。これらは Trace Store Directory にある .utrace ファイルです。これらのトレース セッションのいずれかをダブルクリックするか (またはトレース セッションを選択し、[Open] ボタンをクリック)、[Open] ボタンのドロップダウン矢印を使用して他の場所で .utrace ファイルを検索できます。それぞれのトレース ファイルの解析をすぐに開始するには、エクスプローラーから .utrace ファイルを [Unreal Insights] ウィンドウにドラッグ＆ドロップします。

ライブ UE4 セッションがツールに接続されている場合はリストにも表示されます。ライブ セッションのステータス列には LIVE という単語が表示され、解析中にリアルタイムで更新されますが、それ以外の点では、事前に指定されたセッションと同じです。ツールは複数のセッションに同時に接続することができ、すべてのセッションのデータを自動的に記録します。これらのセッションは、リストからロードすることでリアルタイムに分析できます (事前に記録されたセッションと同様)。

下のセクション ([New Connection (新しい接続)]) には、実験的機能の [Connect (接続)] ボタンと、ユーザーがすでに進行中の IP を入力するためのテキスト入力フィールドがあります。これは主にゲーム コンソールでの使用を目的としていますが、引き続き開発中であり、信頼性が低い可能性があります。この機能は、今後のリリースで改良される予定です。現時点では、プロジェクトを起動する前に Unreal Insights Tool を起動し、プロジェクトの -tracehost=%ADDRESS% コマンドライン オプションを使用することをお勧めします。

非推奨機能

ツールを閉じることなくトレース レコーディングを停止できる [Stop (停止)] ボタン機能を含む [Trace Recorder (トレースレコーダ)] セクションは、4.25 で非推奨となりました。必要なデータを収集した後、セッションが終了する前に、ライブ セッションへの新しいデータのフローを停止する場合に便利な機能で、これにより、データを読み取りやすくなりました。このボタンを押すと、現在実行中のセッションからツールが切断され、新しいセッションへ接続できないようにしました。

レコーディングの停止中は、[Stop] ではなく [Start (開始)] と表示されていました。レコーディングを再開すると、新しいリモートの Unreal Engine セッションは接続可能になりますが、トレース レコーディングが停止している間に開始されたセッションには接続されず、[Stop] でドロップされたセッションには再接続されませんでした。

Unreal Insights — ビューア

4.25 の新機能として、トレース セッション解析が別のプロセス (Viewer モード) で開始します。さらに、複数の解析 (ビューア) ウィンドウを同時に開くことができます。

解析用のトレース セッションを開くと、Unreal Insights には 3 つのウィンドウ タブが表示されます。そのうちの 2 つは [Timing Insights] ウィンドウと [Asset Loading Insights] ウィンドウで、パフォーマンス データを参照および可視化し、セッションが表示可能になると表示されます。

Timing Insights ウィンドウ

[Timing Insights] ウィンドウには、CPU と GPU に関するフレームごとのパフォーマンス データが表示されます。いくつかのパネルでは、プロジェクトが各種のタスクに費やした時間を異なるビジュアライゼーションで確認できたり、時間ブロックを選択して集計を表示したり、データをソートまたは分類したり、ログ出力を確認したりすることができます。また、各パネルの表示/非表示を切り替えることができます。

Unreal Insights のリファレンス

[Timing Insights] ウィンドウの重要な機能の 1 つは、1 つのフレームまたは期間を選択し、その期間に収集されたパフォーマンス情報を表示する機能です。この機能では、[Timing] パネルをハイライト表示してズームし、[Timers] タブと [Stats Counters (統計カウンター)] タブでデータを集約します。これを行うには、[Frames] パネルで 1 つのフレームをクリックするか、[Timing] パネルの上部にあるスクラブバーのセクション (タイム ルーラー) をクリックしてドラッグします。

!0

Frames パネル

[Frames] パネルには、各フレームの合計所要時間が棒グラフ形式で表示されます。これは、特定のレベルがロードされたときや最適化されていないシーンが表示されたときにフレーム レートが低下するなどの一般的な傾向を識別したり、多数のアクタを一度にスポーンさせるなど、個々のフレームの速度が低下する理由を発見するのに役立ちます。縦の棒は長いフレームを表しているため、これらのイベントが発生した正確な時点を特定し、データを調べてどの操作が原因であるかを簡単に確認できます。カーソルをバーの上に置くと、そのフレームのインデックスと実行にかかった時間が表示されます。このバーを左クリックすると、[Timing] パネル、[Timers] タブ、および [Stats Counters] タブでそのフレームのデータを分離できます。

Timing パネル

Unreal Insights ツールでは、作業のほとんどを [Timing] パネルで行います。このパネルには、セッション中に実行された各タイマー イベントの各インスタンスが視覚的に表示されます。フレーム全体の概要を表示する [Frames] パネルとは異なり、[Timing] パネルでは個々のトレース イベントが表示され、マイクロ秒未満の精度で時間を測定できます。これらのイベントは、スコープを示すために垂直にスタックされ、異なるスレッドでのアクティビティを示すために個別のトラックを使用します。トラック表示では、イベントはスレッドごとに分割され、スコープを示すために垂直方向に分割され、開始時間と終了時間に基づいて水平方向に配置されます。

関連するスレッドのグループは、パネルの左上にある [Tracks (トラック)] ドロップダウンでオンまたはオフにできます。トラック内のブロック上にマウス カーソルを置くと、そのタイマー イベントに関する情報が表示され、それをクリックすると、[Timers] タブ内のイベントが検索されて選択されます。

[Timing] パネルを使って、特定の時間範囲の集計データを表示することができます。タイム ルーラー上でマウスポインタをクリックしながらドラッグして、調べる期間を選択します。[Timing] タブでイベントを Ctrl キーを押しながらとダブルクリック、または Timing イベントをクリックして、Enter キーを押して選択することもできます。[Frames] パネルでフレームをクリックする方法もあります。これを行うと、選択した時間範囲が青色のオーバーレイとして表示され、その長さの合計が上部に表示されます。[Timers] タブと [Counters] タブには、その時間範囲内のデータのみが表示されます。F を押すと、選択した時間範囲に直接ズームおよびパンできます。

4.25 では、同じタイプ (タイマー) のすべてのタイミング イベントを強調表示 (フィルタリング) するには、Timing View でタイミング イベントをダブルクリックします。

Timer タブ

[Timers] タブには、[Timing] パネルで指定した時間範囲内に実行されたすべてのタイマー イベントがリストされます。このリストは、時間範囲に基づいてデータを集計するだけでなく、アクティブな列の値で昇順または降順にソートすることもできます。ソート順を変更したり、列をアクティブまたは非アクティブにするには、リスト内の任意の場所を右クリックします。[Timers] タブには以下の列を使用できます。[Timer] タブには以下の列を使用できます。

• Meta Group Name (メタグループ名)

• Type (タイプ)

• Instance Count (インスタンス数)

• Total Inclusive Time (総包括時間)

• Max Inclusive Time (最大包括時間) (ms)

• Average Inclusive Time (平均包括時間) (ms)

• Median Inclusive Time (中央値包括時間) (ms)

• Min Inclusive Time (最小包括時間) (ms)

• Total Exclusive Time (総排他時間)

• Max Exclusive Time (最大排他時間) (ms)

• Average Exclusive Time (平均排他時間) (ms)

• Median Exclusive Time (中央値排他時間) (ms)

• Min Exclusive Time (最小排他時間) (ms)

[Group By (グループ化)]

Counters タブ

[Counters] タブには、同じ期間中に増分されたすべての統計がリストされます。ユーザーは順序と行の並びを Timer タブと同じ方法で更新することができます。[Counters] タブには以下の列があります。

• Meta Group Name (メタグループ名)

• Type (タイプ)

• Count (数)

• Sum (合計)

• Maximum (最大値)

• Upper Quartile (上四分位数) (4.23 では実装されていない)

• Average (平均値)

• Median (中央値)

• Lower Quartile (下位四分位数) (4.23 では実装されていない)

• Minimum (最小)

[Group By (グループ化)]

Unreal Insights のリファレンス

一連のグラフをカウンタに追加する時にグラフ トラックの可視性をオンにするｔには、カウンタをダブルクリックします。

Log パネル

[Log] パネルには、UE4 セッションから (UE_LOG によって生成された) すべてのログが表示されます。ログは、エディタの [Output Log (アウトプットログ)] ウィンドウと同様に、冗長性とカテゴリによってフィルタリングできます。また、入力したテキストと一致しないすべてのログ メッセージをフィルタリングする検索ボックスもあります。フィルタリングに加えて、任意の行をクリックすると、その行のテキストが記録された時間に [Timing] パネルが移動します。

[Timing] パネルで期間を選択すると、その期間内のすべてのログ エントリが青色でハイライト表示されます。逆に、1 つのエントリをクリックしてから別のエントリを Shift キーを押しながらクリックして複数のログ エントリを選択した場合は、これらのエントリ間の時間範囲が強調表示されます。

Asset Loading Insights ウィンドウ

Unreal Insights Tool では、アセットのロード パフォーマンス解析のために [Asset Loading Insights] ウィンドウが用意されています。このウィンドウには、アセットのロードに関連するイベントにフォーカスして設定された Timing Insights ビューの [Timing] パネルの特殊なバージョンが含まれています。

-loadtimetrace

Memory Insights ウィンドウ

デベロッパーは [Memory Insights (メモリ インサイト)] ウィンドウでアプリケーションのメモリ使用を視覚的に確認することができます。メモリの使用状況を把握できるため、自分の作業がアプリケーションのパフォーマンスやエンジンの動作にどのように影響するかをより詳しく理解できるようになりました。

メモリ使用は次のデフォルト グラフ トラックで表示されます。

• Total (合計)

• TrackedTotal (合計 (追跡済み))

• Untracked (未追跡)

• Meshes (メッシュ)

• Textures (テクスチャ)

• Physics (物理)

• Audio (オーディオ)

使用方法

アプリケーションのメモリ使用をトレースするには、[Level Editor] - [Play] > [Play in Standalone Game] の中にある [Additional Launch Parameters (追加起動パラメータ)] テキストボックスに「-trace=memory」と入力します。

-trace=memory implies -llm

Memory Graph パネル

[LLM Graphs (LLM グラフ)] パネルには、それぞれの LLM タグごとの時間経過に伴うメモリ使用の変動が LLM タグごと表示されます。[Memory Graph] パネルには、表示可能な範囲で最大値および最小値を含むカスタム垂直軸グリッドがついています。トラックの右側にマウス カーソルを置くと、現在の最小値と最大値の間にデルタ値が表示されます。ただし、これらの値が互いに等しくない場合に限ります。

LLM Tags パネル

[LLM Tags] パネルには、使用可能な LLM タグがリスト表示されます。リスト表示された各 LLM タグには次の属性があります。

ユーザーは LLM タグをダブルクリックすると、メモリ グラフ トラックを追加または削除することができます。さらに、ユーザーはトラッカーごとに LLM タグをソートしたりグループ化することもできます。

チャンネル

チャンネルとは、デベロッパーがイベントを指定されたグループに分類する方法を提供する新しい概念です。チャンネルによりデベロッパーは生成したトレース データの量を管理できるようになり、その結果パフォーマンスの向上と空間の節約につながります。現在、チャンネルはデフォルトで無効になっていますが、ユーザーはライブ セッション中にオンオフの切り替えができます。

Insights Data Source Filters プラグインと Trace Data Filtering プラグインをエディタから有効にするには、[Editor] > [Plugins] > [Built-In] を確認します。もしくは、プロジェクトの「*.uproject」ファイルでプラグインを有効にします。

{
    "FileVersion":3,
    "EngineAssociation":"4.25",
    "Category": "",
    "Description": "",
    "Plugins": [
        {
            "Name":"TraceSourceFilters",
            "Enabled": true
        },
        {
            "Name":"TraceDataFilters",
            "Enabled": true
        }
    ]
} 

Unreal Insights のリファレンス

プロジェクトの出力をカスタマイズする

エンジン、プラグイン、またはプロジェクトのソース コードに小さな変更を加えることで、Unreal Insights の特定の機能を有効または無効にしたり、カスタム ログを追加したりできます。

ロギングをアクティブ化もしくは非アクティブ化する

ログ データを送信する領域を制御する場合、またはシステム全体を非アクティブ化する場合は、エンジンのソース コードを編集し、特定のマクロの値を変更します。これらのマクロは、通常、関連する機能またはモジュールのヘッダ ファイルとして、エンジン全体に分散されます。これらは、ロギングがオンになっている領域では値「1」を使用し、ロギングがオフになっている領域では値「0」を使用しますが、常に、ビルドのコンテキスト内でマクロが適切かどうかを最初に決定する条件付き構造体内で定義されます。LOGTRACE_ENABLED はログ メッセージ トレースを制御するマクロで、Engine/Source/Runtime/Core/Public/Logging/LogTrace.h の次の構造体に記述されています。

#if !IS_PROGRAM && !UE_BUILD_SHIPPING && (PLATFORM_WINDOWS || PLATFORM_PS4 || PLATFORM_XBOXONE)
#define LOGTRACE_ENABLED 1
#else
#define LOGTRACE_ENABLED 0
#endif

デフォルトでは、LOGTRACE_ENABLED は Unreal Insights システムにログ データを送信することが適切な場合に「1」として定義されます。非アクティブ化するには、上記のコードの 2 行目を変更して、LOGTRACE_ENABLED を「0」ではなく「1」として定義します。

Unreal Insights のリファレンス

カスタム CPU スコープ タイマーを追加する

独自のエンジンの機能、プラグイン、またはプロジェクトにログを追加するには、プロファイルするスコープで TRACE_CPUPROFILER_EVENT_SCOPE マクロを起動します。このマクロは、1 つのテキスト引数を使用して、生成するプロファイル データを所有するトレース グループを識別します。任意の名前を使用できますが、一般的な例は TRACE_CPUPROFILER_EVENT_SCOPE(TEXT("MyClass::Function")) や TRACE_CPUPROFILER_EVENT_SCOPE(TEXT("ReticulatingSplines")) のようになります。TRACE_BOOKMARK マクロと UE_LOG マクロは Unreal Insights に表示されるので、調査したいコード領域の近くにログを置くと、データを解析するときに必要な情報をすばやく見つけるのに役立ちます。

Insights Log

Insights Log (インサイト ログ) は Unreal Insights に固有のメッセージ ログを表示します。以下は、Insights Log が LLM XML レポート ファイルをパースした結果の警告とエラーを表示している例です。

プラットフォームの詳細

Unreal Insights を使用すると、Android と PC のように、複数のプラットフォーム上でのデータ収集が可能になります。

Android

Android Debug Bridge (adb) を使用すると、Android ツールは USB ケーブル上で TCP トラフィックをリダイレクトすることができます。Android デバイスでランタイム アプリケーションを接続するには、まず USB 接続を介して、デバイス上に作成された TCP 接続を流すように adb に指示します。

adb.exe reverse tcp:1980 tcp:1980

デバイス上で実行する時はオペレーティング システムが USB ケーブルでトラフィックをルートするように localhost に接続します。

-tracehost=127.0.0.1

Android プロジェクトでこれらの CLI 引数を次の 2 つの方法のいずれかで使用することができます。

UE4CommandLine.txt という名前の空のテキスト ファイルに -tracehost=127.0.0.1 を追加します。次に adb push <path_to>\UE4CommandLine.txt /mnt/sdcard/UE4Game/<project_name>/UE4CommandLine.txt を実行します。

または adb shell setprop debug.ue4.commandline -tracehost=127.0.01 を実行することもできます。これは、デバイスがオンになっている間のみ持続します。

これらのいずれかの方法で、コマンドライン引数がご使用のデバイスのアプリケーションに追加されます。その後、アプリケーションを通常どおりに、または adb shell am start -n com.<your_company_name>.<project_name>/com.epicgames.ue4.GameActivity を使ってアプリケーションを実行することができます。

ファイル

トレースは -tracefile=PATH コマンドライン引数を使ってファイルに出力することができます。PATH の値はトレース中のプラットフォーム (PC と Android を含む) 固有になります。

PC

-tracefile=d:/foo/bar.utrace

Android

-tracefile=/sdcard/UE4Game/foobar.utrace

/sdcard/