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
- Enable developer options
- Go to Developer options -> Quick settings developer tiles
- Enable WinScope Trace
- Open Quick Settings
- Tap Winscope Trace to enable tracing
- Run window transitions on the device
- 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
- Enable trace
adb shell cmd window tracing start
- Disable trace
adb shell cmd window tracing stop
- Grab trace file
adb pull /data/misc/wmtrace/wm_trace.pb wm_trace.pb
Surface Flinger trace
- Enable trace
adb shell su root service call SurfaceFlinger 1025 i32 1
- Disable trace
adb shell su root service call SurfaceFlinger 1025 i32 0
- 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.
- 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
- Open downloaded artifact in a web browser
- 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
- Install Yarn, a JS package manager
- Download Android source
- Navigate to
development/tools/winscope
- Run
yarn install
Building & testing changes
- Navigate to
development/tools/winscope
- Run
yarn run dev