此页面由 Cloud Translation API 翻译。

使用 adb 命令捕获轨迹

您可以使用 adb 命令行在调试 build（即 userdebug 和 eng build）上收集 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 相同，但仅在生成 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 \