Cómo capturar registros con comandos adb

Los seguimientos de Winscope se pueden recopilar con la línea de comandos adb en compilaciones de depuración (es decir, compilaciones userdebug y eng). Antes de recopilar registros de Winscope con adb, ejecuta adb root.

A partir de Android 15, los seguimientos de Winscope se integran en Perfetto y se recopilan con la línea de comandos de Perfetto. Cada registro de Winscope es una fuente de datos de Perfetto con su propia configuración. Puedes habilitar las configuraciones de forma individual o en una sola sesión de seguimiento.

En Android 14 y versiones anteriores, cada registro de Winscope tiene un comando diferente y puedes recoger cada uno de forma independiente. Consulta Cómo capturar registros en Android 14 y versiones anteriores para obtener más información.

WindowManager

Usa el nombre de la fuente de datos android.windowmanager para este tipo de registro.

Opciones de configuración

• Nivel de registro (log_level): Especifica la verbosidad del registro. Valores admitidos:

  • LOG_LEVEL_VERBOSE: Registra todos los elementos con la cantidad máxima de información.
  • LOG_LEVEL_DEBUG: Registra todos los elementos, pero no escribe todos los datos de configuración.
  • LOG_LEVEL_CRITICAL: Solo registra los elementos visibles, con la cantidad mínima de sobrecarga de rendimiento.

• Frecuencia de registro (log_frequency): Define la frecuencia con la que se registran los elementos:

  • LOG_FREQUENCY_FRAME: Genera un seguimiento de las instantáneas de estado cuando se confirma un fotograma.
  • LOG_FREQUENCY_TRANSACTION: Genera un registro de las instantáneas de estado cada vez que se confirma una transacción.
  • LOG_FREQUENCY_SINGLE_DUMP: Genera un seguimiento de instantáneas de estado único cuando se inicia la fuente de datos.

Consulta WindowManager para obtener detalles sobre los valores de configuración.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento de WindowManager para 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

Usa el nombre de la fuente de datos android.protolog para este tipo de registro.

Opciones de configuración

Modo de seguimiento (tracing_mode): Determina la configuración de registro que se usará:

• DEFAULT: Genera registros solo de los grupos y niveles de registro especificados en group_overrides.
• ENABLE_ALL: Genera un seguimiento de todos los grupos y niveles de registro, a menos que se especifique en group_overrides.

Nivel de registro mínimo (default_log_from_level): Si se establece, se realiza un seguimiento de cualquier mensaje con un nivel de registro superior a este nivel, a menos que se especifique una anulación de grupo. Por ejemplo, se usa para habilitar el registro de todas las advertencias y errores, sin tener que habilitar todos los registros. Los valores admitidos son los siguientes:

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

Anulaciones de grupo (group_overrides): Habilita la configuración manual del nivel de registro para cada grupo de ProtoLog. Cada grupo contiene lo siguiente:

• name: Es el nombre del grupo de ProtoLog, que se usa en el código fuente de Android.
• log_from: Igual que default_log_from_level, pero se especifica solo para el grupo actual.

• collect_stacktrace: Cuando se establece en true, recopila el seguimiento de pila de cada mensaje de ProtoLog en el grupo del que se realiza el seguimiento.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento de ProtoLog para 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

Entrada

Usa el nombre de la fuente de datos android.input.inputevent para este tipo de registro.

Opciones de configuración

Modo de seguimiento (trace_mode): Determina si se debe iniciar el seguimiento de entrada con reglas que preservan la privacidad o si se deben registrar todos los eventos de entrada:

• TRACE_MODE_TRACE_ALL: Registra todos los eventos de entrada que procesa el sistema, independientemente del contexto en el que se procesaron.
• TRACE_MODE_USE_RULES: Usa las reglas de seguimiento definidas en esta configuración para especificar qué eventos se deben seguir. Consulta android_input_event_config.proto para obtener más información sobre cómo especificar las reglas del seguimiento.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento de entrada para 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 (capas)

