使用 Winscope 跟踪窗口转换

Winscope 是一款 Web 工具,可以让用户在动画和转换期间和之后记录、重放和分析多个系统服务的状态。Winscope 将所有相关的系统服务状态记录在一个跟踪文件中。使用带有跟踪文件的 Winscope 界面,您可以通过重放、单步执行和调试转换来针对每个动画帧检查这些服务的状态(无论是否有屏幕录制)。

生成可加载到 Winscope 中的跟踪记录的系统服务包括:

  • SurfaceFlinger
  • WindowManager
  • WMShell
  • IME
  • 启动器

运行 Winscope 跟踪记录查看器

Winscope 跟踪是该平台上服务的一部分。本部分概述了下载、构建并运行 Winscope 跟踪记录查看器所需的步骤。

请按照以下步骤设置您的 PC,以便运行 Winscope 跟踪器:

  1. 下载 Android 源代码
  2. 导航到 Winscope 文件夹:

    cd development/tools/winscope
    
  3. 使用以下命令安装依赖项:

    npm install
    

    如需查看可用命令的列表,请运行以下命令: npm run

  4. 使用以下命令构建所有生产和测试目标:

    npm run build:prod
    
  5. 使用以下命令运行 Winscope:

    npm run start
    

捕获跟踪记录

您可以通过 WinscopeAndroid 调试桥 (adb) 命令在设备上捕获跟踪记录。

在设备上捕获跟踪记录

在针对动画问题提交错误时,在设备上捕获跟踪记录以收集数据。所有界面跟踪记录都是通过此方法记录的,因为无法自定义配置。

在 Android 设备上:

  1. 启用开发者选项
  2. 选择开发者选项下的 System Tracing
  3. 启用收集 Winscope 跟踪记录
  4. 其他下:
    1. 启用在错误报告中附加录制内容
    2. 启用显示“快捷设置”功能块
  5. 导航到您需要重现错误的位置。
  6. 如需开始记录,请打开“快捷设置”,然后选择录制跟踪记录

    quick_setting_winscope

    图 1. 包含“录制跟踪记录”的“快捷设置”菜单。

  7. 仅执行重现错误所需的步骤。

  8. 如需停止捕获,请打开“快捷设置”,然后选择停止跟踪

  9. 使用所列选项之一共享捕获的日志,如 Gmail、云端硬盘或 BetterBug。

通过 Winscope 捕获跟踪记录

您可以使用 Winscope 捕获跟踪记录以进行本地开发和调试。Winscope 使用 adb,它支持通过 USB 或 Wi-Fi 连接设备。

在 Winscope 上:

  1. Collect Traces(收集跟踪记录)界面上,点击 ADB Proxy(ADB 代理):

    capture_traces_winscope

    图 2. 在 Winscope 上捕获跟踪记录。

  2. 启动 Winscope ADB Connect 代理,以直接从浏览器中捕获跟踪记录。

  3. 运行以下命令:

    python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py
    
  4. 如需开始捕获,请在 Collect Traces(收集跟踪记录)界面上选择目标和配置,然后点击 Start trace(开始跟踪):

    collect_traces_winscope

    图 3. 在 Winscope 上收集跟踪记录。

  5. 如需停止捕获,请点击 End trace(结束跟踪记录):

    end_trace_winscope

    图 4. 在 Winscope 上结束跟踪。

当该工具在 Winscope 界面上上传跟踪记录时,屏幕上会显示“Fetching”(正在提取)和“Parsing Proto Files”(正在解析 Proto 文件)消息。

使用 Winscope 生成状态转储文件

如需使用 Winscope 进行状态转储,请在 Collect Traces(收集跟踪记录)屏幕上选择 Dump(转储)标签页,然后点击 Dump state(转储状态):

dump-winscope

图 5. 在 Winscope 上转储状态。

通过 adb 命令捕获跟踪记录

