Unreal Insights の概要

Unreal Insights アプリケーション ツールの概要

Windows
MacOS
Linux

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

設定

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

UnrealInsightsProjectVisualStudio.png

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

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

  • "-tracehost=X" 引数はリモート デバイス、Mac、Linux 上での起動時のみ必要となります。

  • Windows (それが「discoverable」モードの場合) 上で起動する場合、ランタイムで自動的に Unreal Insights に接続されます。

Unreal Insights — ブラウザ

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

UnrealInsightsBrowser.png

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

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

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

非推奨機能

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

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

UnrealInsightsStopped.png

開始ボタンがついた Unreal Insights v0.10

Unreal Insights — ビューア

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

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

Timing Insights ウィンドウ

[Timing Insights] ウィンドウには、CPU と GPU に関するフレームごとのパフォーマンス データが表示されます。いくつかのパネルでは、プロジェクトがさまざまなタスクに費やした時間をさまざまに可視化して表示したり、時間ブロックを選択して集計を表示したり、データを並べ替えたり分類したり、ログ出力を確認することができます。パネルごとに表示または非表示にできます。

Timing Insights を開く方法については、「Unreal Insights のリファレンス 」を参照してください。

TimingInsightsPanels.png

[Timing Insights] ウィンドウは、フレーム パネル (1)、タイミング パネル (2)、ログ パネル (3)、[Timers] タブと [Counters] タブ (4) [Callers] パネルと [Callees] パネル (5) で構成されています。

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

[Timers] パネルと [Counters] パネルにある !0 トグルを使って、合計してゼロになるインスタンス数 (総数) でタイマーとカウンターをフィルタ処理します。

フレーム パネル

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

FramesPanel.png

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

Timing パネル

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

TimingPanel.png

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

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

TracksDropdown.png

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

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

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

UnrealInsightsEventFiltering.png

同類のタイミング イベントが強調表示され、他のすべてのタイミング イベントは薄い色で表示されます。

Timer タブ

[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] ドロップダウン リストボックスがあり、名前または種類ごとにリストをグループ化したり、すべてのリストを 1 つのフラット グループに結合することもできます。次に、グループを展開したり折りたたんだりして、必要なデータだけを表示できます。

TimersTabByName.png

Timer Name の分類による Timer タブのデータ

Counters タブ

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

  • Meta Group Name

  • Type

  • Count

  • Sum

  • Maximum

  • Upper Quartile (4.23 では実装されていません)

  • Average

  • Median

  • Lower Quartile (4.23 では実装されていません)

  • Minimum

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

UnrealInsightsCounters.png

フラットにグループ化された Counters タブ データ

現在 [Stats Counters (統計情報カウンタ)] タブは実験的機能とみなされているため空でデフォルトでは非アクティブです。実験的機能の Stats and Counters については、「Unreal Insights のリファレンス 」を参照してください。

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

UnrealInsightsCountersGraph.png

STAT_PageAllocatorTree グラフ トラック

ログパネル

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

LogPanel.png

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

Asset Loading Insights ウィンドウ

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

AssetLoadingInsights.png

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

チャンネル

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

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 に表示されるので、調査したいコード領域の近くにログを置くと、データを解析するときに必要な情報をすばやく見つけるのに役立ちます。

プラットフォームの詳細

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

Android

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

adb.exe reverse tcp:1980 tcp:1980

Unreal Insights は 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

ユーザー指定パスはすべて動作しますが、Android OS のバージョンおよびデバイス メーカーによって /sdcard/ パスは変わる場合があります。

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback