[UE4] PerfReportToolを用いたパフォーマンスレポート作成

1. はじめに

[検証バージョン：4.24.0]
　4.23から追加されたPerfReportToolはCSVProfilerで取得したデータをグラフ化するためのコマンドラインツールです。このツールを利用することでCSVProfilerで出力した.csvファイルを.htmlファイルに変換し、パフォーマンス推移グラフとして可視化することができます。
　ざっくり言えば**「カッコイイパフォーマンスレポートを作るツール」**です。

[基礎知識]
公式ドキュメント：CSV Profiler
Qiita：[UE4] CSV Profileを用いたパフォーマンス計測

　これらのツールを用いることで以下のようなパフォーマンスレポートを作成することができます。これはCSVProfilerから取得した各パフォーマンス情報をグラフ化して.html形式に変換したものとなります。
　(※図が大きいのでクリックして拡大を推奨)

ヒッチ検出回数を表にしたり、作成される多くのグラフに対してGraphsからジャンプできます。

Stat Unit単位でのレポートされたグラフです。シナリオ単位で作成しておくと便利です。

Actor CountやPhysical Memoryなどの推移グラフも作成します。バジェットを決めるのにも役に立ちます。

Render Threadのパフォーマンスレポートグラフです。どの処理で負荷となっているかを確認できます。

2. 使い方

　PerfReportToolを利用してパフォーマンスグラフを作成する手順は以下の２つです。

【PerfReportToolでパフォーマンスグラフを作成する手順】
① CSVProfilerでアプリケーションのプロファイルデータ(.csv)を取得
　CSVProfilerの使い方を参考に、csvprofile start/csvprofile stopコマンドを利用して取得できます。

② PerfReportToolでプロファイルデータ(.csv)を.html形式に変換
　PerfReportToolはコマンドラインツールのため、必要な引数とプロファイルデータを渡すことで変換します。

2.1. 通常モード

　以下は②のバッチファイル例で、プロジェクト構成に沿って編集することで直ぐに活用できます。

PerfReportTool.bat

@echo off
rem ---------- Common ----------
rem Engineルートパス
set ENGINE_PATH=G:\GitHub\UnrealEngine-4.24
rem Toolパス
set TOOL_PATH=\Engine\Binaries\DotNET\CsvTools\PerfreportTool.exe

rem ---------- Option ----------
rem 対象csvパス
set CMD_CSV=-csv G:\Report\Profile(20191204_232056).csv
rem 出力先指定
set CMD_O=-o G:\Report\
rem オプション
set OPTION=%CMD_CSV% %CMD_O%

@echo on
%ENGINE_PATH%%TOOL_PATH% %OPTION%

このバッチファイルを利用すると、パフォーマンスレポートを作成します。
完成後に以下のように出力されます。

ここで作成されたレポートは、1.はじめにで載せたグラフと以下のようなサマリーが出力されます。

2.2. Bulkモード

　通常モードは**「１つのcsvprofileからレポートを作成するモード」であるのに対して、Bulkモードは「複数のcsvprofileから纏めてレポートを作成するモード」です。このモードは、-csvで.csvファイルを指定した場合は通常モード**、-csvdirで.csvファイルがあるディレクトリを指定した場合はBulkモードとなります。以下は②のバッチファイル例で、プロジェクト構成に沿って編集することで直ぐに活用できます。

PerfReportTool.bat

@echo off
rem ---------- Common ----------
rem Engineルートパス
set ENGINE_PATH=G:\GitHub\UnrealEngine-4.24
rem Toolパス
set TOOL_PATH=\Engine\Binaries\DotNET\CsvTools\PerfreportTool.exe

rem ---------- Option ----------
rem 対象csvディレクトリ
set CMD_CSV=-csvdir G:\Report\
rem 出力先指定
set CMD_O=-o G:\Report\
rem オプション
set OPTION=%CMD_CSV% %CMD_O%

@echo on
%ENGINE_PATH%%TOOL_PATH% %OPTION%

このバッチファイルを利用すると、指定のディレクトリ(G:\Report)から複数のパフォーマンスレポートをまとめて作成します。完成後に以下のように出力されます。

Bulkモードでは複数のパフォーマンスレポートのサマリーが出力されます。

3. 引数一覧

　PerfReportToolに対して指定するオプション引数は \Engine\Source\Programs\CSVTools\PerfReportTool\PerfReportTool.csに記載されているのでそちらをご参考ください。以下の表でもう少し説明しています。

引数	説明
フォーマット
-csv [filepath]	対象.csvパス
-csvdir [dirpath]	対象.csvディレクトリパス (Bulkモード)
-o [dirpath]	出力先ディレクトリ
オプション
-reportType [type]	レポート出力タイプ1
-reportTypeCompatCheck	レポート出力タイプ互換性チェック
-graphXML [xmlfilename]	グラフ用.xmlファイル
-reportXML [xmlfilename]	レポート用.xmlファイル
-reportxmlbasedir [folder]	レポート用.xmlベースディレクトリ
-title [titleName]	レポートタイトル名
-minx [frameNumber]	グラフ用X最小値(最小フレーム番号)
-maxx [frameNumber]	グラフ用X最大値(最大フレーム番号)
-maxy [value]	グラフ用Y最大値(最大値)
-graphScale [value]	グラフの大きさスケール値2
-noStripEvents	除外イベント削除
-perfLog	レポート作成のパフォーマンスログ出力
-writeSummaryCsv	FrameStats/HitchStats出力許可
-beginEvent [event]	レポート開始イベント名
-endEvent [event]	レポート終了イベント名
オプション:Bulkモード
-recurse	.csvファイルのサブディレクトリ検索許可
-searchpettern [pattern]	.csvファイルの検索パターン3
-customTable [comma seprated fields]	カスタムテーブル利用項目4
-customTableSort [sort order]	カスタムテーブルソート指定
-noDetailedReport	.csvの個別レポート作成非許可設定
-collateTable	カスタムテーブルへのマージ作成
-emailTable	Email送信時に適した要約テーブル作成
-csvTable	.csv形式でのサマリーテーブル出力
-summaryTable [type]	サマリーテーブルレポート出力タイプ5
-summaryTableFilename [name]	サマリーテーブルレポート名指定
-metadataFilter [key=value,...]	フィルタリング時の.csvメタデータ指定
-precacheCount [n]	事前キャッシュファイル数
-precacheThreadCount [n]	事前キャッシュスレッド数
-readAllStats	全項目強制出力
-externalGraphs	DetailReport出力時の.svg出力指定

4. まとめ

　PerfReportToolを利用することで、CSVProfilerで取得したパフォーマンスキャプチャデータから簡単にパフォーマンスレポートを作成することができます。CIの１つのシナリオに、Csvprofile＋Perfreport作成を組み込んでおくことで、日々のパフォーマンスを監視することに役に立つと思いますので是非ご活用ください。

1. \Engine\Binaries\DotNET\CsvTools\ReportTypes.xml 内のreporttypes タグ参照 (Default60fps/Default30fps/Memory) ↩

2. おススメは0.5 ("-graphscale 0.5") ↩

3. "-searchpettern csvprofile*"のようなワイルドカード指定等が可能 ↩

4. 固定フォーマットのSummaryTableではなく、指定した独自のカスタムサマリーを出力 ↩

5. \Engine\Binaries\DotNET\CsvTools\ReportTypes.xml 内のsummaryTables タグ参照 (all/default/memory/condensed) ↩