Usa el nombre de la fuente de datos android.surfaceflinger.layers para este tipo de registro.

Opciones de configuración

Modo de registro (mode): Define la frecuencia con la que se registran los elementos:

• MODE_ACTIVE: Rastrea las instantáneas de capas. Se toma una instantánea cada vez que se produce un cambio en las capas.
• MODE_GENERATED: Genera instantáneas de capas a partir de las transacciones que se guardan en el búfer circular interno de SurfaceFlinger. La generación de instantáneas de la capa se produce cuando se borra esta fuente de datos.
• MODE_DUMP: Traza una instantánea de una sola capa.
• MODE_GENERATED_BUGREPORT_ONLY: Es igual que MODE_GENERATED, pero activa la generación de instantáneas de capas solo cuando se toma un informe de errores, no cada vez que se borra un registro.

Marcas de seguimiento (trace_flags):

• TRACE_FLAG_INPUT: Si la superficie contiene datos de entrada, realiza un seguimiento de las especificaciones de la ventana de entrada.
• TRACE_FLAG_COMPOSITION: Rastrea el tipo de composición y la región visible.

• TRACE_FLAG_EXTRA: Rastrea metadatos de superficie adicionales, incluidas las capas fuera de la pantalla.

• TRACE_FLAG_HWC: Genera un registro de metadatos adicionales del compositor de hardware no estructurado.

• TRACE_FLAG_BUFFERS: Configura SurfaceFlinger para que rastree todos los cambios de búfer en la superficie. De forma predeterminada, SurfaceFlinger rastrea un estado nuevo solo cuando se producen alteraciones de geometría.

• TRACE_FLAG_VIRTUAL_DISPLAYS: Incluye capas de visualización virtuales en el seguimiento.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento de SurfaceFlinger para 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

Consulta SurfaceFlinger para obtener detalles sobre el significado de los diferentes valores de configuración.

Transiciones de Shell

Usa el nombre de la fuente de datos com.android.wm.shell.transition para este tipo de registro.

Opciones de configuración

Este tipo de registro no tiene opciones de configuración.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento de transición de shell para 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 (transacciones)

Usa el nombre de la fuente de datos android.surfaceflinger.transactions para este tipo de seguimiento.

Opciones de configuración

Modo de registro (mode): Define la frecuencia con la que se registran los elementos:

• MODE_CONTINUOUS: SurfaceFlinger escribe su búfer circular interno de transacciones cada vez que se borra la fuente de datos. El búfer circular contiene el estado inicial de SurfaceFlinger y las transacciones más recientes.

• MODE_ACTIVE: SurfaceFlinger escribe el estado inicial y, luego, cada transacción entrante hasta que se detiene la fuente de datos.

Ejemplo

El siguiente es un ejemplo del tipo de registro de transacciones de SurfaceFlinger para 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

Usa el nombre de la fuente de datos: android.inputmethod para este tipo de registro.

Opciones de configuración

Este tipo de registro no tiene opciones de configuración.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento del IME para 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

Usa el nombre de la fuente de datos android.viewcapture para este tipo de registro.

Opciones de configuración

Este tipo de registro no tiene opciones de configuración.

Ejemplo

El siguiente es un ejemplo del tipo de seguimiento de ViewCapture para 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

Ejemplo completo

Perfetto te permite recopilar datos de varias fuentes en una sola configuración. Puedes recopilar todos los seguimientos de Winscope con un solo comando:

$ 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

Cómo capturar seguimientos en Android 14 y versiones anteriores

Ejecuta adb root antes de ejecutar los comandos adb shell para cada uno de los siguientes seguimientos. Al final del registro, los archivos de registro están disponibles en /data/misc/wmtrace. Para copiar un archivo o directorio y sus subdirectorios desde un dispositivo, consulta Cómo copiar archivos desde y hacia un dispositivo.

