使用 ADB 指令擷取追蹤記錄

您可以在偵錯版本 (即 userdebug 和 eng 版本) 上，使用 adb 指令列收集 Winscope 追蹤記錄。使用 adb 收集 Winscope 追蹤記錄前，請先執行 adb root。

從 Android 15 開始，Winscope 追蹤記錄會整合至 Perfetto，並使用 Perfetto 指令列收集。每個 Winscope 追蹤記錄都是 Perfetto 資料來源，並有自己的設定。您可以個別啟用設定，也可以在單一追蹤工作階段中啟用。

在 Android 14 以下版本中，每個 Winscope 追蹤記錄都有不同的指令，您可以分別收集。詳情請參閱「在 Android 14 以下版本中擷取追蹤記錄」。

WindowManager

請為這個追蹤類型使用資料來源名稱 android.windowmanager。

設定選項

  • 記錄層級 (log_level)：指定記錄詳細程度。支援的值：

    • LOG_LEVEL_VERBOSE：記錄所有元素，並提供最多資訊。
    • LOG_LEVEL_DEBUG：記錄所有元素，但不寫入所有設定資料。
    • LOG_LEVEL_CRITICAL：只記錄可見元素，且效能負擔極小。

  • 記錄頻率 (log_frequency)：定義記錄項目的頻率：

    • LOG_FREQUENCY_FRAME：在影格提交時追蹤狀態快照。
    • LOG_FREQUENCY_TRANSACTION：每次提交交易時，都會追蹤狀態快照。
    • LOG_FREQUENCY_SINGLE_DUMP：在資料來源啟動時追蹤單一狀態快照。

如要進一步瞭解設定值，請參閱 WindowManager。

範例

以下是 adb 的 WindowManager 追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

請為這個追蹤類型使用資料來源名稱 android.protolog。

設定選項

追蹤模式 (tracing_mode)：決定要使用的記錄設定：

  • DEFAULT：只追蹤 group_overrides 中指定的記錄群組和層級。
  • ENABLE_ALL：追蹤所有記錄群組和層級，除非在 group_overrides 中指定。

最低記錄層級 (default_log_from_level)：如果設定這個層級，系統會追蹤記錄層級高於或等於這個層級的任何訊息，除非指定群組覆寫。舉例來說，這項功能可用於啟用所有警告和錯誤的記錄，不必啟用所有記錄。支援的值如下：

  • PROTOLOG_LEVEL_DEBUG
  • PROTOLOG_LEVEL_VERBOSE
  • PROTOLOG_LEVEL_INFO
  • PROTOLOG_LEVEL_WARN
  • PROTOLOG_LEVEL_ERROR
  • PROTOLOG_LEVEL_WTF

群組覆寫 (group_overrides)：針對每個 ProtoLog 群組手動設定記錄層級。每個群組包含：

  • name：Android 原始碼中使用的 ProtoLog 群組名稱。
  • log_from：與 default_log_from_level 相同，但僅適用於目前群組。

  • collect_stacktrace：設為 true 時，會收集所追蹤群組中每則 ProtoLog 訊息的堆疊追蹤記錄。

範例

以下是 adb 的 ProtoLog 追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: DEFAULT
              default_log_from_level: PROTOLOG_LEVEL_WARN
              group_overrides: {
                 group_name: "WM_SHELL_STARTING_WINDOW"
                 log_from: PROTOLOG_LEVEL_DEBUG
                 collect_stacktrace: true
              }
           }
       }
   }
EOF

輸入

請為這個追蹤類型使用資料來源名稱 android.input.inputevent。

設定選項

追蹤模式 (trace_mode)：決定是否應使用隱私權保護規則啟動輸入追蹤記錄，或記錄所有輸入事件：

  • TRACE_MODE_TRACE_ALL：記錄系統處理的所有輸入事件，無論處理事件的環境為何。
  • TRACE_MODE_USE_RULES：使用這個設定中定義的追蹤規則，指定要追蹤的事件。如要進一步瞭解如何指定追蹤記錄的規則，請參閱 android_input_event_config.proto。

範例

以下是 adb 的輸入追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
EOF

SurfaceFlinger (圖層)

請為這個追蹤類型使用資料來源名稱 android.surfaceflinger.layers。

