Winscope を使用してウィンドウ遷移をトレースする

Winscope は、アニメーションや遷移の最中および終了後における複数のシステムサービスの状態を記録、リプレイ、分析できるウェブツールです。Winscope は、すべての関連するシステムサービスの状態をトレースファイルに記録します。トレースファイルと Winscope UI を使用すると、遷移をリプレイ、ステップ実行、デバッグすることで、画面録画の有無にかかわらず、各アニメーションフレーム向けのこうしたサービスの状態を調べることができます。

Winscope に読み込み可能なトレースを生成できるシステムサービスは次のとおりです。

SurfaceFlinger
WindowManager
WMShell
IME
ランチャー

Winscope トレースビューアを実行する

Winscope トレースは、このプラットフォーム上のサービスの一部です。このセクションでは、Winscope トレースビューアをダウンロード、ビルド、実行するために必要な手順について概説します。

Winscope トレーサーを実行するために PC をセットアップする手順は次のとおりです。

Android ソースをダウンロードします。
次の Winscope フォルダに移動します。
```
cd development/tools/winscope
```
以下を使用して依存関係をインストールします。
```
npm install
```
使用可能なコマンドのリストを表示するには、次のコマンドを実行します: npm run
以下を使用して、すべての本番環境およびテストターゲットをビルドします。
```
npm run build:prod
```
次を使用して Winscope を実行します。
```
npm run start
```

トレースをキャプチャする

デバイス上でのトレースのキャプチャには、Winscope または Android Debug Bridge（adb）コマンドが使用できます。

デバイス上でトレースをキャプチャする

アニメーションの問題に関するバグの報告時にデータを収集するため、デバイス上でトレースをキャプチャします。構成をカスタマイズできないため、このメソッドではすべての UI トレースが記録されます。

Android デバイスの場合:

開発者向けオプションを有効にします。
[開発者向けオプション] の [システムトレース] を選択します。
[Winscope トレースの収集] を有効にします。
[その他] で以下を実行します。
1. [バグレポートに記録を添付する] を有効にします。
2. [[クイック設定] タイルの表示] をオンにします。
バグの再現が必要な場所に移動します。
キャプチャを開始するには、クイック設定を開き、[トレースを記録] を選択します。

図 1. [トレースを記録] を含むクイック設定メニュー。
バグを再現するために必要な手順のみを実行します。
キャプチャを停止するには、クイック設定を開き、[トレースを停止] を選択します。
Gmail、ドライブ、BetterBug など、表示されたオプションのいずれかを使用して、キャプチャしたログを共有します。

Winscope でトレースをキャプチャする

Winscope を使用して、ローカルでの開発やデバッグのためにトレースをキャプチャすることができます。Winscope は、USB または Wi-Fi 経由のデバイス接続をサポートする adb を使用します。

Winscope の場合:

[トレースの収集] 画面で、[ADB プロキシ] をクリックします。

図 2. Winscope でトレースをキャプチャします。
Winscope ADB Connect プロキシを起動して、ブラウザから直接トレースをキャプチャします。

注: Python 3.5 以上と ADB が必要です。

次のコマンドを実行します。

python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py

キャプチャを開始するには、[トレースの収集] 画面でターゲットと構成を選択し、[トレースを開始] をクリックします。

図 3. Winscope でトレースを収集します。
キャプチャを停止するには、[トレースを終了] をクリックします。

図 4. Winscope でトレースを終了します。

ツールが Winscope の UI にトレースをアップロードすると、[取得しています] および [proto ファイルを解析しています] というメッセージが画面に表示されます。

Winscope を使用して状態ダンプを生成する

Winscope を使用して状態ダンプを取得するには、[トレースの収集] 画面で [ダンプ] タブを選択し、[状態をダンプ] をクリックします。

dump-winscope

図 5. Winscope で状態をダンプします。

adb コマンドでトレースをキャプチャする

