コマンドラインでシステム トレースをキャプチャする

systrace コマンドは、デバイス上で実行中のすべてのプロセスのタイミング情報をシステムレベルで収集して検査できる Systrace ツールを呼び出します。

このドキュメントでは、コマンドラインから Systrace レポートを生成する方法について説明します。 Android 9（API レベル 28）以降を搭載しているデバイスの場合は、システム トレース システムアプリを使用して Systrace レポートを生成することもできます。

systrace を実行する手順は次のとおりです。

  1. Android Studio から、最新の Android SDK ツールをダウンロードしてインストールします。
  2. Python をインストールして、ワークステーションの PATH 環境変数に含めます。
  3. android-sdk/platform-tools/ を PATH 環境変数に追加します。このディレクトリには、systrace プログラムによって呼び出される Android Debug Bridge バイナリ（adb）が含まれています。
  4. Android 4.3（API レベル 18）以降を搭載しているデバイスを、USB デバッグ接続経由で開発システムに接続します。

systrace コマンドは、Android SDK Tools パッケージで提供され、android-sdk/platform-tools/systrace/ にあります。

構文

アプリの HTML レポートを生成するには、次の構文を使用してコマンドラインから systrace を実行する必要があります。

python systrace.py [options] [categories]

たとえば、次のコマンドは systrace を呼び出してデバイス アクティビティを記録し、mynewtrace.html という名前の HTML レポートを生成します。このカテゴリリストは、ほとんどのデバイスにおいて、妥当なデフォルト リストになります。

$ python systrace.py -o mynewtrace.html sched freq idle am wm gfx view \
    binder_driver hal dalvik camera input res memory

ヒント: トレース出力内にタスクの名前を表示するには、コマンド パラメータ内に sched カテゴリを含める必要があります。

接続済みのデバイスがサポートするカテゴリのリストを表示するには、次のコマンドを実行します。

$ python systrace.py --list-categories

カテゴリまたはオプションを指定しない場合、systrace は使用可能なすべてのカテゴリを含むレポートを生成し、デフォルト設定を使用します。利用可能なカテゴリは、接続済みのデバイスによって異なります。

グローバル オプション

グローバル オプション 説明
-h | --help ヘルプ メッセージを表示します。
-l | --list-categories 接続済みのデバイスで利用可能なトレース カテゴリをリスト表示します。

コマンドとコマンド オプション

コマンドおよびオプション 説明
-o file 指定されたファイル（file）に HTML トレース レポートを書き込みます。このオプションを指定しない場合、systrace はレポートを systrace.py と同じディレクトリに保存し、trace.html という名前を付けます。
-t N | --time=N デバイス アクティビティを N 秒間トレースします。このオプションを指定しない場合、systrace はコマンドラインから Enter キーを押してトレースを終了するように求めます。
-b N | --buf-size=N N キロバイトのトレース バッファ サイズを使用します。このオプションを使用すると、トレース中に収集されるデータの合計サイズを制限できます。
-k functions
| --ktrace=functions		 カンマ区切りリストで指定した特定のカーネル関数のアクティビティをトレースします。
-a app-name
| --app=app-name		 プロセス名のカンマ区切りリストで指定したアプリのトレースを有効にします。アプリには、Trace クラスのトレース インストゥルメンテーション呼び出しが含まれている必要があります。アプリをプロファイリングするときは、常にこのオプションを指定する必要があります。RecyclerView など、多くのライブラリには、アプリレベルでトレースを有効にしたときに有益な情報を提供するトレース インストゥルメンテーション呼び出しが含まれています。詳細については、カスタム イベントを定義するをご覧ください。

Android 9（API レベル 28）以降を搭載しているデバイス上のすべてのアプリをトレースするには、引用符を含むワイルドカード文字 "*" を渡します。

--from-file=file-path ライブトレースを実行するのではなく、未加工トレースデータを格納した TXT ファイルなどのファイルからインタラクティブ HTML レポートを作成します。
-e device-serial
| --serial=device-serial		 デバイス シリアル番号で識別される特定の接続済みデバイス上でトレースを行います。
categories グラフィックをレンダリングするシステム プロセス用の gfx など、指定したシステム プロセスを対象とするトレース情報を格納します。-l コマンドを使用して systrace を実行すると、接続済みデバイスで利用可能なサービスのリストを表示できます。