WinScope provides the infrastructure and tools to record and analyze WindowManager and SurfaceFlinger states during and after window transitions. WinScope records all pertinent system service states to a trace file, which you can use to replay and step through the transitions.
Capturing traces
Capture traces through Quick Settings or
adb
on devices running userdebug or eng builds.
Quick settings
To capture traces 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.winscope
and
/data/misc/wmtrace/layers_trace.winscope
. Traces are also included in
bug reports.
adb
When capturing traces through adb
, capture
WindowManager and SurfaceFlinger traces separately.
WindowManager traces
To capture WindowManager traces:
- Enable trace:
adb shell cmd window tracing start
- Disable trace:
adb shell cmd window tracing stop
- Take the trace file:
adb pull /data/misc/wmtrace/wm_trace.winscope wm_trace.winscope
You can optionally change the default log configuration of various settings for WindowManager traces:
- Set the log frequency (for the transaction or frame):
adb shell cmd window tracing [frame | transaction]
- Configure the verbose level for log entries:
adb shell cmd window tracing level [all | trim | critical]
- Set the maximum buffer size (in KB):
adb shell cmd window tracing size size-value
- Dump the buffer status, log level, remaining capacity, and number of
elements:
adb shell cmd window tracing status
SurfaceFlinger traces
To capture SurfaceFlinger traces:
- Enable trace:
adb shell su root service call SurfaceFlinger 1025 i32 1
- Disable trace:
adb shell su root service call SurfaceFlinger 1025 i32 0
- Take the trace file:
adb pull /data/misc/wmtrace/layers_trace.winscope layers_trace.winscope
You can optionally change the default log configuration of various settings for SurfaceFlinger traces:
- Set the maximum buffer size (in KB):
adb shell su root service call SurfaceFlinger 1029 i32 size-value
- Configure the verbose level for log entries:
adb shell su root service call SurfaceFlinger 1033 i32 flags
Transactions
To capture transactions:
- Enable trace:
adb shell su root service call SurfaceFlinger 1020 i32 1
- Disable trace:
adb shell su root service call SurfaceFlinger 1020 i32 0
- Take the trace file:
adb pull /data/misc/wmtrace/transaction_trace.winscope
More transaction merge files are available in `/data/misc/wmtrace/` with naming `transaction_merges_*.winscope`.
Generating state dumps
WinScope reads a snapshot of WindowManager and SurfaceFlinger states
from bug reports. The bug reports store the states as separate proto files
inside the proto
folder. To generate the state dumps using
adb
, run the following commands.
WindowManager
adb exec-out dumpsys window --proto > window_dump.winscope
SurfaceFlinger
adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope
Analyzing traces
To analyze a trace file, use the WinScope web app. Build the app from the source or open it from the prebuilt directory.
- Download prebuilt artifacts from the Android source repository:
curl 'https://android.googlesource.com/platform/prebuilts/misc/+/master/common/winscope/winscope.html?format=TEXT' | base64 -d > winscope.html
- Open the downloaded artifacts in a web browser.
- After WinScope opens, select 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 — Shows the sequence of events in the trace. Use the 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.
- Screen recording — Shows the device screen synchronized with the trace. Navigates together with the timeline.
- Hierarchy — Represents each window known to the
system. Some windows don't contain buffers, but exist to set policies on
the window's children. Visible windows are marked with the
V
icon. - Properties — Shows state information for the selected entry in the hierarchy.