Trace window transitions using Winscope

Winscope is a web tool that lets users record, replay, and analyze the states of several system services during and after animations and transitions. Winscope records all pertinent system service states to a trace file. Using the Winscope UI with the trace file, you can inspect the state of these services for each animation frame, with or without a screen recording, by replaying, stepping, and debugging through the transitions.

The system services that produce traces that can be loadable into Winscope are as follows:

SurfaceFlinger
WindowManager
WMShell
IME
Launcher

Run the Winscope trace viewer

Winscope tracing is part of the services on the platform. This section outlines the steps required to download, build, and run the Winscope trace viewer.

Follow these steps to set up your PC to run the Winscope tracer:

Download the Android source.
Navigate to the Winscope folder:
```
cd development/tools/winscope
```
Install dependencies using:
```
npm install
```
To see a list of available commands, run: npm run
Build all prod and test targets using:
```
npm run build:prod
```
Run Winscope using:
```
npm run start
```

Capture traces

You can capture traces on the device, through Winscope, or through Android Debug Bridge (adb) commands.

Capture traces on the device

Capture traces on the device to collect data when filing bugs for animation issues. All UI traces are recorded with this method, as the configuration can’t be customized.

On your Android device:

Enable developer options.
Select System Tracing under Developer Options.
Enable Collect Winscope traces.
Under Miscellaneous:
1. Enable Attach recordings to bug reports.
2. Enable Show Quick Settings tile.
Navigate to where you need to reproduce the bug.
To start the capture, open Quick Settings and select Record trace:

Figure 1. Quick setting menu with Record Trace.
Execute only the steps necessary to reproduce the bug.
To stop the capture, open Quick Settings and select Stop tracing.
Share the captured log using one of the options listed, such as Gmail, Drive, or BetterBug.

Capture traces through Winscope

You can capture traces using Winscope for local development and debugging. Winscope uses adb, which supports device connection over USB or Wi-Fi.

On Winscope:

On the Collect Traces screen, click ADB Proxy:

Figure 2. Capture traces on Winscope.
Launch the Winscope ADB Connect proxy to capture traces directly from your browser.

Note: Python 3.5+ and ADB are required.

Run the command:

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

To start the capture, on the Collect Traces screen select the targets and configuration and click Start trace:

Figure 3. Collect traces on Winscope.
To stop the capture, click End trace:

Figure 4. End trace on Winscope.

As the tool uploads the traces on Winscope’s UI, the Fetching and Parsing Proto Files messages appear on screen.

Generate the state dump using Winscope

To take a state dump using Winscope, on the Collect Traces screen select the Dump tab and then click Dump state:

dump-winscope

Figure 5. Dump state on Winscope.

Capture traces through adb commands

Run adb root before running the adb shell commands for each of the following traces. At the end of the trace, the trace files are available in /data/misc/wmtrace. To copy a file or directory and its subdirectories from a device, see Copy files to and from a device. See adb for more information.

WindowManager traces

To capture WindowManager traces:

Enable trace:
```
adb shell wm tracing start
```
Disable trace:
```
adb shell wm tracing stop
```
Save logging data to file while running a trace capture:
```
adb shell wm tracing save-for-bugreport
```
Log trace once per frame:
```
adb shell wm tracing frame
```
Log each transaction:
```
adb shell wm tracing transaction
```
Set the maximum log size (in KB):
```
adb shell wm tracing size
```
Print trace status:
```
adb shell wm tracing status
```
Set the log level to critical (only visible windows with reduced information), trim (all windows with reduced information), or all (all windows and information):
```
adb shell wm tracing level
```

ProtoLog

The following commands are used for the ProtoLog system.

In the system_server process:

Start ProtoLog:
```
adb shell cmd window logging start
```
Stop ProtoLog:
```
adb shell cmd window logging stop
```

Enable ProtoLog for given log groups:

adb shell cmd window logging enable [group...]

Disable ProtoLog for given log groups:

adb shell cmd window logging disable [group...]

Enable Logcat logging for given log groups:

adb shell cmd window logging enable-text [group...]

Disable Logcat logging for given log groups:

adb shell cmd window logging disable-text [group...]

In WMShell:

Start ProtoLog:

adb shell dumpsys activity service SystemUIService WMShell

Transition tracing

The following commands are used for transition tracing:

In the system_server process:

Start a trace:

adb shell cmd window shell tracing start

Stop a trace:

adb shell cmd window shell tracing stop

Start a trace in WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

Stop a trace in WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

Input Method Editor

The following commands are used for Input Method Editor (IME) tracing:

Start IME tracing for Input Method (IM) clients, Input Method Service (IMS), and Input Method Management Service (IMMS):
```
adb shell ime tracing start
```
Start tracing IME clients, IMS, and IMMS:
```
adb shell ime tracing stop
```

SurfaceFlinger layers

SurfaceFlinger layer tracing uses Perfetto trace for capture. See Trace configuration for configuration information.

See the following example of a configuration for SurfaceFlinger layer tracing:

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
        }
    }
}

See the following example command to generate tracing for SurfaceFlinger layers:

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

SurfaceFlinger transactions

SurfaceFlinger transaction tracing uses Perfetto trace for capture. See Trace configuration for configuration information.

See the following example of a Perfetto configuration for SurfaceFlinger active tracing:

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

See the following example of a Perfetto configuration for SurfaceFlinger continuous tracing:

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
        }
    }
}

See the following example command to generate tracing for SurfaceFlinger transactions:

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

Generate state dump using adb

