自 2025 年 3 月 27 日起，我们建议您使用 android-latest-release 而非 aosp-main 构建 AOSP 并为其做出贡献。如需了解详情，请参阅 AOSP 的变更。

使用 adb 命令捕获跟踪记录

在调试 build（即 userdebug 和 eng build）上，可以使用 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 (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 相同，但仅在提交 bug 报告时触发层级快照生成，而不是在每次刷出跟踪记录时触发。

跟踪标志 (trace_flags)：

TRACE_FLAG_INPUT：如果 Surface 包含输入数据，则跟踪输入窗口的具体信息。
TRACE_FLAG_COMPOSITION：跟踪组合类型和可见区域。
TRACE_FLAG_EXTRA：跟踪其他 surface 元数据，包括屏幕外的层。

警告：此字段非常冗长，需要大量内存。
TRACE_FLAG_HWC：跟踪其他非结构化硬件编辑器元数据。

警告：此字段非常冗长，需要大量内存。
TRACE_FLAG_BUFFERS：将 SurfaceFlinger 配置为跟踪 Surface 上的所有缓冲区更改。默认情况下，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。

Shell 过渡

对于此跟踪类型，请使用数据源名称 com.android.wm.shell.transition。

配置选项

此跟踪类型没有任何配置选项。

示例

以下是 adb 的 shell 转换跟踪类型示例：

$ 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

IME

对于此跟踪类型，请使用数据源名称 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

Shell 过渡

以下命令用于转换跟踪：

在 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

以下命令用于输入法 (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 \