🌊

Arm Mobile StudioのPerformance AdvisorをCIで使いたい

2023/05/07に公開

Android

動機

ゲーム向けにAndroidのパフォーマンス測定をCIに組み込めたら良いなと思って色々調べていたところ、Arm Mobile Studioというのが使えそうだったので試してみました。

今回はGPUのパフォーマンス測定を目的としています。

目標

Unity公式のBoatAttackのプロファイル結果をhtml形式で可視化する所までを目標とします。
アプリ起動～計測～終了までをコマンドラインで完結するようにしたいと思います。

Arm Mobile Studioについて

Arm Mobile Studioについてはこちらの動画が参考になります。

動画内でコマンドラインツールは有料といわれていますが、少し前に無料化されたようです。
今回はその無料化されたコマンドラインツールを使用していく形になります。
StreamlineとPerformance Advisorを使用します。

また、Performance AdvisorはStreamlineに統合されており、streamline-cli.exe -paのように指定することで以前と似た形で利用できます。

環境

Google Pixel 6a（Google Tensor, Mali-G78）
Arm Mobile Studio 2023.1
Python 3.11.3（3.6以上）
ADB 1.0.41

事前準備

Arm アカウントを取得

Arm Mobile Studioのインストーラーをダウンロードするには、Arm アカウントが必要です。
Arm Developerの右上のアイコンからRegisterを選択して登録します。

Arm Mobile Studioをインストール

Streamlineを使用するためには、Arm Mobile Studioというツールセットをインストールする必要があります。
製品ページのDownload Arm Mobile Studioをクリック後、ログインを行うとダウンロードページへ遷移します。（2段階認証が必要です）

インストーラーをダウンロードできたら実行し、指示に従ってインストールを行います。
デフォルトではC:\Program Files\Arm\Arm Mobile Studio 2023.1へインストールされます。

コマンドプロンプトからStreamlineの実行ファイルにパスが通っていることを確認します。

cmd.exe

> streamline-cli.exe --version
Arm Mobile Studio
Streamline 8.5 (ビルド 8.5.0.v20230412_1650)
Copyright (c) 2010-2023 by ARM Limited
All rights reserved worldwide.

Androidアプリケーションの作成

Streamlineでの計測を行うには、デバッグ可能なアプリケーションが必要です。
今回はUnity2019でARM64向けにDevelopment Buildで作成したAPKを使用しました。
端末にインストールした状態にしておきます。

キャプチャ設定ファイルの生成

キャプチャに使用する設定ファイルを事前に作成しておきます。
Streamline-gui.exeを起動してSelect applicationセクションで対象のアプリを選択すると、Configure countersボタンが有効になるのでクリックします。

筆者はGoogle Pixel 6aに搭載されているMali-G78向けのプロファイルを選択してエクスポートしました。

Mali-G78のプロファイルを選択

エクスポート

LWI(LightWeight Interceptor)経由でキャプチャ用ランタイムを起動

lwi_me.pyを使用して、キャプチャ用ランタイムを起動します。

run_lwi.bat

pushd "C:\Program Files\Arm\Arm Mobile Studio 2023.1\streamline\bin\android"

python -X utf8 lwi_me.py ^
--daemon arm64/gatord ^
--lwi-mode screenshots ^
--lwi-api vulkan ^
--lwi-fps-threshold 60 ^
--lwi-frame-gap 200 ^
--lwi-out-dir D:\Streamline\LWICap ^
--headless D:\Streamline\Capture.apc ^
--config D:\Streamline\configuration.xml ^
--package com.Unity3d.BoatAttackDay ^
--overwrite

popd

lwi_me.pyのオプションの内容については、ヘルプコマンドで確認できます。

lwi_help.bat

pushd "C:\Program Files\Arm\Arm Mobile Studio 2023.1\streamline\bin\android"

python -X utf8 lwi_me.py --help

popd
pause

主要な引数についての説明は以下の通りです。