次の各トレースの adb shell コマンドを実行する前に、adb root を実行します。トレースの終了時、トレースファイルは /data/misc/wmtrace にあります。デバイスからファイルやディレクトリ（およびそのサブディレクトリ）をコピーするには、「デバイスにファイルをコピーする、デバイスからファイルをコピーする」をご確認ください。詳しくは、adb をご覧ください。

WindowManager のトレース

WindowManager のトレースをキャプチャするには、以下の手順を行います。

トレースを有効にします。
```
adb shell wm tracing start
```
トレースを無効にします。
```
adb shell wm tracing stop
```
トレースキャプチャの実行中にロギングデータをファイルに保存します。
```
adb shell wm tracing save-for-bugreport
```
1 フレームごとにトレースのログを記録します。
```
adb shell wm tracing frame
```
各トランザクションのログを記録します。
```
adb shell wm tracing transaction
```
最大ログサイズを KB 単位で設定します。
```
adb shell wm tracing size
```
トレースステータスを表示します。
```
adb shell wm tracing status
```
ログレベルを critical（可視ウィンドウのみ、情報を簡略化）、trim（すべてのウィンドウ、情報を簡略化）、または all（すべてのウィンドウと情報）に設定します。
```
adb shell wm tracing level
```

ProtoLog

ProtoLog システムでは次のコマンドが使用されます。

system_server プロセス内:

ProtoLog を開始します。
```
adb shell cmd window logging start
```
ProtoLog を停止します。
```
adb shell cmd window logging stop
```
指定されたロググループに対して ProtoLog を有効にします。
```
adb shell cmd window logging enable [group...]
```
指定されたロググループに対して ProtoLog を無効にします。
```
adb shell cmd window logging disable [group...]
```
指定されたロググループに対して Logcat ログを有効にします。
```
adb shell cmd window logging enable-text [group...]
```
指定されたロググループに対して Logcat ログを無効にします。
```
adb shell cmd window logging disable-text [group...]
```

WMShell 内:

ProtoLog を開始します。

adb shell dumpsys activity service SystemUIService WMShell

遷移トレース

遷移トレースでは次のコマンドが使用されます。

system_server プロセス内:

トレースを開始します。

adb shell cmd window shell tracing start

トレースを停止します。

adb shell cmd window shell tracing stop

WMShell でトレースを開始します。

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

WMShell でトレースを停止します。

adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

インプットメソッドエディタ

インプットメソッドエディタ（IME）のトレースでは次のコマンドが使用されます。

インプットメソッド（IM）クライアント、インプットメソッドサービス（IMS）、およびインプットメソッドマネジメントサービス（IMMS）の IME トレースを開始します。
```
adb shell ime tracing start
```
IME クライアント、IMS、および IMMS のトレースを開始します。
```
adb shell ime tracing stop
```

SurfaceFlinger レイヤ

SurfaceFlinger レイヤのトレースには、キャプチャに Perfetto トレースを使用します。設定情報については、トレース構成を参照してください。

SurfaceFlinger レイヤのトレースの構成例を次に示します。

unique_session_name: "surfaceflinger_layers_active"
buffers: {
    size_kb: 63488
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.layers"
        surfaceflinger_layers_config: {
            mode: MODE_ACTIVE
            trace_flags: TRACE_FLAG_INPUT
            trace_flags: TRACE_FLAG_COMPOSITION
            trace_flags: TRACE_FLAG_HWC
            trace_flags: TRACE_FLAG_BUFFERS
            trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
        }
    }
}

SurfaceFlinger レイヤのトレースを生成するためのコマンド例を次に示します。

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

SurfaceFlinger トランザクション

SurfaceFlinger トランザクションのトレースには、キャプチャに Perfetto トレースを使用します。設定情報については、トレース構成を参照してください。

SurfaceFlinger のアクティブなトレースの Perfetto 構成例を次に示します。

unique_session_name: "surfaceflinger_transactions_active"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_ACTIVE
        }
    }
}
write_into_file: true
file_write_period_ms: 100