設定選項

追蹤模式 (mode)：定義記錄項目的頻率：

  • MODE_ACTIVE：追蹤圖層快照。每次發生圖層變更時，系統都會擷取快照。
  • MODE_GENERATED：從 SurfaceFlinger 內部環形緩衝區保留的交易產生圖層快照。系統會在排清這個資料來源時，產生圖層的快照。
  • MODE_DUMP：追蹤單一層的快照。
  • MODE_GENERATED_BUGREPORT_ONLY：與 MODE_GENERATED 相同，但只會在擷取錯誤報告時觸發圖層快照產生作業，不會在清除追蹤記錄時觸發。

追蹤標記 (trace_flags)：

  • TRACE_FLAG_INPUT：如果介面包含輸入資料，則會追蹤輸入視窗的詳細資料。
  • TRACE_FLAG_COMPOSITION：追蹤組合類型和可見區域。

  • TRACE_FLAG_EXTRA：追蹤其他表面中繼資料，包括螢幕外圖層。

  • TRACE_FLAG_HWC：追蹤其他非結構化硬體合成器中繼資料。

  • TRACE_FLAG_BUFFERS：設定 SurfaceFlinger，追蹤介面上所有緩衝區的變更。根據預設，只有在幾何變化發生時，SurfaceFlinger 才會追蹤新狀態。

  • TRACE_FLAG_VIRTUAL_DISPLAYS：在追蹤記錄中加入虛擬螢幕層。

範例

以下是 adb 的 SurfaceFlinger 追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   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
           }
       }
   }
EOF

如要進一步瞭解不同設定值的意義，請參閱「SurfaceFlinger」。

殼層轉場

使用這個追蹤類型適用的資料來源名稱 com.android.wm.shell.transition。

設定選項

這個追蹤類型沒有任何設定選項。

範例

以下是 adb 的殼層轉場效果追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
EOF

SurfaceFlinger (交易)

請使用這個追蹤類型適用的資料來源名稱 android.surfaceflinger.transactions。

設定選項

追蹤模式 (mode)：定義記錄項目的頻率：

  • MODE_CONTINUOUS：每次資料來源排清時，SurfaceFlinger 都會寫入內部交易環形緩衝區。環形緩衝區包含 SurfaceFlinger 的初始狀態和最新交易。

  • MODE_ACTIVE：SurfaceFlinger 會寫入初始狀態，然後寫入每個傳入的交易，直到資料來源停止為止。

範例

以下是 adb 的 SurfaceFlinger 交易追蹤類型範例。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

輸入法編輯器

使用資料來源名稱：android.inputmethod，適用於這個追蹤類型。

設定選項

這個追蹤類型沒有任何設定選項。

範例

以下是 adb 的 IME 追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
EOF

ViewCapture

請為這個追蹤類型使用資料來源名稱 android.viewcapture。

設定選項

這個追蹤類型沒有任何設定選項。

範例

以下是 adb 的 ViewCapture 追蹤類型範例：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

完整範例

您可以使用 Perfetto，透過單一設定從多個來源收集資料。 您可以使用單一指令收集所有 Winscope 追蹤記錄：

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: ENABLE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
   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
           }
       }
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

在 Android 14 以下版本中擷取追蹤記錄

請先執行 adb root，再針對下列每個追蹤記錄執行 adb shell 指令。追蹤完成後，追蹤檔會顯示在 /data/misc/wmtrace 中。如要從裝置複製檔案或目錄及其子目錄，請參閱「將檔案複製到裝置/從裝置複製檔案」。

WindowManager 追蹤記錄

如要擷取 WindowManager 追蹤記錄，請按照下列步驟操作：

  • 啟用追蹤：

    adb shell wm tracing start

  • 停用追蹤：

    adb shell wm tracing stop

  • 在執行追蹤記錄擷取作業時，將記錄資料儲存至檔案：

    adb shell wm tracing save-for-bugreport

  • 每個影格記錄一次追蹤記錄：

    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

WindowManager 傾印

如要擷取 WindowManager 傾印，請按照下列步驟操作：

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

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

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 傾印：

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

殼層轉場

下列指令用於追蹤轉場效果。

在 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 主動追蹤的 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 \