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

使用 Winscope 捕获跟踪记录

您可在本地运行 Winscope 或通过 Web 服务器访问它。

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

启动 Winscope 后，系统会显示 Collect Traces 界面。

设备连接

您可在 Winscope 中使用 Winscope Proxy 或 Web Device Proxy 连接设备。默认情况下，Winscope 首页会显示 Winscope Proxy 连接设置界面。

如需开始捕获跟踪记录，请选择以下设备连接机制之一。

请按照以下步骤设置 Winscope Proxy：

在首页的 Collect Traces 下，从 Select connection type 下拉菜单中选择 Winscope Proxy：

图 1. 使用 Winscope Proxy 捕获跟踪记录。
通过运行以下命令，启动 Winscope ADB Connect 代理，以直接从浏览器中捕获跟踪记录：
```
python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py
```
注意：必须使用 Python 3.10+ 和 adb。
请记下执行后终端上显示的 Winscope Proxy 令牌。
启动 Winscope ADB Connect 代理后，界面会发生如下变化。如需与代理建立初始连接，请输入第 3 步中的 Winscope Proxy 令牌，然后点击 Connect。

图 2. 连接到 Winscope Proxy。

请按照以下步骤设置 Web Device Proxy：

在首页的 Collect Traces 下，从 Select connection type 下拉菜单中选择 Web Device Proxy：

图 3. 使用 Web Device Proxy 捕获跟踪记录。
如果您的计算机上没有 Web Device Proxy 守护程序，请点击安装或运行安装程序。

注意：Mac 尚不支持 Web Device Proxy。
通过对话框向源设备授予 Web Device Proxy 访问权限。

图 4. 向源设备授权。
在首次连接到新设备时，批准该设备的访问权限。如果对话框未自动显示，请点击设备旁边的 lock_open 图标：

图 5. 向当前设备授权。

请按照以下步骤收集跟踪记录：

连接后，如需启动捕获过程，请选择目标并配置设置。然后点击 Start trace 以开始捕获：

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

图 7. 在 Winscope 中结束跟踪。

本部分介绍了每种跟踪记录类型的选项。

借助 Winscope，您可以录制多个显示屏的屏幕。从菜单中选择要录制屏幕的显示屏。如果您未做选择，Winscope 会默认录制处于活跃状态的显示屏。

Buffer size：调整 SurfaceFlinger 跟踪的内存中环形缓冲区的大小。缓冲区越大，可收集的数据就越多，但内存用量也会随之增加。

注意：Buffer size 在 Android 15 中已废弃。
Input：如果 Surface 包含输入数据，则跟踪输入窗口的具体信息。
Composition：跟踪组合类型和可见区域。
Metadata：跟踪其他 Surface 元数据，包括屏幕外的层。

Warning：元数据非常冗长，需要大量内存。
HWC：跟踪其他非结构化硬件混合渲染器元数据。

Warning：HWC 非常冗长，需要大量内存。
Trace buffers：配置 SurfaceFlinger 以跟踪 Surface 上的所有缓冲区更改。默认情况下，SurfaceFlinger 仅在几何图形发生更改时跟踪新状态。
Virtual displays：在跟踪记录中包含虚拟显示屏层。

Buffer size：调整 WindowManager 跟踪记录的内存中环形缓冲区的大小。缓冲区越大，可收集的数据就越多，但内存用量也会随之增加。
Tracing type：定义用于收集状态的频率选项：
- frame：在此模式下，WindowManager 会在每帧中转储单个状态，以确保仅捕获有效的 WindowManager 状态。此模式的性能开销最低。
- transaction：每当提交事务时，此模式都会记录 WindowManager 状态。您可在一个帧内提交多个事务，因此可在一个帧期间调试中间 WindowManager 状态。不过，与 frame 模式相比，此模式的性能开销更高。
Tracing level：确定 WindowManager 跟踪记录的详细程度：
- verbose：包含每个窗口的所有窗口和配置信息。此模式的内存和性能开销最高。
- debug：包含有关所有窗口的信息，但仅在窗口配置包含请求的替换配置时才会记录该配置。
- critical：包含与调试模式相同的信息，但仅包含可见窗口。此模式的内存和性能开销最低。

如需使用 Winscope 进行状态转储，请在首页的 Collect Traces 下选择 Dump 标签页，然后点击 Dump state：

在 Winscope 中转储状态

图 8. 在 Winscope 中转储状态。

Winscope 可让您截取多个显示屏的屏幕截图。从菜单中选择要截屏的显示屏。如果未进行选择，系统会针对处于活跃状态的显示屏收集屏幕截图。