Capture traces with adb commands

Winscope traces can be collected with the adb command line on debug builds (that is, userdebug and eng builds). Before collecting Winscope traces with adb, run adb root.

Warning: Using adb commands isn't recommended, unless you want to create custom scripts to enable, disable, or fetch traces.

Starting in Android 15, Winscope traces are integrated into Perfetto and are collected using the Perfetto command line. Each Winscope trace is a Perfetto data source with its own configuration. You can enable configurations individually or in a single tracing session.

In Android 14 and lower, each Winscope trace has a different command and you can collect each independently. See Capture traces in Android 14 and lower for more information.

WindowManager

Note: This configuration is used for both WindowManager traces and dumps.

Use the data source name android.windowmanager for this trace type.

Configuration options

• Log level (log_level): Specifies log verbosity. Supported values:

  • LOG_LEVEL_VERBOSE: Logs all elements with maximum amount of information.
  • LOG_LEVEL_DEBUG: Logs all elements but doesn't write all configuration data.
  • LOG_LEVEL_CRITICAL: Logs only visible elements, with the minimum amount of performance overhead.

• Log frequency (log_frequency): Defines the frequency in which items are logged:

  • LOG_FREQUENCY_FRAME: Traces state snapshots when a frame is committed.
  • LOG_FREQUENCY_TRANSACTION: Traces state snapshots every time a transaction is committed.
  • LOG_FREQUENCY_SINGLE_DUMP: Traces single state snapshots when the data source is started.

See WindowManager for details about configuration values.

Note: If you don't provide a custom configuration, the WindowManager trace defaults to LOG_LEVEL_DEBUG and LOG_FREQUENCY_FRAME.

Example

The following is an example of the WindowManager trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

Use the data source name android.protolog for this trace type.

Configuration options

Tracing mode (tracing_mode): Determines the log configuration to use:

• DEFAULT: Traces only log groups and levels specified in the group_overrides.
• ENABLE_ALL: Traces all log groups and levels, unless specified in the group_overrides.

Minimum log level (default_log_from_level): If set, any message with a log level higher than and including this level is traced, unless a group override is specified. For example, this is used to enable all warnings and errors to be logged, without having to enable all logs. The supported values are:

• PROTOLOG_LEVEL_DEBUG
• PROTOLOG_LEVEL_VERBOSE
• PROTOLOG_LEVEL_INFO
• PROTOLOG_LEVEL_WARN
• PROTOLOG_LEVEL_ERROR
• PROTOLOG_LEVEL_WTF

Group overrides (group_overrides): Enables manual configuration of the log level for each ProtoLog group. Each group contains:

• name: ProtoLog group name, used in the Android source code.
• log_from: Same as default_log_from_level but specified only for the current group.

• collect_stacktrace: When set to true, collects the stack trace for each ProtoLog message in the group being traced.

  Warning: Logging stack traces is slow and affects device performance. This feature is better suited for local development.

Example

The following is an example of the ProtoLog trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: DEFAULT
              default_log_from_level: PROTOLOG_LEVEL_WARN
              group_overrides: {
                 group_name: "WM_SHELL_STARTING_WINDOW"
                 log_from: PROTOLOG_LEVEL_DEBUG
                 collect_stacktrace: true
              }
           }
       }
   }
EOF

Input

Use the data source name android.input.inputevent for this trace type.

Configuration options

Trace mode (trace_mode): Determines whether the input trace should be started using privacy-preserving rules or record all input events:

• TRACE_MODE_TRACE_ALL: Records all input events processed by the system, regardless of the context in which they were processed.
• TRACE_MODE_USE_RULES: Uses the tracing rules defined in this config to specify what events to trace. See android_input_event_config.proto for more information on specifying the rules for the trace.

Warning: TRACE_MODE_TRACE_ALL must only be used for tracing on a local device or for tests. Never use this for field tracing. All configs used for field tracing or for initiating on-device tracing by the user must use a robust set of rules.

Example

The following is an example of the input trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
EOF

SurfaceFlinger (layers)

Note: This configuration is used for both SurfaceFlinger traces and dumps.

Use the data source name android.surfaceflinger.layers for this trace type.

Configuration options

Tracing mode (mode): Defines the frequency in which items are logged:

• MODE_ACTIVE: Traces layers snapshots. A snapshot is taken every time a layers change occurs.
• MODE_GENERATED: Generates layers snapshots from the transactions kept in the SurfaceFlinger's internal ring buffer. The layer's snapshots generation occurs when this data source is flushed.
• MODE_DUMP: Traces a single layers snapshot.
• MODE_GENERATED_BUGREPORT_ONLY: Same as MODE_GENERATED, but triggers the layers snapshots generation only when a bug report is taken, not whenever a trace is flushed.

Note: MODE_ACTIVE is computationally heavy and affects performance. For performance critical traces use MODE_GENERATED_BUGREPORT_ONLY.

Trace flags (trace_flags):

• TRACE_FLAG_INPUT: If the surface contains input data, tracks the specifics of the input window.
• TRACE_FLAG_COMPOSITION: Traces the composition type and visible region.

• TRACE_FLAG_EXTRA: Traces additional surface metadata, including offscreen layers.

  Warning: This field is highly verbose and requires a large amount of memory.

• TRACE_FLAG_HWC: Traces additional unstructured hardware composer metadata.

  Warning: This field is highly verbose and requires a large amount of memory.

• TRACE_FLAG_BUFFERS: Configures SurfaceFlinger to trace all buffer changes on the surface. By default, SurfaceFlinger traces a new state only when geometry alterations occur.

• TRACE_FLAG_VIRTUAL_DISPLAYS: Includes virtual display layers in the trace.

Note: If no tracing mode is specified, Winscope defaults to MODE_GENERATED_BUGREPORT_ONLY.

Example

The following is an example of the SurfaceFlinger trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   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
           }
       }
   }
EOF

See SurfaceFlinger for details about the meaning of different configuration values.

Shell transitions

Use the data source name com.android.wm.shell.transition for this trace type.

Configuration options

This trace type has no configuration options.

Example

The following is an example of the shell transition trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
EOF

SurfaceFlinger (transactions)

Use the data source name android.surfaceflinger.transactions for this trace type.

Configuration options

Tracing mode (mode): Defines the frequency in which items are logged:

• MODE_CONTINUOUS: SurfaceFlinger writes its internal ring buffer of transactions every time the data source is flushed. The ring buffer contains the SurfaceFlinger's initial state and the latest transactions.

• MODE_ACTIVE: SurfaceFlinger writes the initial state and then each incoming transaction until the data source is stopped.

Note: If you don't specify a tracing mode, Winscope defaults to MODE_CONTINUOUS.

Example

The following is an example of the SurfaceFlinger transactions trace type for adb.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

Use the data source name: android.inputmethod for this trace type.

Configuration options

This trace type has no configuration options.

Example

The following is an example of the IME trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
EOF

ViewCapture

Use data source name android.viewcapture for this trace type.

Configuration options

This trace type has no configuration options.

Example

The following is an example of the ViewCapture trace type for adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Complete example

Perfetto lets you collect data from multiple sources in a single configuration. You can gather all Winscope traces with a single command:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: ENABLE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
   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
           }
       }
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Capture traces in Android 14 and lower

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.

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
  

WindowManager dumps

To capture WindowManager dumps:

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

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
  

SurfaceFlinger traces (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 dumps (layers)

To capture SurfaceFlinger dumps:

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

Shell transitions

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
  

Note: Transition tracing is always on for userdebug and eng builds.

IME

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 (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 \