Unreal Insights

パフォーマンス プロファイリングのための Unreal Insights システム

Windows
MacOS
Linux

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

Unreal Insights システムを設定する

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

UnrealInsightsProjectVisualStudio.png

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

-tracehost=X

ライブ セッションは、次の画像のようにツールに表示されます。

UnrealInsightsLiveSession.png

ツールの内部には 3 つのウィンドウがあり、それぞれのウィンドウはユーザー インターフェースの上部にあるタブで示されます 1 つは [Unreal Insights] ウィンドウ で、ライブ セッションまたは録画済みセッションを接続、切断、選択して表示することにより、さまざまなセッションを管理できます。残りの 2 つ、[Timing Insights] ウィンドウ[Asset Loading Insights] ウィンドウ は、パフォーマンス データを参照および可視化し、セッションが表示可能になると表示されます。

Unreal Insights ウィンドウ

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

UnrealInsightsToolOpening.png

[Unreal Insights] ウィンドウが開きました。

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

UnrealInsightsLiveSession.png

[Unreal Insights] ウィンドウでリアルタイム分析が可能なライブセッションです。

[Trace Recorder] セクションには、[Stop] ボタンがあり、ツールを閉じずにトレース記録を停止できます。これは、必要なデータを収集した後、セッションが終了する前に、ライブ セッションへの新しいデータのフローを停止する場合に便利です。これにより、データが読みやすくなります。このボタンを押すと、現在実行中のセッションからツールが切断され、新しいセッションが接続できなくなります。記録停止中は、[Stop] ボタンの代わりに [Start] と表示されます。記録を再開すると、新しいリモート UE4 セッションは接続可能になりますが、トレース記録が停止している間に開始されたセッションには接続されず、[Stop] ボタンでドロップされたセッションには再接続されません。

UnrealInsightsStopped.png

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

Timing Insights ウィンドウ

[Timing Insights] ウィンドウには、CPU と GPU に関するフレームごとのパフォーマンス データが表示されます。いくつかのパネルでは、プロジェクトがさまざまなタスクに費やした時間をさまざまに可視化して表示したり、時間ブロックを選択して集計を表示したり、データを並べ替えたり分類したり、ログ出力を確認することができます。これらのパネルの表示や非表示を切り替えるには、一番上の行にある [Frames][Timing][Timers][Stats]、および [Log] という名前のボタンを使用します。これらのボタンは、[Frames] パネル、[Timing] パネル、[Timers] タブ、[Stats Counters] タブ、および [Log] パネルをそれぞれ表示または非表示にします。

TimingInsightsPanels.png

[Timing Insights] ウィンドウには、(1) [Frames] パネル、(2) [Timing] パネル、(3) [Log] パネル、(4) [Timers] タブと [Stats Counters] タブ ([Timers] タブをアクティブにした状態) があります

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

Frames パネル

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

FramesPanel.png

[Frames] パネル内で選択されたフレーム白いブラケットマーカーは、[Timing] パネル内に表示されるフレームのセットを示します。

Timing パネル

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

TimingPanel.png

(1) [Timing] パネル内のタイマー イベントにカーソルを合わせたときに表示されるツールチップ。(2) 同じスレッド上のネストされたイベントのスタック。

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

TracksDropdown.png

[Timing] パネルには、含まれているスレッドに基づいてトラックのグループを表示または非表示にするドロップダウン メニューがあります。

[Timing] パネルを操作するときに、特定の時間範囲の集計データを表示することができます。[タイム ルーラー] をクリックしてドラッグするか、[Timing] タブでタイマー イベントをダブルクリックするか、[Frames] パネルでフレームをクリックして、調べる期間を選択できます。これを行うと、選択した時間範囲が青色のオーバーレイとして表示され、その長さの合計が上部に表示されます。[Timers] タブと [Stats Counters] タブには、その時間範囲内のデータのみが表示されます。「F」を押すと、選択した時間範囲に直接ズームおよびパンできます。

Timers タブと Stats Counters タブ

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

[Timers] タブについては以下のとおりです。

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

[Stats Counters] タブについては以下のとおりです。

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

  • Type (型)

  • Count (カウント)

  • Sum (合計)

  • Maximum (最大値)

  • Upper Quartile (上四分位数) (4.23 ではまだ実装されていません)

  • Average (平均値)

  • Median (中央値)

  • Lower Quartile (下位四分位数) (4.23 ではまだ実装されていません)

  • Minimum (最小値)

どちらのリストにも [Group By] ドロップダウン リストボックスがあり、リストを名前またはタイプでグループに分けたり、すべてを 1 つのフラット グループに結合することもできます。次に、グループを展開したり折りたたんだりして、必要なデータだけを表示できます。

TimersTabByName.png

[Timers] タブは、名前に基づいてグループに分類されます。

この機能は実験的なものであり、デフォルトでは無効になっているため、デフォルトでは [Stats Counters] タブは空になっています。

Log パネル

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

LogPanel.png

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

クイック コントロール リファレンス

次のマウス コマンドとキーボード コマンドを使用すると、Timing Insights をより効率的にナビゲートできます。これはすべての入力操作を網羅したリストではなく、将来ツールが開発されるにつれて変更される可能性があります。

入力

機能

マウス ホイール

トラックをズームイン / ズームアウトをします

Shift + マウス ホイール

