Tracing Window Transitions

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:

  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.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:

  1. Enable trace: 
    adb shell cmd window tracing start
  2. Disable trace: 
    adb shell cmd window tracing stop
  3. 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:

  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. 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:

  1. Enable trace: 
    adb shell su root service call SurfaceFlinger 1020 i32 1
  2. Disable trace: 
    adb shell su root service call SurfaceFlinger 1020 i32 0
  3. 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 can from the source or open it from the prebuilt directory.

  1. 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
  2. Open the downloaded artifacts in a web browser.
  3. 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.

WinScope Screenshot
Figure 1. Analyzing a trace in WinScope
  • 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.