Unreal Engine 5 ドキュメントは Epic Developer Community に移動しました

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 )。

-cpuprofilertrace などのいくつかのコマンド引数は 4.26 リリースで除去されました。詳細は、「 Unreal Insights のリファレンス 」を参照してください。

ファイルのトレースは実行時に trace.start [channel0[,channel1...]] コンソール コマンドを使用して開始することができます。.utrace ファイルはプロジェクトのデフォルト プロファイリング ディレクトリ (usually /Saved/Profiling) に置かれ、Unreal Insights のブラウザ ペインにドラッグ アンド ドロップすることで 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] タブでデータを集約します。これを行うには、フレーム パネルで 1 つのフレームをクリックするか、タイミング パネルの上部にあるスクラブバーのセクション ( タイム ルーラー ) をクリックしてドラッグします。

!0

フレーム パネル

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

タイミング パネル

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

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

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

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

Timers タブ

[Timers] タブには、[Timing] パネルで指定した時間範囲内に実行されたすべてのタイマー イベントがリストされます。時間範囲に基づくデータ集計を行うだけでなく、アクティブな列の値を昇順または降順に並べ替えることもできます。並べ替え順序を変更したり、列をアクティブまたは非アクティブにするには、リスト内の任意の場所を右クリックします。[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] パネルには、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 ウィンドウでアプリケーションのメモリ使用を視覚的に確認することができます。メモリ使用を見える化することで、チームはアプリケーションのパフォーマンスとエンジンの動作に与える作業量を把握しやすくなります。

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

• 合計

• 合計 (追跡済み)

• 未追跡

• メッシュ

• テクスチャ

• 物理

• オーディオ

使用方法

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

-trace=memory implies -llm

メモリ グラフ パネル

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

LLM タグ パネル

LLM タグ パネルには、使用可能な 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

ファイル

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

PC

-tracefile=d:/foo/bar.utrace

Android

-tracefile=/sdcard/UE4Game/foobar.utrace

/sdcard/