Winscope reads a snapshot of WindowManager and SurfaceFlinger states from bug reports. The bug reports store the states as separate proto files within the proto folder. To generate the state dumps using adb, run the following commands.

For WindowManager:

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

For SurfaceFlinger:

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

Analyze traces

To debug transient and invalid states that cause animation issues, Winscope aggregates different trace files, provides search and visualization over frames and timelines, and presents protobuf messages in a coherent manner. Analyzing traces in Winscope helps identify the exact layer, frame, and state of the bug's occurrence.

Use Winscope

When you've captured traces, analyze the traces on Winscope:

Upload your saved traces using the panel on the right. You can remove uploaded traces or upload more traces.

Note: The supported trace file types are Winscope traces, MP4 videos with Winscope metadata (collected with adb), zip files, and bug reports.

Figure 6. Upload traces on Winscope.
Click View traces to visualize the uploaded traces. Tabs for each trace appear on the top panel of the window. If the uploaded file contains the relevant traces, a floating view of the screen recording trace is overlaid on the screen.

Figure 7. View traces on Winscope.

Use the UI on the topmost panel of the window to rename and download your uploaded trace or to upload a new one.
Navigate through the traces over time using the time slider tool at the bottom panel of the window. For additional time navigation, use the following features, as shown in Figure 8:
- To navigate to a particular time or occurrence, use the cursor (time slider), or the left and right arrows in the time display box (lower left corner), or left and right arrows on your keyboard.
- To display selected color-coded traces on the timeline, use the drop-down menu (left of the time slider). By default, the last three traces viewed using the trace tabs are displayed on the timeline.
- For a granular view of all the uploaded traces, use the zoom in or zoom out tool (under the time slider), or scroll on your keyboard. Use the reset button to reset the zoom level.
- For an expanded view of the trace distribution over time, click the up arrow (lower right corner).
Figure 8. Time navigation on Winscope.

In the expanded view (Figure 9), select and zoom in on specific time frames for better inspection:

Figure 9. Expanded timeline on Winscope.
To examine traces, you can view the device state with the screen recording. To examine a particular trace, click the relevant trace tab on the top panel of the tool.
- For the Surface Flinger trace, three panels display different views of the trace at a given time period, as shown in Figure 10:
  
  Figure 10. Surface Flinger trace on Winscope.
  - Layers view: A 3D view of the layers in rectangular overlays. The following UI elements adjust the rectangles to render the graphical elements in terms of their position, size, transform, and z-order:
    - The Rotation slider (top left of the Layers view) rotates the layered rectangles to view them at chosen angles.
    - The Spacing slider (top right of the Layers view) adjusts the spacing between the layers to create the chosen composite view.
    - The zoom tools (top right of the Layers view) zoom in and zoom out into the layers for better inspection.
    - The reset button (top right of the Layers view) restores the camera settings to the original view.
    - Drag the rectangles to facilitate better zooming.
    Note: The Only visible and Show virtual checkboxes are deprecated.
  - Hierarchy view: A full hierarchy of the layers.
    - Only visible (top right of the Hierarchy view), when selected, hides invisible layers from the hierarchy to help visualize the elements on the screen.
    - Flat (top right of the Hierarchy view), when selected, shows the hierarchy as a flattened list of layers.
    - Show diff (top left of the Hierarchy view) is selected only when there's a state transition. When selected, the tool compares the current state against the previous one. A new element is highlighted in green, a deleted element is highlighted in red, and a modified element is highlighted in blue.
  - Properties view: Properties of the selected layer. The top panel of the Properties view contains information about only key properties, such as Visibility, Geometry, and Buffer. The bottom panel of the Properties view contains a Proto Dump of all properties.
    - The Show Diff checkbox (top left of the Properties view) behaves as in the Hierarchy view.
    - Show defaults (top left of the Properties view), when selected, displays the default proto values on the Proto Dump. By default, these values aren't listed in the Proto Dump. The default proto values are taken from the proto field definition. If a proto field doesn't have a nonnull default value set, the default proto values shown are:
      - Strings: Null
      - Numbers: 0
      - Boolean values: False
      - Objects: Null
  Selection between the three views and the screen recording is synchronized, that is, all traces synchronously update when you navigate to a different point in time. To see the properties for a layer, select the layer by clicking it in the Hierarchy view or by clicking the respective rectangle in the Properties view. A purple rectangle indicates that a view trace is attached to this layer. On double clicking a purple layer, the UI navigates to change to the relevant view trace tab.
- For the Window Manager trace, three panels display different views of the trace at a given time period, as shown in Figure 11:
  - Windows view: A 3D view of the layers.
  - Hierarchy view: A full hierarchy of the layers.
  - Properties view contains a Proto Dump of all properties.
  Selection between the three views and the screen recording is synchronized, that is, all traces synchronously update when you navigate to a different point in time.
  
  Note: The function and placement of UI elements on the three views are similar to those in the Surface Flinger trace.
  
  Figure 11. Window Manager trace on Winscope.
- For Transactions traces, the transactions between the Surface Flinger and Window Manager are presented in table format which is searchable by the displayed IDs, type, and text, along with a properties view that shows the proto dump. Selection between the two views and the screen recording is synchronized:
  
  Figure 12. Transactions trace on Winscope.
- For ProtoLog traces, the information is presented in a table format, which is searchable by tags, source files, and text:
  
  Figure 13. ProtoLog trace on Winscope.
- For Transitions traces, a list of transitions with the ID, type, send time, duration, and status is displayed along with the properties of the selected transition:
  
  Figure 14. Transitions trace on Winscope.