使用 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。

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 写入初始状态，然后写入每个传入事务，直到数据源停止。

示例

以下是 SurfaceFlinger 事务跟踪类型的 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.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

使用数据源名称：android.inputmethod 作为此跟踪类型。

配置选项

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

示例

以下是 IME 跟踪类型的 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.inputmethod"
       }
   }
EOF

ViewCapture

使用数据源名称 android.viewcapture 作为此跟踪类型。

配置选项

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

示例

以下是 ViewCapture 跟踪类型的 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.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 shell 命令之前，请运行 adb root。在跟踪结束时，跟踪文件位于 /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 \