使用 Winscope 跟踪窗口转换

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

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

SurfaceFlinger
WindowManager
WMShell
IME
启动器

运行 Winscope 跟踪记录查看器

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

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

下载 Android 源代码。
导航到 Winscope 文件夹：
```
cd development/tools/winscope
```
使用以下命令安装依赖项：
```
npm install
```
如需查看可用命令的列表，请运行以下命令： npm run
使用以下命令构建所有生产和测试目标：
```
npm run build:prod
```
使用以下命令运行 Winscope：
```
npm run start
```

捕获跟踪记录

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

在设备上捕获跟踪记录

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

在 Android 设备上：

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

图 1. 包含“录制跟踪记录”的“快捷设置”菜单。
仅执行重现错误所需的步骤。
如需停止捕获，请打开“快捷设置”，然后选择停止跟踪。
使用所列选项之一共享捕获的日志，如 Gmail、云端硬盘或 BetterBug。

通过 Winscope 捕获跟踪记录

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

在 Winscope 上：

在 Collect Traces（收集跟踪记录）界面上，点击 ADB Proxy（ADB 代理）：

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

注意：必须使用 Python 3.5+ 和 ADB。

运行以下命令：

python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py

如需开始捕获，请在 Collect Traces（收集跟踪记录）界面上选择目标和配置，然后点击 Start trace（开始跟踪）：

图 3. 在 Winscope 上收集跟踪记录。
如需停止捕获，请点击 End trace（结束跟踪记录）：

图 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 上分析跟踪记录：

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

注意：支持的跟踪文件类型包括 Winscope 跟踪记录、包含 Winscope 元数据（使用 adb 收集）的 MP4 视频、ZIP 文件和错误报告。

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

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

使用窗口最顶部面板中的界面，可重命名和下载您上传的跟踪记录，或上传新的跟踪记录。
使用窗口底部面板上的时间滑块工具浏览随时间变化的跟踪记录。如需进行更多时间导航，请使用以下功能，如图 8 所示：
- 如需导航到特定时间或出现，请使用光标（时间滑块）或时间显示框（左下角）中的向左和向右箭头，或使用键盘上的向左和向右箭头。
- 如需在时间轴上显示所选的用不同颜色标识的跟踪记录，请使用下拉菜单（时间滑块左侧）。默认情况下，使用跟踪标签页查看的最后三条跟踪记录显示在时间轴上。
- 如需查看所有上传的跟踪记录的精细视图，请使用放大或缩小工具（位于时间滑块下方）或在键盘上滚动。使用重置按钮可重置缩放级别。
- 如需查看跟踪记录分布情况的展开视图，请点击向上箭头（右下角）。
图 8. Winscope 上的时间导航。

在展开视图（图 9）中，选择并放大特定时间范围，以便更好地进行检查：

图 9. Winscope 上的展开时间轴。
如需检查跟踪记录，您可以通过屏幕录制查看设备状态。如需检查特定跟踪记录，请点击工具顶部面板上的相关跟踪记录标签页。
- 对于 Surface Flinger 跟踪记录，三个面板会显示给定时间段内跟踪记录的不同视图，如图 10 所示：
  
  图 10. Winscope 上的 Surface Flinger 跟踪记录。
  - Layers（层）视图：采用矩形叠加形式的层的 3D 视图。以下界面元素会调整矩形，以便根据其位置、大小、转换和 Z 轴顺序渲染图形元素：
    - 旋转滑块（位于“Layers”[层] 视图的左上角）可旋转分层矩形，以便从所选角度查看它们。
    - 间距滑块（位于“Layers”[层] 视图的右上角）可调整层之间的间距以创建所选的合成视图。
    - 缩放工具（位于“Layers”[层] 视图的右上角）可放大和缩小层，以便更好地进行检查。
    - 重置按钮（位于“Layers”[层] 视图的右上角）可将相机设置恢复为原视图。
    - 拖动矩形以便于更好地缩放。
    注意：Only visible（仅可见）和 Show virtual（显示虚拟）复选框已被废弃。
  - Hierarchy（层次结构）视图：层的完整层次结构。
    - 选择 Only visible（仅可见）（位于“Hierarchy”[层次结构] 视图的右上角）后，系统会隐藏层次结构中的不可见层，以帮助在屏幕上直观呈现元素。
    - 选择 Flat（扁平）（位于“Hierarchy”[层次结构] 视图的右上角）后，系统会将层次结构显示为扁平化的层列表。
    - 只有在发生状态转换时，系统才会选择 Show diff（显示差异）（位于“Hierarchy”[层次结构] 视图的左上角）。选中该选项后，它会将当前状态与之前的状态进行比较。新元素会以绿色突出显示，已删除的元素会以红色突出显示，而已修改的元素会以蓝色突出显示。
  - Properties（属性）视图：所选层的属性。Properties（属性）视图的顶部面板仅包含有关关键属性的信息，例如 Visibility、Geometry 和 Buffer。 Properties（属性）视图的底部面板中包含一个具有所有属性的 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 转储）。
  这三种视图和屏幕录制之间的选择是同步的，也就是说，当您导航到不同的时间点时，所有跟踪记录都会同步更新。
  
  注意：界面元素在三个视图上的功能和位置与在 Surface Flinger 跟踪记录中类似。
  
  图 11. Winscope 上的“Window Manager”（窗口管理器）跟踪记录。
- 对于 Transactions（事务）跟踪记录，Surface Flinger 和 Window Manager 之间的事务以表格格式显示，可按显示的 ID、类型和文本进行搜索，同时还提供一个显示 proto 转储的属性视图。这两种视图与屏幕录制之间的选择是同步的：
  
  图 12. Winscope 上的“Transactions”（事务）跟踪记录。
- 对于 ProtoLog 跟踪记录，系统会以表格格式显示信息，您可以通过标记、源文件和文本对其进行搜索：
  
  图 13. Winscope 上的 ProtoLog 跟踪记录。
- 对于 Transitions（转换）跟踪记录，系统会显示包含 ID、类型、发送时间、时长和状态的转换列表，以及所选转换的属性：
  
  图 14. Winscope 上的“Transitions”（转换）跟踪记录。