ホーム ガイド リファレンス サンプル Downloads

Simpleperf コマンドとオプションのリファレンス

このページでは、最もよく使用される Simpleperf コマンドとオプションについて説明します。 オプションとサブコマンドの完全なリストは、simpleperf --help コマンドを使用して表示できます。

構文

simpleperf [--version] [--help] command [command options]

グローバル オプション

グローバル オプション 説明
--help 使用方法を表示します。
--log severity ロギングの最小限の重要度を設定します。 有効な重要度の値は次のとおりです。
  • verbose
  • debug
  • warning
  • info
  • error
  • fatal
デフォルト値は info です。
--version バージョン情報を表示します。

主要なコマンドとオプション

コマンドとオプション 説明
list [hw|sw|cache|tracepoint] このマシンで使用可能なパフォーマンス イベントをすべてリストします。
record [options] [command [command-args]] 一定期間にプロファイリングされたプロセスのサンプルを記録します。 引数に command を指定すると、Simpleperf は command を実行するプロセスのサンプル情報のみを収集します。 続けて、このサンプリング データを perf.data ファイルに書き込みます。 -a/-p/-t 記録オプションを使用すると、サンプリングのターゲットを変更できます。
  • -a:すべての CPU からのシステム全体のコレクション。
  • -b:実行されたブランチのスタック サンプリングを有効にします。 これは '-j any' オプションを使用することと同じです。 詳細については、このオプションのドキュメントをご覧ください。
  • -c :イベント サンプルの期間を設定します。 これで、count イベントが発生したときに 1 つのサンプルが記録されます。 このオプションは -f/-F オプションと同時には使用できません。 トレースポイント イベントの場合、デフォルトのオプションは -c 1 です。
  • --call-graph fp | dwarf[, dump_stack_size]:コールグラフの記録を有効にします。 コールグラフを表示するための情報収集の方法としては、フレーム ポインタまたは dwarf デバッグ フレームを使用できます。 デフォルト設定は dwarf,65528 です。
  • --cpu cpu_item1,cpu_item2,...:選択した CPU でのみサンプルを収集します。 [cpu_item] には、1 などの CPU 番号、または 0-3 などの CPU 範囲を指定できます。
  • --dump-symbols: perf.data ファイルにシンボルをダンプします。 デフォルトでは、perf.data にはサンプルのシンボル情報は含まれていません。 このオプションは、レポート環境にシンボル情報がない場合に使用されます。
  • --duration time_in_sec:command を実行するのではなく、スレッドを time_in_sec 秒間監視します。 ここで、time_in_sec には任意の正の浮動小数点数を指定できます。
  • -e event1[:modifier1],event2[:modifier2],... : サンプリングするイベントのリストを選択します。 指定可能なすべてのイベント名を確認するには、`simpleperf list` を使用します。 修飾子を追加すると、イベントを監視する方法を定義できます。 指定できる修飾子は次のとおりです。
    • u: ユーザースペースのイベントのみを監視します
    • k: カーネル スペースのイベントのみを監視します
  • -f freq:イベントのサンプリング頻度を設定します。 この場合、1 秒ごとに最大 freq 個のサンプルが記録されます。 トレースポイント以外のイベントの場合、デフォルトのオプションは -f 4000 です。
  • -F freq:「-f freq」と同じです。
  • -g:「--call-graph dwarf」と同じです。
  • --group event1[:modifier],event2[:modifier2], ...:-e オプションと似ていますが、同じ --group オプションで指定されたイベントは 1 つのグループとして監視され、同じスケジュールが適用されます。
  • -j branch_filter1,branch_filter2,...:実行されたブランチのスタック サンプリングを有効にします。 各サンプルには、連続して実行された一連のブランチが取得されます。 次のフィルタを指定できます。
    • any:任意のタイプのブランチ。
    • any_call:任意の関数呼び出しまたはシステム呼び出し。
    • any_ret:任意の関数の戻り値またはシステム呼び出しの戻り値。
    • ind_call:任意の間接ブランチ。
    • u:ブランチ ターゲットがユーザーレベルの場合のみ。
    • k:ブランチ ターゲットがカーネルにある場合のみ。 このオプションでは、少なくとも、any、any_call、any_ret、ind_call のいずれか 1 つのブランチタイプが必要です。
  • -m mmap_pages:カーネルからサンプルデータを受け取るために使用するバッファのサイズを設定します。 これは 2 の累乗にする必要があります。設定していない場合、最大可能値の <=1024 が使用されます。
  • --no-dump-kernel-symbols:カーネル シンボルを perf.data にダンプしません。 デフォルトでは、Simpleperf は、必要な場合にカーネル シンボルをダンプします。
  • --no-inherit:作成された子スレッドまたは子プロセスを記録しません。
  • --no-unwind:デフォルトでは、`--call-graph dwarf` オプションを使用するとユーザーのスタックがアンワインドされます。 このオプションを使用すると、ユーザーのスタックのアンワインドが無効になります。
  • -o record_file_name:記録ファイル名を設定します。デフォルト名は perf.data です。
  • -p pid1,pid2,...:既存のプロセスでイベントを記録します。 -a とは相互に排他的です。
  • --post-unwind:デフォルトでは、`--call-graph dwarf` オプションを使用すると、記録中にユーザーのスタックがアンワインドされます。 この場合、スタックのアンワインドに時間がかかり、記録が失われることがあります。 このオプションを使用すると、記録後にユーザーのスタックをアンワインドできます。
  • --start_profiling_fd fd_no:プロファイリングの開始後に、fd_no に「STARTED」と書き込んで、fd_no を閉じます。
  • --symfs dir:このディレクトリに対して相対的な、シンボルを含むファイルを探します。 このオプションを使用して、--dump-symbols と -g により使用される、シンボル表とデバッグ情報を含むファイルを指定します。
  • -t tid1,tid2,...:既存のスレッドでのイベントを記録します。 -a とは相互に排他的です。