Seguimientos de WindowManager

Para capturar seguimientos de WindowManager, haz lo siguiente:

• Habilita el seguimiento:

  adb shell wm tracing start
  

• Inhabilita el seguimiento:

  adb shell wm tracing stop
  

• Guarda los datos de registro en un archivo mientras ejecutas una captura de registro:

  adb shell wm tracing save-for-bugreport
  

• Registra el seguimiento una vez por fotograma:

  adb shell wm tracing frame
  

• Registra cada transacción:

  adb shell wm tracing transaction
  

• Establece el tamaño máximo del registro (en KB):

  adb shell wm tracing size
  

• Imprimir el estado del seguimiento:

  adb shell wm tracing status
  

• Establece el nivel de registro en critical (solo ventanas visibles con información reducida), trim (todas las ventanas con información reducida) o all (todas las ventanas y la información):

  adb shell wm tracing level
  

Volcados de WindowManager

Para capturar volcados de WindowManager, haz lo siguiente:

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

ProtoLog

Los siguientes comandos se usan para el sistema ProtoLog.

En el proceso system_server, sucede lo siguiente:

• Inicia ProtoLog:

  adb shell cmd window logging start
  

• Detener ProtoLog:

  adb shell cmd window logging stop
  

• Habilita ProtoLog para grupos de registros determinados:

  adb shell cmd window logging enable [group...]
  

• Inhabilita ProtoLog para grupos de registros determinados:

  adb shell cmd window logging disable [group...]
  

• Habilita el registro de Logcat para grupos de registros determinados:

  adb shell cmd window logging enable-text [group...]
  

• Inhabilita el registro de Logcat para grupos de registros determinados:

  adb shell cmd window logging disable-text [group...]
  

En WMShell:

• Inicia ProtoLog:

  adb shell dumpsys activity service SystemUIService WMShell
  

Seguimientos (capas) de SurfaceFlinger

El registro de capas de SurfaceFlinger usa el registro de Perfetto para la captura. Consulta Configuración de seguimiento para obtener información sobre la configuración.

Consulta el siguiente ejemplo de una configuración para el seguimiento de capas de SurfaceFlinger:

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
        }
    }
}

Consulta el siguiente comando de ejemplo para generar un registro de las capas de SurfaceFlinger:

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

volcados de SurfaceFlinger (capas)

Para capturar volcados de SurfaceFlinger, haz lo siguiente:

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

Transiciones de Shell

Los siguientes comandos se usan para el seguimiento de transiciones.

En el proceso system_server, sucede lo siguiente:

• Inicia un registro:

  adb shell cmd window shell tracing start
  

• Sigue estos pasos para detener un seguimiento:

  adb shell cmd window shell tracing stop
  

• Inicia un registro en WMShell:

  adb shell dumpsys activity service SystemUIService WMShell transitions tracing start
  

• Detén un registro en WMShell:

  adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop
  

IME

Los siguientes comandos se usan para el seguimiento del editor de métodos de entrada (IME):

• Inicia el seguimiento de IME para los clientes de método de entrada (IM), el servicio de método de entrada (IMS) y el servicio de administración de métodos de entrada (IMMS):

  adb shell ime tracing start
  

• Inicia el seguimiento de clientes de IME, IMS y IMMS:

  adb shell ime tracing stop
  

SurfaceFlinger (transacciones)

El registro de transacciones de SurfaceFlinger usa el registro de Perfetto para la captura. Consulta Configuración de seguimiento para obtener información sobre la configuración.

Consulta el siguiente ejemplo de una configuración de Perfetto para el registro activo de SurfaceFlinger:

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

Consulta el siguiente ejemplo de una configuración de Perfetto para el seguimiento continuo de SurfaceFlinger:

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
        }
    }
}

Consulta el siguiente comando de ejemplo para generar un registro de transacciones de SurfaceFlinger:

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \