Unreal Insights Trace Capture

Last updated on August 18, 2026

注釈：本資料はAI技術を用いて翻訳されています。

概要​

Unreal Insights Trace Captureを使用すると、Unreal Engineスタジオは、ADTで管理されるゲームセッション中に.utraceパフォーマンス記録を自動的に収集し、そのファイルを他のすべてのセッションデータと一緒に一元的に保存できます。ADTはすでに各セッションのビルドバージョン、プラットフォーム、デバイス、プレイヤーIDを追跡しているため、すべてのトレースは事前に情報が付加された状態で届きます。開発者は、手動での紐付け作業をすることなく、特定のビルド、テスター、デバイスに既に関連付けられたファイルを開くことができます。

この機能はオプトイン方式で、チャネルまたはトラックレベルで設定します。トレースの解析は引き続きUnreal Insightsで行います。ADTはストレージ、コンテキスト、アクセスを担当します。ADTはUnreal Insightsを置き換えるものではありません。

Trace Captureが存在する理由​

ゲームセッションでパフォーマンスの問題が報告された場合、開発者は通常、それを調査するために.utraceファイルを必要とします。手動のワークフローでは、そのファイルはテスターのマシンにローカルに保存され、共有された場所には保存されません。また、どのビルドから生成されたか、どのセッションで生成されたか、誰が実行したかの記録もありません。

その結果、開発者は深い診断を完全にスキップしてしまいます。トレースを見つけてコンテキストを把握するのに、調査そのものよりも時間がかかってしまうためです。あるいは、テスターにそのセッションを再現するようにトレースキャプチャを目的として依頼することになりますが、これはテスターにとって煩わしく、また元の条件を再現できるとは限りません。

ADTはすでにセッションのコンテキストを保持しています。不足しているのは、.utraceファイルがキャプチャされ、それに紐付けられていない点です。この機能はそのギャップを埋めます。

Trace Captureの仕組み​

ADT Hubでチャネルまたはトラックに対してTrace Captureが有効になっている場合、その設定から起動される各セッションで以下が行われます。

  1. 起動時：ADTが適切なトレース起動引数を挿入し、ゲームは即座に記録を開始します。テスターによる操作は不要です。
  2. セッション中：トレースは既定のUnreal Engine出力ディレクトリ（Saved/Profiling/）に記録されます。QAは、実行中のオートキャプチャトレースを中断せずに、Unreal Engineの組み込みコンソールコマンドを使用してセッション中に対象を絞ったスナップショットをトリガーすることもできます。
  3. セッション終了時：ADT HubはSaved/Profiling/内の.utraceファイルを検出し、バックグラウンドでADTにアップロードします。接続が遅い場合、アップロードはゲームが終了した後も継続します。
  4. セッション詳細ページ：トレースは、クラッシュ、バグレポート、その他のセッションアーティファクトと並んでTracesタブに表示されます。各エントリには、キャプチャ種別、タイムスタンプ、期間、記録チャネル、プラットフォーム、ファイルサイズが表示されます。
  5. 調査時：開発者はADTからトレースをダウンロードし、Unreal Insightsで開きます。ADTはブラウザ内でのトレースビューアーを提供しません。
Enable trace capture in ADT Hub (Channel or Track settings)
        ↓
Tester launches game → trace records automatically
        ↓
Session ends → ADT Hub detects and uploads trace file
        ↓
Trace appears on Session detail page in ADT Web
        ↓
Developer downloads trace and opens in Unreal Insights

キャプチャ方法​

この機能内でトレースを生成する方法は3つあります。

方法トリガーする担当者使用するタイミング
起動時の自動キャプチャADT（テスターの操作は不要）デフォルトの方法 — セッション全体をキャプチャします
セッション中のスナップショットUEのゲーム内コンソール経由でQAが実行（Trace.SnapshotFile）オートキャプチャを停止せずに、特定の瞬間を対象としたキャプチャを行う場合
セッション中の開始/停止UEのゲーム内コンソール経由でQAが実行（Trace.Start / Trace.Stop）オートキャプチャが実行されていない場合の、対象を絞ったキャプチャ

セッション中のキャプチャについては、ファイルがSaved/Profiling/に出現した時点でADTが自動的に取得し、アップロードします。QAによる追加の操作は不要です。