SurfaceFlinger の継続的なトレースの Perfetto 構成例を次に示します。

unique_session_name: "surfaceflinger_transactions_continuous"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_CONTINUOUS
        }
    }
}

SurfaceFlinger トランザクションのトレースを生成するためのコマンド例を次に示します。

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

adb を使用して状態ダンプを生成する

Winscope は、バグレポートから WindowManager と SurfaceFlinger の状態のスナップショットを読み取ります。バグレポートでは、状態を別々の proto ファイルとして proto フォルダに保存します。adb を使用して状態ダンプを生成するには、次のコマンドを実行します。

WindowManager の場合:

adb exec-out dumpsys window --proto > window_dump.winscope

SurfaceFlinger の場合:

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

トレースを分析する

アニメーションの問題を引き起こす一時的かつ無効な状態をデバッグするために、Winscope はさまざまなトレースファイルを集約し、フレームとタイムラインに対する検索および可視化機能を提供し、protobuf メッセージを一貫した方法で提示します。Winscope でトレースを分析すると、バグが発生した正確なレイヤ、フレーム、状態を特定するのに役立ちます。

Winscope を使用する

トレースのキャプチャが完了したら、Winscope でトレースを分析します。

右側のパネルを使用して、保存したトレースをアップロードします。アップロードしたトレースを削除したり、さらにトレースをアップロードしたりできます。

注: サポートされているトレースファイルの種類は、Winscope トレース、Winscope メタデータ（adb で収集）を含む MP4 ビデオ、zip ファイル、およびバグレポートです。

図 6. Winscope でトレースをアップロードします。
アップロードされたトレースを可視化するには、[トレースを表示] をクリックします。各トレースのタブがウィンドウの上部パネルに表示されます。アップロードされたファイルに関連するトレースが含まれている場合、画面録画トレースのフローティングビューが画面にオーバーレイされます。

図 7. Winscope でトレースを表示します。

ウィンドウの最上部パネルにある UI を使用して、アップロードしたトレースの名前を変更してダウンロードしたり、新しいトレースをアップロードしたりします。
ウィンドウの下部パネルにあるタイムスライダーツールを使用し、時間軸に沿ってトレースを移動します。その他の時間軸移動については、次の機能を使用します（図 8 を参照）。
- 特定の時間や事象に移動するには、カーソル（タイムスライダー）、時間表示ボックス（左下隅）の左矢印と右矢印、またはキーボードの左矢印と右矢印を使用します。
- 選択した色分けされたトレースをタイムラインに表示するには、プルダウンメニュー（タイムスライダーの左側）を使用します。デフォルトでは、トレースタブを使用して表示された最後の 3 つのトレースがタイムラインに表示されます。
- アップロードされたすべてのトレースを詳細に表示するには、（タイムスライダー下の）ズームインやズームアウトのツールを使用するか、キーボード上でスクロールします。リセットボタンを使用してズームレベルをリセットします。
- トレースの分布の推移を拡大表示するには、上矢印（右下隅）をクリックします。
図 8. Winscope での時間軸移動。

拡大表示（図 9）では、特定の時間枠を選択して拡大し、より詳しく調べることができます。