report [options] simpleperf record で作成した perf.data ファイルを読み取り、何に時間がかかっているのかを示す報告を表示します。
  • -b:命令アドレスではなく、サンプリングされた実行ブランチのブランチ先アドレスを使用します。 -b/-j オプションで記録された perf.data に対してのみ有効です。
  • --brief-callgraph:コールグラフの概略を出力します。
  • --children:コールチェーンに出現することで累積されたオーバーヘッドを出力します。
  • --comms comm1,comm2,...:選択したコマンドについてのみ報告します。
  • --dsos dso1,dso2,...:選択した動的共有オブジェクトについてのみ報告します。
  • -g [callee|caller]:コールグラフを出力します。 callee モードが使用されている場合、グラフはその関数がどのように他の関数から呼び出されるかを示します。 そうでない場合、グラフはその関数がどのように他の関数を呼び出すかを示します。 デフォルトのモードは caller です。
  • -i file:記録ファイルのパスを指定します。デフォルトのパスは perf.data です。
  • --kallsyms file:カーネル シンボルを読み取るファイルを設定します。
  • --max-stack frames:コールグラフを出力するときに表示される最大スタック フレーム数を設定します。
  • -n:各アイテムのサンプル数を出力します。
  • --no-demangle:シンボル名をデマングルしません。
  • --no-show-ip:不明シンボルについてファイルに vaddr を表示しません。
  • -o report_file_name:レポート ファイル名を設定します。デフォルトのファイル名は stdout です。
  • --percent-limit percent:コールグラフの出力時に表示する最小のパーセンテージを設定します。
  • --pids pid1,pid2,...:選択したプロセス ID についてのみ報告します。
  • --raw-period:期間のパーセンテージではなく期間の数を報告します。
  • --sort key1,key2,...:レポートをソートし、出力するためのキーを選択します。 キーを指定する順序によって、レポートのソートと出力に使用されるキーの順序が決まります。 指定できるキーは次のとおりです。
    • pid:プロセス ID。
    • tid:スレッド ID。
    • comm:スレッド名（スレッドの存続期間中は変更できます）。
    • dso:共有ライブラリ。
    • symbol:共有ライブラリ内の関数名。
    • vaddr_in_file:共有ライブラリ内の仮想アドレス。

    -b オプションでのみ使用できるキー。

    • dso_from:ブランチ元の共有ライブラリ。
    • dso_to:ブランチ先の共有ライブラリ。
    • symbol_from:ブランチ元の関数名。
    • symbol_to:ブランチ先の関数名。

    デフォルトのソートキーは comm、pid、tid、dso、symbol です。

  • --symbols symbol1;symbol2;...:選択されたシンボルについてのみ報告します。
  • --symfs dir:このディレクトリに対して相対的な、シンボルを含むファイルを探します。
  • --tids tid1,tid2,...:選択されたスレッド ID についてのみ報告します。
  • --vmlinux file:file からのカーネル シンボルを解析します。