主なメリット​

  • コンテキストがすでに揃っている。 すべてのトレースは、特定のビルドバージョン、セッション、プラットフォーム、テスターに紐付けられています。開発者は、手動でコンテキストを再構築するのではなく、完全な診断コンテキストを最初から得られます。
  • テスターの操作が不要。 起動時の自動キャプチャにより、テスターが何かを設定したりトリガーしたりする必要なく、すべてのセッションのトレースが収集されます。
  • 一元的なアクセス。 トレースは、セッションへのアクセス権を持つすべての開発者がADT Webから利用できます。テスターのローカルマシンに限定されません。
  • 既存のワークフローと連携する。 ADTはUnreal Insightsを置き換えるものではありません。トレースを保存して表示することで、開発者は既存のツールで即座にそれを開くことができます。
  • チャネルおよびトラック単位で設定可能。 スタジオは、特定のチャネルまたは個々のトラックに対してTrace Captureを有効にできます。また、設定ごとに記録チャネルと保持期間を個別に設定できます。これにより、スタジオはトレースの詳細度とファイルサイズ・ストレージコストのバランスを取ることができます。

制限事項と考慮事項​

ビルド要件。 Trace Captureには、ゲームがUE_TRACE_ENABLEDフラグ付きでコンパイルされている必要があります。このフラグがないビルドでは、.utraceファイルは生成されません。Trace Captureが有効なセッションを実行してもトレースが表示されない場合、最も可能性の高い原因は、ビルドがこのフラグ付きでコンパイルされていないことです。

デフォルトの記録プロファイルは軽量です。 デフォルトのチャネルセット — CPU、GPU、Frame、Bookmark — は、1分あたり数十メガバイト程度の低容量のトレースファイルを生成します。より負荷の高いチャネル（Memory、Load time、RHI commands、Object tracking）はオプトインの追加項目として利用できますが、長時間のセッションではトレースサイズが1分あたり100 MBを超える場合があります。

保持期間が短い。 トレースファイルはセッションおよびビルドとは別の保持ポリシーを持ち、スタジオごとに1日から7日の範囲で設定可能です。トレースファイルは、親セッションおよびビルドのレコードよりも先に期限切れになる場合があります。期限切れになったトレースは、セッション詳細ページに「Expired」のラベルで表示され続けますが、ファイルはダウンロードできなくなります。

セッション中の警告。 Trace.SnapshotFileではなくTrace.Startを使用してセッション中にキャプチャされたトレースは、Unreal Insightsでいくつかのイベントに「unknown」ラベルが表示される場合があります。これは、CPUスコープ名やスレッド名などの一部のメタデータがエンジン初期化時に一度だけ発行されるため、起動後に開始されたトレースには含まれない場合があるためです。ADTはこれらのエントリに警告を表示します。

Trace.Stopはすべてのチャネルをグローバルに停止します。 これはUnreal Engineのネイティブな動作です。オートキャプチャが実行されている状態でQAテスターが手動でのセッション中キャプチャを終了するためにTrace.Stopを実行すると、両方のトレースが同時に停止します。オートキャプチャが有効な場合は、Trace.Start/Trace.Stopの代わりにTrace.SnapshotFileを使用してください。

セッション中のFPS低下によってトリガーされるキャプチャはv1.xには含まれません。 検出されたFPS低下によって自動的にトリガーされるキャプチャは、将来のフェーズで提供予定です。v1.xでは、キャプチャはセッション起動時の自動実行か、UEコンソールコマンドによる手動トリガーのいずれかです — セッションのTracesタブには、AutoまたはMid-sessionのエントリのみが表示されます。

サポートされているプラットフォーム​

エンジンプラットフォーム状況
Unreal Engine 5.3+Windows、macOS、Linuxサポート対象
Unreal Engine 5.3+コンソール、モバイル未サポート（将来対応予定）
Unityすべてサポート対象外

コンソールおよびモバイルのサポートは将来のバージョンに見送られています。ADT SDKのファイルシステム監視は、v1.xではデスクトップビルド（Windows、macOS、Linux）のみで検証されています。

次のステップ​

に最終更新
On this page