トラックを垂直方向にスクロールまたはズームします

Ctrl + マウス ホイール

トラックを水平方向にスクロールまたはズームします

「C」キー

コンパクトモードに切り替えます

「F」キー

選択した時間範囲に画面を合わせます

「Y」キー

GPU トラックに切り替えます

「U」キー

CPU トラックに切り替えます

「I」キー

I/O トラックを表示 / 非表示 (デフォルトでは非表示) にします

「V」キー

空のタイムライン トラックの表示を切り替えます

「B」キー

[Timing] パネルでのブックマークの表示を切り替えます

「M」キー

[Timing] パネルのすべてのログ メッセージのマーカー表示を切り替えます

「L」キー

Asset Loading トラックを表示 / 非表示 (デフォルトでは非表示) にします

「G」キー

グラフを切り替えます

「Ctrl」 + 「+」キー

ズームインします

「Ctrl」 + 「-」キー

ズームアウトします

「Ctrl」 + 「Left」キー

左にパンします

「Ctrl」 + 「Right」キー

右にパンします

Asset Loading Insights ウィンドウ

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

AssetLoadingInsights.png

[Asset Loading Insights] ウィンドウは、アセットのロードに関連するパフォーマンスにフォーカスしています。ここに示すセッションは、-loadtimetrace コマンドライン オプションを使用して記録されたものです。

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

エンジン、プラグイン、またはプロジェクトのソース コードに小さな変更を加えることで、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

デフォルトでは、Unreal Insights システムにログ データを送信することが適切なビルドでは、LOGTRACE_ENABLED は「1」として定義されます。非アクティブ化するには、上記のコードの 2 行目を変更して、LOGTRACE_ENABLED を「0」ではなく「1」として定義します。次の表を使用して、Unreal Insights Tool で表示するデータに基づいて調整するマクロを決定します。

Macro name

Default State

Source File

Area Description

UE_TRACE_ENABLED

On

Engine/Source/Runtime/TraceLog/Public/Trace/Private/Trace.h

システム全体のマスター コントロールです

LOGTRACE_ENABLED

On

Engine/Source/Runtime/Core/Public/Logging/LogTrace.h

ログ メッセージを Unreal Insights にレポートするかどうかを制御します

MISCTRACE_ENABLED

On

Engine/Source/Runtime/Core/Public/ProfilingDebugging/MiscTrace.h

ブックマーク、フレーム、スレッド、スレッド グループのトレースを制御します

CPUPROFILERTRACE_ENABLED

On

Engine/Source/Runtime/Core/Public/ProfilingDebugging/CpuProfilerTrace.h

CPU タイマーおよびタイミング イベントのトレースを制御します

LOADTIMEPROFILERTRACE_ENABLED

On

Engine/Source/Runtime/CoreUObject/Public/Serialization/LoadTimeTrace.h

アセットのロードに関連するイベントのトレースを制御します

EXPERIMENTAL_STATSTRACE_ENABLEDSTATSTRACE_ENABLED

Off

Engine/Source/Runtime/Core/Public/Stats/StatsTrace.h

Stats Counters のトレースを制御します。両方のマクロを「1」として定義してアクティブ化します。

PLATFORMFILETRACE_ENABLED

Off

Engine/Source/Runtime/Core/Public/ProfilingDebugging/PlatformFileTrace.h

ファイルを開く、閉じる、読み取る、書き込むなどのファイル アクティビティのトレースを制御します

GPUPROFILERTRACE_ENABLED

Off

Engine/Source/Runtime/RHI/Public/GpuProfilerTrace.h

GPU のタイマーおよびタイミング イベントを制御します

次の UE4 コマンドライン オプションと上記のマクロを組み合わせて、追加のトレース データを有効にします。

コマンドライン オプション

必要なマクロ

効果

-cpuprofilertrace

CPUPROFILERTRACE_ENABLED

このオプションを指定して実行すると、タイミング イベントを含む複数の CPU スレッド トラックがタイミング ビューに表示されます。

-statnamedevents

CPUPROFILERTRACE_ENABLED

-cpuprofilertrace と組み合わせた場合、このオプションはさらに多くの CPU タイミング イベントを起動します。

-filetrace

PLATFORMFILETRACE_ENABLED

このオプションを使用して生成されたトレースの場合、2 つの I/O アクティビティ トラックを持ち、それらは Unreal Insights Tool の [Timer] タブで「I」キーを押すか、[Tracks] ドロップダウンで [I/O Tracks] を有効にすることで表示できます。この機能は、UE4 バージョン 4.23 では試験的なものです。

-loadtimetrace

LOADTIMEPROFILERTRACE_ENABLED

このオプションを選択すると、[Asset Loading Insights] ウィンドウに「Loading - Main Thread」トラックと「Loading - Main Thread」トラックが表示されます。

カスタム ロギングを追加する

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

Select Skin
Light
Dark

新しい Unreal Engine 4 ドキュメントサイトへようこそ!

あなたの声を私たちに伝えるフィードバックシステムを含め、様々な新機能について開発をおこなっています。まだ広く使える状態にはなっていないので、準備ができるまでは、ドキュメントフィードバックフォーラムで、このページについて、もしくは遭遇した問題について教えていただけると助かります。

新しいシステムが稼働した際にお知らせします。

フィードバックを送信