请先运行 adb root,然后再针对以下每条跟踪记录运行 adb shell 命令。跟踪结束后,跟踪文件会显示在 /data/misc/wmtrace 中。如需从一个文件中复制某个文件或目录(及其子目录),请参阅将文件复制到设备或从设备复制文件。如需了解详情,请参阅 adb

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
    

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
    

转换跟踪

以下命令用于转换跟踪:

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 层跟踪配置的示例:

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 事务跟踪使用 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 \

使用 adb 生成状态转储

WinScope 可以从错误报告中读取 WindowManager 状态和 SurfaceFlinger 状态的快照。错误报告会将状态信息以单独的 proto 文件的形式存储在 proto 文件夹中。要使用 adb 生成状态转储文件,请运行以下命令。

对于 WindowManager:

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

对于 SurfaceFlinger:

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

分析跟踪记录

为了调试导致动画问题的瞬态和无效状态,Winscope 会汇总不同的跟踪文件,提供对帧和时间轴的搜索和可视化功能,并以连贯的方式呈现 protobuf 消息。分析 Winscope 中的跟踪记录有助于确定错误出现时的确切层、帧和状态。

使用 Winscope

捕获跟踪记录后,可在 Winscope 上分析跟踪记录:

  1. 使用右侧面板上传已保存的跟踪记录。您可以移除已上传的跟踪记录或上传更多跟踪记录。

    upload_traces_winscope

    图 6. 在 Winscope 上上传跟踪记录。

  2. 点击 View traces(查看跟踪记录)以直观呈现已上传的跟踪记录。每个跟踪记录的标签页都会显示在窗口的顶部面板上。如果上传的文件包含相关跟踪记录,屏幕录制的跟踪记录的浮动视图会叠加在屏幕上。

    view_traces_winscope

    图 7. 通过 Winscope 查看跟踪记录。

    使用窗口最顶部面板中的界面,可重命名 edit_name 和下载您上传的跟踪记录 download_trace,或上传新的跟踪记录。

  3. 使用窗口底部面板上的时间滑块工具浏览随时间变化的跟踪记录。如需进行更多时间导航,请使用以下功能,如图 8 所示:

    • 如需导航到特定时间或出现,请使用光标(时间滑块)或时间显示框(左下角)中的向左 arrow_left_time 和向右 arrow_right_time 箭头,或使用键盘上的向左和向右箭头。
    • 如需在时间轴上显示所选的用不同颜色标识的跟踪记录,请使用下拉菜单(时间滑块左侧)。默认情况下,使用跟踪标签页查看的最后三条跟踪记录显示在时间轴上。
    • 如需查看所有上传的跟踪记录的精细视图,请使用放大 zoom_in_time 或缩小 zoom_out_time 工具(位于时间滑块下方)或在键盘上滚动。使用重置按钮可重置缩放级别。
    • 如需查看跟踪记录分布情况的展开视图,请点击向上箭头 arrow_up_time(右下角)。

    time_nav_winscope

    图 8. Winscope 上的时间导航。

    在展开视图(图 9)中,选择并放大特定时间范围,以便更好地进行检查:

    expand_time_winscope

    图 9. Winscope 上的展开时间轴。

  4. 如需检查跟踪记录,您可以通过屏幕录制查看设备状态。如需检查特定跟踪记录,请点击工具顶部面板上的相关跟踪记录标签页。

    • 对于 Surface Flinger 跟踪记录,三个面板会显示给定时间段内跟踪记录的不同视图,如图 10 所示: sf_trace

      图 10. Winscope 上的 Surface Flinger 跟踪记录。

      • Layers(层)视图:采用矩形叠加形式的层的 3D 视图。以下界面元素会调整矩形,以便根据其位置、大小、转换和 Z 轴顺序渲染图形元素:

        • 旋转滑块(位于“Layers”[层] 视图的左上角)可旋转分层矩形,以便从所选角度查看它们。
        • 间距滑块(位于“Layers”[层] 视图的右上角)可调整层之间的间距以创建所选的合成视图。
        • 缩放工具(位于“Layers”[层] 视图的右上角)可放大 zoom_in_time 和缩小 zoom_out_time 层,以便更好地进行检查。
        • 重置按钮 reset_sf(位于“Layers”[层] 视图的右上角)可将相机设置恢复为原视图。
        • 拖动矩形以便于更好地缩放。
      • Hierarchy(层次结构)视图:层的完整层次结构。

        • 选择 Only visible(仅可见)(位于“Hierarchy”[层次结构] 视图的右上角)后,系统会隐藏层次结构中的不可见层,以帮助在屏幕上直观呈现元素。
        • 选择 Flat(扁平)(位于“Hierarchy”[层次结构] 视图的右上角)后,系统会将层次结构显示为扁平化的层列表。
        • 只有在发生状态转换时,系统才会选择 Show diff(显示差异)(位于“Hierarchy”[层次结构] 视图的左上角)。选中该选项后,它会将当前状态与之前的状态进行比较。新元素会以绿色突出显示,已删除的元素会以红色突出显示,而已修改的元素会以蓝色突出显示。
      • Properties(属性)视图:所选层的属性。Properties(属性)视图的顶部面板仅包含有关关键属性的信息,例如 VisibilityGeometryBufferProperties(属性)视图的底部面板中包含一个具有所有属性的 Proto Dump(Proto 转储)。

        • Show Diff(显示差异)复选框(位于“Properties”[属性] 视图的左上角)的行为与其在 Hierarchy(层次结构)视图中的行为相同。
        • 选择 Show defaults(显示默认值)(位于“Properties”[属性] 视图的左上角)后,将显示“Proto Dump”(Proto 转储)中的默认 proto 值。默认情况下,这些值不会列在“Proto Dump”(Proto 转储)中。默认 proto 值取自 proto 字段定义。如果 proto 字段未设置非 null 默认值,则显示的默认 proto 值为:
          • 字符串:Null
          • 数值:0
          • 布尔值:False
          • 对象:Null

      这三种视图和屏幕录制之间的选择是同步的,也就是说,当您导航到不同的时间点时,所有跟踪记录都会同步更新。如需查看层的属性,可通过以下两种方式来选择相应层:在“Hierarchy”(层次结构)视图中点击该层,或者在“Properties”(属性)视图中点击相应的矩形。紫色矩形表示视图跟踪记录已附加到此层。当您双击紫色层时,界面会导航到相关的视图跟踪记录标签页。

    • 对于 Window Manager 跟踪记录,三个面板会显示给定时间段内跟踪记录的不同视图,如图 11 所示:

      • Windows 视图:层的 3D 视图。
      • Hierarchy(层次结构)视图:层的完整层次结构。
      • Properties(属性)视图包含一个具有所有属性的 Proto Dump(Proto 转储)。

      这三种视图和屏幕录制之间的选择是同步的,也就是说,当您导航到不同的时间点时,所有跟踪记录都会同步更新。

      wm_trace

      图 11. Winscope 上的“Window Manager”(窗口管理器)跟踪记录。

    • 对于 Transactions(事务)跟踪记录,Surface Flinger 和 Window Manager 之间的事务以表格格式显示,可按显示的 ID、类型和文本进行搜索,同时还提供一个显示 proto 转储的属性视图。这两种视图与屏幕录制之间的选择是同步的:

      transaction_trace

      图 12. Winscope 上的“Transactions”(事务)跟踪记录。

    • 对于 ProtoLog 跟踪记录,系统会以表格格式显示信息,您可以通过标记、源文件和文本对其进行搜索:

      protolog_trace

      图 13. Winscope 上的 ProtoLog 跟踪记录。

    • 对于 Transitions(转换)跟踪记录,系统会显示包含 ID、类型、发送时间、时长和状态的转换列表,以及所选转换的属性:

      transitions_trace

      图 14. Winscope 上的“Transitions”(转换)跟踪记录。