本頁面由 Cloud Translation API 翻譯而成。

使用 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：ProtoLog 群組名稱，用於 Android 原始碼。
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 \