Cómo capturar registros con comandos adb

Los registros 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 registros 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 los parámetros de configuración de forma individual o en una sola sesión de registro.

En Android 14 y versiones anteriores, cada registro de Winscope tiene un comando diferente y puedes recopilarlos 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 máxima cantidad de información.
    • LOG_LEVEL_DEBUG: Registra todos los elementos, pero no escribe todos los datos de configuración.
    • LOG_LEVEL_CRITICAL: Registra solo los elementos visibles, con la menor sobrecarga de rendimiento posible.

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

    • LOG_FREQUENCY_FRAME: Registra instantáneas del estado cuando se confirma un fotograma.
    • LOG_FREQUENCY_TRANSACTION: Registra instantáneas del estado cada vez que se confirma una transacción.
    • LOG_FREQUENCY_SINGLE_DUMP: Realiza un seguimiento de las instantáneas de un solo estado cuando se inicia la fuente de datos.

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

Ejemplo

A continuación, se muestra un ejemplo del tipo de registro 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: Solo se registran los grupos y niveles de registro especificados en group_overrides.
  • ENABLE_ALL: Registra 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 configura, se realizará un seguimiento de cualquier mensaje con un nivel de registro superior o igual 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 los 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

Invalidaciones de grupos (group_overrides): Permite configurar manualmente el 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: Es 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 que se está rastreando.

Ejemplo

A continuación, se muestra 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 el seguimiento de entrada debe iniciarse con reglas que preservan la privacidad o 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 registro definidas en esta configuración para especificar qué eventos se deben registrar. Consulta android_input_event_config.proto para obtener más información sobre cómo especificar las reglas del registro.

Ejemplo

A continuación, se muestra un ejemplo del tipo de registro 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 seguimiento (mode): Define la frecuencia con la que se registran los elementos:

  • MODE_ACTIVE: Registra instantáneas de las 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 conservan en el búfer de anillo interno de SurfaceFlinger. La generación de instantáneas de la capa se produce cuando se vacía esta fuente de datos.
  • MODE_DUMP: Registra el seguimiento de una sola instantánea de capas.
  • 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 vacía un registro.

Marcas de seguimiento (trace_flags):

  • TRACE_FLAG_INPUT: Si la superficie contiene datos de entrada, hace un seguimiento de los detalles de la ventana de entrada.
  • TRACE_FLAG_COMPOSITION: Registra el tipo de composición y la región visible.

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

  • TRACE_FLAG_HWC: Registra metadatos adicionales no estructurados del compositor de hardware.

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

  • TRACE_FLAG_VIRTUAL_DISPLAYS: Incluye capas de pantalla virtual en el registro.

Ejemplo

A continuación, se muestra un ejemplo del tipo de registro 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

A continuación, se muestra un ejemplo del tipo de registro 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 registro.

Opciones de configuración

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

  • MODE_CONTINUOUS: SurfaceFlinger escribe su búfer de anillo interno de transacciones cada vez que se vacía la fuente de datos. El búfer de anillo 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

A continuación, se muestra 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

A continuación, se muestra un ejemplo del tipo de registro 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

A continuación, se muestra un ejemplo del tipo de registro 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 múltiples fuentes en una sola configuración. Puedes recopilar todos los registros 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 registros en Android 14 y versiones anteriores

Ejecuta adb root antes de ejecutar los comandos de adb shell para cada uno de los siguientes registros. 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 a un dispositivo y desde él.

Registros de WindowManager

Sigue estos pasos para capturar registros de WindowManager:

  • Habilita el registro:

    adb shell wm tracing start

  • Inhabilita el registro:

    adb shell wm tracing stop

  • Cómo guardar los datos de registro en un archivo mientras se ejecuta 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

  • Estado de impresión 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 de system_server, sucede lo siguiente:

  • Cómo iniciar ProtoLog:

    adb shell cmd window logging start

  • Detener ProtoLog:

    adb shell cmd window logging stop

  • Habilita ProtoLog para los grupos de registros determinados:

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

  • Inhabilita ProtoLog para los grupos de registros determinados:

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

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

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

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

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

En WMShell:

  • Cómo iniciar ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Registros de SurfaceFlinger (capas)

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

Consulta el siguiente ejemplo de una configuración para el registro 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 ejemplo de comando para generar un registro de las capas de SurfaceFlinger:

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

Volcado 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 registro de seguimiento de transiciones.

En el proceso de system_server, sucede lo siguiente:

  • Sigue estos pasos para iniciar un registro:

    adb shell cmd window shell tracing start

  • Sigue estos pasos para detener un registro:

    adb shell cmd window shell tracing stop

  • Inicia un registro en WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Para detener un registro en WMShell, haz lo siguiente:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

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

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

    adb shell ime tracing start

  • Inicia el registro de los clientes del 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 del registro 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 registro 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 \