オプション	説明
--daemon	`gatord`バイナリのパスを指定します。 ARM64向けなら`arm64/gatord`になります。
--lwi-mode	lwiの実行モードを指定します。今回はスクリーンショットを利用したいので`screenshots`を指定します。
--lwi-api	グラフィックスAPIを指定します。測定対象のパッケージと合わせる必要があります。
--lwi-fps-threshold	FPSが指定した値を下回るとキャプチャを行います。
--lwi-frame-gap	キャプチャ間の最小フレーム数を指定します。
--lwi-out-dir	キャプチャデータを指定の場所へ保存します。このフォルダはPerformance Advisorの`--frame-capture`で同じ場所を指定する必要があります。
--headless	ヘッドレスモード（手動操作が不要）で実行します。パフォーマンスキャプチャを指定のフォルダに保存します。（ZIPファイルもOK）このフォルダはPerformance Advisorで同じ場所を指定する必要があります。
--config	パフォーマンスキャプチャの設定ファイルを指定します。ヘッドレスモードでは必須です。
--package	パフォーマンスキャプチャを行うパッケージを指定します。ヘッドレスモードでは必須です。

アプリケーションを実行

アプリケーションを実行した後、60秒後に停止スクリプトを作成します。

run_app.bat

adb shell am start -n com.Unity3d.BoatAttackDay/com.unity3d.player.UnityPlayerActivity

powershell sleep 60

adb shell am force-stop com.Unity3d.BoatAttackDay

Performance Advisorでレポートを作成

generate_report.bat

pushd D:\Streamline

rem Performance Advisorを使用してレポートを作成
streamline-cli.exe -pa Capture.apc ^
--frame-capture=LWICap ^
--application-name="BoatAttack" ^
--build-name="BoatAttack" ^
--device-name="Google Pixel 6a (Mali G78)" ^
--build-timestamp="2023/05/07 18:37:00" ^
--directory=Reports

popd

Performance Advisorのヘルプコマンドは以下です。

performance_advisor_help.bat

streamline-cli.exe -pa --help

筆者の実行環境では以下のような警告が出ていました。
原因について調べてはいるものの、情報が少なく特定には至っていません。

Warning: NLS unused message: BARMAN_PROTOCOL_TITLE in: com.arm.streamline.analysis.AnalysisMessages
Warning: NLS unused message: GATOR_TITLE in: com.arm.streamline.analysis.AnalysisMessages
Warning: NLS unused message: NO_LICENSE_SUPPORT_FOR_GIVEN_CAPTURE_OR_TARGET in: com.arm.streamline.analysis.AnalysisMessages
Warning: NLS unused message: NONE_TITLE in: com.arm.streamline.analysis.AnalysisMessages
Warning: NLS unused message: PERF_TITLE in: com.arm.streamline.analysis.AnalysisMessages

~~~
WARNING: User regions not provided. You can add this using annotation instrumentation in the application. Consult the user guide for more information.
WARNING: CPU cycles data was not used. Cycles data is missing or unreliable. Use --force-cycles to force usage of this data.

実行が終了すると、下図のようなレポートが作成されます。

レポートサンプル

最終的な実行スクリプトは以下のになります。

execute.bat

@echo off

pushd "C:\Program Files\Arm\Arm Mobile Studio 2023.1\streamline\bin\android"

rem LightWeight-Interseptor経由でStreamlineキャプチャを起動
start /b python -X utf8 lwi_me.py ^
--daemon arm64/gatord ^
--lwi-mode screenshots ^
--lwi-api vulkan ^
--lwi-fps-threshold 60 ^
--lwi-frame-gap 200 ^
--lwi-out-dir D:\Streamline\LWICap ^
--headless D:\Streamline\Capture.apc ^
--config D:\Streamline\configuration.xml ^
--package com.Unity3d.BoatAttackDay ^
--overwrite

rem 60秒待つ
powershell sleep 60

rem パッケージ起動
start /b adb shell am start -n com.Unity3d.BoatAttackDay/com.unity3d.player.UnityPlayerActivity

rem 60秒待つ
powershell sleep 60
adb shell am force-stop com.Unity3d.BoatAttackDay

rem 60秒待つ
powershell sleep 60

pushd D:\Streamline

rem Performance Advisorを使用してレポートを作成
streamline-cli.exe -pa Capture.apc ^
--frame-capture=LWICap ^
--application-name="BoatAttack" ^
--build-name="BoatAttack" ^
--device-name="Google Pixel 6a (Mali G78)" ^
--build-timestamp="2023/05/07 18:37:00" ^
--directory=Reports

popd
popd

おわりに

事前準備さえしてしまえば、自動でパフォーマンス計測～レポート作成までできて、CIにも組み込めそうです。
計測用に端末が必要なこととサポート端末が限られているのがネックですが、予算が許せばCIに組み込む価値はありそうです。

以上です。
ありがとうございました。

参考

https://learning.unity3d.jp/6617/