Tracing Window Transitions

You can trace window transitions with WinScope, which provides infrastructure and tools to record and analyze Window Manager and Surface Flinger states during and after transitions. WinScope records all pertinent system service states to a trace file, which you can use to replay and step through the transition.

Capturing traces

You can capture traces through Quick Settings or ADB on devices running userdebug or eng builds.

From Quick Settings

1. Enable developer options
2. Go to Developer options -> Quick settings developer tiles
3. Enable WinScope Trace
4. Open Quick Settings
5. Tap Winscope Trace to enable tracing
6. Run window transitions on the device
7. After you are finished, open Quick Settings and tap Winscope Trace to disable tracing

Traces are written to /data/misc/wmtrace/wm_trace.pb and /data/misc/wmtrace/layers_trace.pb. They are also included in any bugreports.

From ADB

Window Manager trace

1. Enable trace

   adb shell cmd window tracing start

2. Disable trace

   adb shell cmd window tracing stop

3. Grab trace file

   adb pull /data/misc/wmtrace/wm_trace.pb wm_trace.pb

Surface Flinger trace

1. Enable trace

   adb shell su root service call SurfaceFlinger 1025 i32 1

2. Disable trace

   adb shell su root service call SurfaceFlinger 1025 i32 0

3. Grab trace file

   adb pull /data/misc/wmtrace/layers_trace.pb layers_trace.pb

Generating state dumps

WinScope can read a snapshot of Window Manager and Surface Flinger's current state from bugreports. The bugreport stores the states as separate proto files inside the proto folder. To generate the state dumps using ADB, run these commands.

Window Manager

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

Surface Flinger

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

Analyzing traces

To analyze a trace file, use the WinScope web app. The app can be built from source or opened from the prebuilt directory.

1. Download prebuilt artifact from Android source repository

   curl 'https://android.googlesource.com/platform/prebuilts/misc/+/master/common/winscope/winscope.html?format=TEXT' | base64 -d > winscope.html

2. Open downloaded artifact in a web browser
3. After WinScope opens, click OPEN FILE to load a trace file

Using WinScope

After opening a trace file in WinScope, you can analyze the trace in several ways.

Timeline

Use arrow keys or click each entry to navigate through the timeline.

Screen

Provides a visual representation of every visible window on the screen. Click a window to select the source window in the hierarchy.

Hierarchy

Represents each window known to the system. Some windows do not contain buffers, but exist to set policies on its children. Visible windows are marked with the V icon.

Properties

Shows state information for the selected entry in the hierarchy.

Developing WinScope

When the trace is enabled, Window Manager and Surface Flinger capture and save current state to a file at each point of interest. frameworks/base/core/proto/android/server/windowmanagertrace.proto and frameworks/native/services/surfaceflinger/layerproto/layerstrace.proto contain the proto definitions for their internal states.

Checking out code and setting up environment

1. Install Yarn, a JS package manager
2. Download Android source
3. Navigate to development/tools/winscope
4. Run

   yarn install

Building & testing changes

1. Navigate to development/tools/winscope
2. Run

   yarn run dev