図 9. Winscope で拡大されたタイムライン。
トレースを調べるため、画面録画でデバイスの状態を表示できます。特定のトレースを調べるには、ツールの上部パネルにある、対象のトレースのタブをクリックします。
- 「Surface Flinger」トレースの場合、特定の期間におけるトレースの異なるビューが 3 つのパネルに表示されます（図 10 を参照）。
  
  図 10. Winscope 上の Surface Flinger トレース。
  - 「レイヤ」ビュー: 長方形のオーバーレイでレイヤを 3D 表示します。次の UI 要素は、位置、サイズ、変換、Z オーダーに基づいてグラフィカル要素をレンダリングするために長方形を調整します。
    - [回転] スライダー（レイヤビューの左上）を使用すると、レイヤ化された長方形を回転して、指定した角度で表示できます。
    - [間隔] スライダー（レイヤビューの右上）は、レイヤ間の間隔を調整して、選択した複合ビューを作成します。
    - ズームツール（レイヤビューの右上）を使用すると、レイヤを拡大、縮小して、より詳しく調べることができます。
    - リセットボタン（レイヤビューの右上）は、カメラ設定を元のビューに戻します。
    - 長方形をドラッグすると、ズームしやすくなります。
    注: [可視のみ] と [仮想を表示する] のチェックボックスはサポートが終了しています。
  - 「階層」ビュー: レイヤの完全な階層。
    - [可視のみ]（階層ビューの右上）を選択すると、階層から不可視のレイヤを非表示にし、画面上の要素を可視化するのに役立ちます。
    - [フラット]（階層ビューの右上）を選択すると、階層がフラット化されたレイヤのリストとして表示されます。
    - 状態遷移がある場合にのみ、[差異を表示]（階層ビューの左上）が選択されます。選択すると、ツールは現在の状態と以前の状態を比較します。新しい要素は緑色で、削除された要素は赤色で、変更された要素は青色でハイライト表示されます。
  - 「プロパティ」ビュー: 選択したレイヤのプロパティ。「プロパティ」ビューの上部パネルには、「可視性」、「ジオメトリ」、「バッファ」などの主要なプロパティに関する情報のみが表示されます。「プロパティ」ビューの下部パネルには、すべてのプロパティの「Proto Dump」が表示されます。
    - [差異を表示] のチェックボックス（プロパティビューの左上）は、「階層」ビューと同じように動作します。
    - [デフォルトを表示]（プロパティビューの左上）を選択すると、Proto Dump にデフォルトの proto 値が表示されます。デフォルトでは、これらの値は Proto Dump にリストされていません。デフォルトの proto 値は、proto フィールド定義から取得されます。proto フィールドに nonnull のデフォルト値が設定されていない場合、表示されるデフォルトの proto 値は次のとおりです:
      - 文字列: Null
      - 数字: 0
      - ブール値: 誤
      - オブジェクト: Null
  3 つのビューからの選択と画面録画は同期されます。つまり、別の時点に移動すると、すべてのトレースが同期的に更新されます。レイヤのプロパティを表示するには、階層ビューでレイヤをクリックするか、プロパティビューでそれぞれの長方形をクリックして、レイヤを選択します。紫色の長方形は、このレイヤにビュートレースがアタッチされていることを示します。紫色のレイヤをダブルクリックすると、UI は関連するビュートレースタブに切り替わります。
- 「Window Manager」トレースの場合、特定の期間におけるトレースの異なるビューが 3 つのパネルに表示されます（図 11 を参照）。
  - 「ウィンドウ」ビュー: レイヤの 3D ビュー。
  - 「階層」ビュー: レイヤの完全な階層。
  - 「プロパティ」ビューには、すべてのプロパティの「Proto Dump」が表示されます。
  3 つのビューからの選択と画面録画は同期されます。つまり、別の時点に移動すると、すべてのトレースが同期的に更新されます。
  
  注: 3 つのビューにある UI 要素の機能と配置は、Surface Flinger トレースのものに類似しています。
  
  図 11. Winscope 上の Window Manager トレース。
- 「トランザクション」トレースの場合、Surface Flinger と Window Manager の間のトランザクションは表形式で示されます。これは、表示された ID、タイプ、テキストで検索することができ、プロパティビューには proto ダンプが表示されます。2 つのビューからの選択と画面録画は同期されます。
  
  図 12. Winscope 上のトランザクショントレース。
- 「ProtoLog」トレースの場合、情報は表形式で表示され、タグ、ソースファイル、テキストで検索できます。
  
  図 13. Winscope 上の ProtoLog トレース。
- 「遷移」トレースの場合、選択した遷移のプロパティとともに、ID、タイプ、送信日時、期間、ステータスを含む遷移のリストが表示されます。
  
  図 14. Winscope 上の遷移トレース。