stat [options] [command [command-args]] 一定の期間内にプロファイリングされたプロセスで発生したイベント数の概要を取得します。 引数に command を指定すると、Simpleperf では を実行するプロセスについてのみ、パフォーマンス カウンタ情報を収集します。 -a/-p/-t オプションを使用すると、カウンタ情報収集のターゲットを変更できます。
  • -a:システム全体の情報を収集します。
  • --cpu cpu_item1,cpu_item2,...:選択された CPU でのみ情報を収集します。 cpu_item には、1 などの CPU 番号、または 0-3 などの CPU 範囲を指定できます。
  • --csv:コンマ区切り形式でレポートを作成します。
  • --duration time_in_sec:command を実行するのではなく、time_in_sec 秒間監視します。 ここで、time_in_sec には任意の正の浮動小数点数を指定できます。
  • --interval time_in_ms:time_in_ms ミリ秒ごとに統計を出力します。 ここで、time_in_ms には任意の正の浮動小数点数を指定できます。
  • -e event1[:modifier1],event2[:modifier2],... :カウントするイベントリストを選択します。 指定可能なすべてのイベント名を確認するには、simpleperf list を使用します。 修飾子を追加すると、イベントの監視方法を定義できます。 指定できる修飾子は次のとおりです。
    • u:ユーザー スペースのイベントのみを監視します。
    • k:カーネル スペースのイベントのみを監視します。
  • --group event1[:modifier],event2[:modifier2] ,...:-e オプションと同様です。 同じ --group オプションで指定されたイベントは 1 つのグループとして監視され、同じスケジュールが適用されます。
  • --no-inherit:作成された子スレッドおよび子プロセスの統計を取得しません。
  • -o output_filename:標準出力ではなく、output_filename にレポートを作成します。
  • -p pid1,pid2,...:既存のプロセスでのイベントの統計を取ります。 -a とは相互に排他的です。
  • -t tid1,tid2,...:既存のスレッドでのイベントの統計を取ります。 -a とは相互に排他的です。
  • --verbose:結果を詳細モードで表示します。

Python スクリプト

Simpleperf ツールでは、ndk-location/simpleperf/ ディレクトリにいくつかの Python スクリプトが含まれています。これらを利用して、Android 端末でパフォーマンス データを簡単に記録および報告できます。 これらのスクリプトは、ターゲットの Android 端末に接続されているホスト開発マシンで実行します。 これらのスクリプトの使用例については、GitHub の Simpleperf デモのサンプルをご覧ください。

スクリプト 説明
annotate.py perf.data のプロファイリング データに基づき、ソースファイルに注釈を付けます。 このスクリプトの動作は、annotate.config ファイルで設定できます。
app_profiler.py Android アプリをプロファイリングします。 プロファイリング環境を準備し、Simpleperf 実行可能ファイルを Android 端末にプッシュし、その端末で perf.data ファイルを生成してから、生成済みファイルをホストに戻します。 このスクリプトの動作は、app_profiler.config ファイルで設定できます。
binary_cache_builder.py Android 端末からライブラリを取得します。 このスクリプトは app_profiler.py によって使用されます。
pprof_proto_generator.py プロファイリング データを pprof で使用される形式に変換します。
report.py グラフィック ユーザー インターフェースを起動して、プロファイリング結果を報告します。
report_sample.py flamegraph 出力を生成します。
simpleperf_report_lib.py プロファイリング データを解析する Python インターフェースを提供します。 このスクリプトを使用して、perf.data のプロファイリング データを他の形式に変換できます。 Simpleperf で提供される report_sample.py で、変換方法の例が示されます。