ローカル プロファイリングのデバッグ コマンド

ProfilingManager 統合をローカルでテストする場合、レート制限によってリクエストがスロットリングされることがあります。また、トリガーのテスト時にバックグラウンド トレースがアクティブにならないことがあります。このページの adb コマンドを使用すると、テストデバイスでスロットリングの無効化、プロファイルの取得、未編集のトレースの保持、キャプチャのトリガー、サービスの状態の検査を行うことができます。

レートリミッターを無効にする

ローカルテスト中に requestProfiling リクエストのアプリプロセスとシステム レート制限を無効にするには、次の device_config コマンドを実行します。

adb shell device_config put profiling_testing rate_limiter.disabled true

テストが完了したら、フラグをリセットします。

adb shell device_config delete profiling_testing rate_limiter.disabled

ADB を使用してプロファイルを取得する

root アクセス権を持つデバイスで、秘匿化されたプロファイルをローカルで検査するには、getResultFilePath から返されたパスを指定して adb pull を実行します。

# Pull a profile
adb pull /data/user/0/<com.example.myapp>/files/profiling/<profile-file-name>

一時的な結果と秘匿化されていない結果を保持する

プロファイリングをローカルでテストする場合は、/data/misc/perfetto-traces/profiling/ の一時ディレクトリに結果を保持できます。秘匿化されていないシステム トレースと秘匿化されたシステム トレースを比較すると、秘匿化中に削除されたデータを把握できます。

一時的な結果と未編集の結果が保持される方法は、デバイスで実行されている Android のバージョンによって異なります。

  • Android 16（API レベル 36）以降: 編集されていない結果（該当する場合）と編集された結果の両方を一時ディレクトリに保持できます。このディレクトリは Android 16 で拡張され、root 権限なしですべてのビルドタイプで adb pull を使用してアクセスできるようになりました（Android 15 では /data/misc/perfetto-traces/profiling/ を読み取るために root 権限が必要です）。システムが一時的な結果を削除しないようにするには、次のコマンドを実行します。

    adb shell device_config put profiling_testing delete_temporary_results.disabled true

  • Android 15（API レベル 35）: 一時ディレクトリには、個人情報が削除されていない結果のみを保持できます。この結果には、root 権限を持つビルドでのみ adb 経由でアクセスできます。（アプリは、独自の /data/user/0/<app>/files/profiling/ ディレクトリで、編集されたプロファイルを引き続き受信します。アプリコードは、任意のビルドでこのプロファイルを読み取りまたはコピーできます。ただし、adb pull を使用して /data/user/0/... から直接 pull するには、root アクセス、またはデバッグ可能なビルドで adb shell run-as <app> が必要です）。システムが削除されていないトレースを削除しないようにするには、次のコマンドを実行します。

    adb shell device_config put profiling_testing delete_unredacted_trace.disabled true

プロファイルをキャプチャしたら、保持されているファイルを一時ディレクトリから pull します。

# Pull a retained redacted profile (Android 16 and higher)
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.<profile-type-ext>

# Pull an unredacted system trace
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.perfetto-trace-unredacted

これらのコマンドで、<trace-name> は ProfilingResult.getResultFilePath によって返されたパスのベース ファイル名（拡張子なし）です。また、削除されていないシステム トレースのコピーは、.perfetto-trace 拡張子に -unredacted を追加します。ファイル名の構造と <profile-type-ext> 値の詳細については、ファイルの場所と命名形式をご覧ください。

adb shell device_config delete profiling_testing delete_temporary_results.disabled
adb shell device_config delete profiling_testing delete_unredacted_trace.disabled

トリガーテスト用にバックグラウンド トレースを強制的に有効化する

システム バックグラウンド トレースは本番環境でランダムな間隔で実行されるため、トリガーベースのプロファイリングをローカルでテストするのは難しい場合があります。システムに継続的なバックグラウンド トレースを強制的に実行させ、アプリのトリガーに対するシステムレベルのレート制限をバイパスするには、system_triggered_profiling.testing_package_name を設定します。

adb shell device_config put profiling_testing system_triggered_profiling.testing_package_name <com.example.myapp>

setRateLimitingPeriodHours で構成されたトリガーごとのクールダウンは引き続き適用されます。このモードは、クリアするまで継続的に実行されるため、テストが終了したらフラグを削除します。

adb shell device_config delete profiling_testing system_triggered_profiling.testing_package_name

便利なデバッグ コマンド

Android 16（API レベル 36）以降で、最近の Profiling モジュール バージョンを使用している場合は、adb 経由で cmd profiling_service ツールを使用して、詳細ロギングの有効化、オンデマンド プロファイル収集のトリガー、トリガーのテストをコマンドラインから直接行うことができます。

詳細なデバッグ ロギングを有効にする

logcat で詳細な ProfilingService ログを有効にして、リクエストの処理と配信を診断するには、次のコマンドを実行します。

adb shell cmd profiling_service enable-logs true

オンデマンド プロファイル収集をリクエストする

コマンドラインから特定のパッケージのプロファイル キャプチャをすぐに開始するには、次のコマンドを実行します。

adb shell cmd profiling_service request-profiling <profiling_type> <com.example.myapp> [--user <user_id>] [--duration <duration_ms>] [--sources <sources>]

このコマンドで、<profiling_type> は ProfilingManager の整数定数値です（Java ヒープダンプの場合は 1、ヒープ プロファイルの場合は 2、スタック サンプリングの場合は 3、システム トレースの場合は 4）。メモリ プロファイルとスタック プロファイルの場合、ターゲット アプリのプロセスが実行されている必要があります。リクエストは、無効にされていない限り、レートリミッターの対象となります。完了した ProfilingResult は、registerForAllProfilingResults に登録されているグローバル リスナーにのみ配信されます。

トリガーを登録してシミュレートする

パッケージのトリガーを登録するか、シミュレートされたトリガー イベントを発生させて、トリガー コールバック処理を検証するには、次のコマンドを実行します。

adb shell cmd profiling_service add-trigger <trigger_type> <com.example.myapp> [--user <user_id>]
adb shell cmd profiling_service trigger <trigger_type> <com.example.myapp> [--user <user_id>]

これらのコマンドで、<trigger_type> は ProfilingTrigger の整数定数値です（たとえば、TRIGGER_TYPE_APP_FULLY_DRAWN の場合は 1、TRIGGER_TYPE_ANR の場合は 2、TRIGGER_TYPE_OOM の場合は 7）。add-trigger を実行すると、0 時間のクールダウンでトリガーが登録され、そのトリガータイプの既存の登録がオーバーライドされます。バックグラウンド トレースのスナップショットを保存するトリガー（1 や 2 など）をシミュレートするには、アクティブなバックグラウンド トレースが必要です（トリガーのテスト用にバックグラウンド トレースを強制有効化するをご覧ください）。

ProfilingManager の全体的な状態を収集する

Android 16（API レベル 36）以降で、最近の Profiling モジュール バージョンを使用している場合は、profiling_service に対して dumpsys を実行して、問題を診断し、ProfilingManager の現在の状態を検査できます。

adb shell dumpsys profiling_service

dumpsys profiling_service 出力は情報提供とデバッグのみを目的としており、その形式は変更される可能性があります。これには、次のようなサービス内部の状態のスナップショットが含まれます。

  • アクティブなスロットルとレートリミッターのステータス。
  • アクティブなデバイス設定。
  • 登録済みのアプリトリガーと、そのレート制限のクールダウン。
  • アクティブなプロファイリング セッションとキューに入れられたプロファイリング セッション。
  • 最近のプロファイリング リクエスト、トリガーの発生、結果配信イベント。