Herramienta de línea de comandos logcat

Logcat es una herramienta de línea de comandos que vuelca un registro de mensajes del sistema, incluidos los seguimientos de pila, los casos de error del sistema y los mensajes que escribas desde tu app con la clase Log.

En esta página se explica la herramienta de línea de comandos logcat, pero también puedes ver mensajes de registro desde la ventana Logcat en Android Studio. Para obtener información acerca de cómo visualizar y filtrar registros desde Android Studio, consulta Cómo escribir y ver registros con Logcat.

Sintaxis de la línea de comandos

Para ejecutar logcat a través del shell de ADB, el uso general es el siguiente:

    [adb] logcat [<option>] ... [<filter-spec>] ...
    

Puedes ejecutar logcat como comando de ADB o directamente en una solicitud de shell de tu emulador o dispositivo conectado. Para ver resultados de registro mediante ADB, dirígete al directorio platform-tools/ de tu SDK y ejecuta lo siguiente:

    adb logcat
    

Para obtener ayuda en línea de logcat, inicia un dispositivo y luego ejecuta lo siguiente:

    adb logcat --help
    

Puedes crear una conexión de shell con un dispositivo y ejecutar lo siguiente:

    $ adb shell
    # logcat
    

Opciones

En la tabla siguiente se describen las opciones de línea de comandos de logcat.

Opción Descripción
-b <buffer> Carga o alterna búferes de registro para visualización, como events o radio. El conjunto de búferes main, system y crash se utiliza de forma predeterminada. Consulta Cómo ver búferes de registro alternativos.
-c, --clear Borra (vacía) los búferes seleccionados y finaliza. El conjunto de búferes predeterminado es main, system y crash. Para borrar todos los búferes, usa -b all -c.
-e <expr>, --regex=<expr> Solo imprime líneas en las que el mensaje de registro coincide con <expr> donde <expr> es una expresión regular.
-m <count>, --max-count=<count> Finaliza después de imprimir <count> líneas. Esto está destinado a vincularse con --regex, pero funcionará por su cuenta.
--print Se vincula con --regex y --max-count para permitir que el contenido omita el filtro de expresiones regulares, pero igual se detiene en el número correcto de coincidencias.
-d Vuelca el registro en la pantalla y finaliza.
-f <filename> Escribe el resultado del mensaje de registro en <filename>. El valor predeterminado es stdout.
-g, --buffer-size Imprime el tamaño del búfer del registro especificado y finaliza.
-n <count> Establece la cantidad máxima de registros rotados en <count>. El valor predeterminado es 4. Requiere la opción -r.
-r <kbytes> Rota el archivo de registro cada <kbytes> de resultado. El valor predeterminado es 16. Requiere la opción -f.
-s Equivale al filterspec '*:S' y se usa para preceder a una lista de filterspecs que agregan contenido.
-v <format> Fija el formato de salida para los mensajes del registro. El valor predeterminado es el formato threadtime. Para obtener una lista de los formatos admitidos, consulta Cómo controlar el formato de los resultados de los registros.
-D, --dividers Imprime divisores entre cada búfer de registro.
-c Vacía (borra) todo el registro y finaliza.
-t <count> Imprime solo la cantidad de líneas más reciente. Esta opción incluye la funcionalidad -d.
-t '<time>' Imprime las líneas más recientes desde el tiempo especificado. Esta opción incluye la funcionalidad -d. Consulta la opción -P para obtener información sobre los parámetros de comillas con espacios incrustados.

adb logcat -t '01-26 20:52:41.820'
-T <count> Imprime el número más reciente de líneas desde el tiempo especificado. Esta opción no incluye la funcionalidad -d.
-T '<time>' Imprime las líneas más recientes desde el tiempo especificado. Esta opción no incluye la funcionalidad de inclusión -d. Consulta la opción -P para obtener información sobre los parámetros de comillas con espacios incrustados.

adb logcat -t '01-26 20:52:41.820'
-L, -last Vuelca los registros anteriores al último reinicio.
-B, --binary Muestra el resultado del registro en objetos binarios.
-S, --statistics Incluye estadísticas en el resultado para ayudarte a identificar y dirigirte a los generadores de spam de registros.
-G <size> Establece el tamaño del búfer de anillo de registro. Puede agregar K o M al final para indicar los kilobytes o megabytes.
-p, --prune Imprime (lee) las listas blancas y negras actuales y no toma argumentos, de la siguiente manera:

    adb logcat -p
    
-P '<list> ...'
--prune '<list> ...' -P '<white_and_black_list>'
Escribe (configura) las listas blanca y negra para modificar el contenido de registro para un propósito específico. Proporcionas un contenido mixto de las entradas de las listas <white> y ~<black>, donde <white> o <black> pueden ser un UID, UID/PID o /PID. Con la guía de las estadísticas de logcat (logcat -S), se pueden considerar ajustes a las listas blancas y negras para fines como los siguientes:
  • Ofrecer la mayor longevidad a contenido de registro específico por medio de selecciones de UID
  • Incluir en la lista negra quién (UID) o qué (PID) consume estos recursos para ayudar a aumentar el intervalo de registro para que puedas tener más visibilidad de los problemas que estás diagnosticando

De forma predeterminada, el sistema de registro incluye de manera automática en una lista negra la peor fuente de error en las estadísticas de registro dinámicamente para dejar espacio para mensajes de registro nuevos. Una vez que agotó las heurísticas, el sistema elimina las entradas más antiguas a fin de dejar espacio para los mensajes nuevos.

Agregar una lista blanca brinda protección al número de identificación de Android (AID) (que se convierte en el AID y GID de los procesos) para que no sea identificado como una fuente de error, y agregar una lista negra ayuda a liberar espacio antes de evaluar las peores fuentes de error. Puedes elegir qué tan activa es la eliminación y puedes desactivarla para que solo borre contenido de las entradas más antiguas en cada búfer de registro.

Comillas

adb logcat no conserva las comillas. Por eso, la sintaxis para especificar listas blancas y negras es la siguiente:


    $ adb logcat -P '"<white_and_blacklist>"'

    or

    adb shell
    $ logcat -P '<white_and_blacklist>'
    

En el siguiente ejemplo, se especifica una lista blanca con PID 32676 y UID 675, y una lista negra con PID 32677 y UID 897. El PID 32677 en la lista negra está ponderado para acelerar el proceso de eliminación.


    adb logcat -P '"/32676 675 ~/32677 897"'
    

A continuación, se incluyen otras variaciones del comando de las listas blanca y negra que puedes usar:


    ~! worst uid blacklist
    ~1000/! worst pid in system (1000)
    
--pid=<pid> ... Solo imprime registros desde el PID dado.
--wrap Se suspende durante 2 horas o cuando el búfer está a punto de ajustarse (lo que ocurra primero). Mejora la eficiencia del sondeo al proporcionar una activación para el momento en que está por ajustarse.

Cómo filtrar resultados de registros

  • La etiqueta de un mensaje de registro es una string corta que indica el componente del sistema donde se origina el mensaje (por ejemplo, “view” para el sistema de vista).
  • La prioridad es uno de los siguientes valores de caracteres ordenados de la prioridad más baja a la más alta:
    • V: Verbose (prioridad más baja)
    • D: Depuración
    • I: Información
    • W: Advertencia
    • E: Error
    • F: Fatal
    • S: Silencio (prioridad más alta en la que nunca se imprime nada)

Puedes obtener una lista de las etiquetas que se usan en el sistema, junto con las prioridades, ejecutando logcat y observando las dos primeras columnas de cada mensaje, indicadas como <priority>/<tag>.

El siguiente es un ejemplo de un resultado breve de logcat obtenido con el comando logcat -v brief output. Muestra que el mensaje está relacionado con el nivel de prioridad "I" y la etiqueta "ActivityManager":

    I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}
    

Para reducir los resultados del registro a un nivel fácil de manejar, puedes restringir los resultados del registro usando expresiones de filtro. Las expresiones de filtro te permiten indicar al sistema las combinaciones de etiqueta y prioridad que te interesan; el sistema omite otros mensajes para las etiquetas especificadas.

Una expresión de filtro tiene este formato tag:priority ..., en el que tag indica la etiqueta de interés y priority indica el nivel de prioridad mínimo que se debe informar para esa etiqueta. Los mensajes para esa etiqueta que posean el nivel de prioridad especificado o un nivel superior se escriben en el registro. Puedes proporcionar cualquier cantidad de especificaciones tag:priority en una sola expresión de filtro. Las series de especificaciones están delimitadas por espacios en blanco.

A continuación, te mostramos un ejemplo de una expresión de filtro que suprime todos los mensajes del registro excepto los que tienen la etiqueta “ActivityManager”, con prioridad “Info” o más alta, y todos los mensajes del registro con la etiqueta “MyApp” y la prioridad “Debug” o más alta:

    adb logcat ActivityManager:I MyApp:D *:S
    

El elemento final en la expresión anterior, *:S, fija el nivel de prioridad para todas las etiquetas en “silent”, lo cual garantiza que solo se muestren los mensajes del registro con “ActivityManager” y “MyApp”. Usar *:S es una excelente manera de garantizar que los resultados del registro se limiten a los filtros que especificaste explícitamente; permite que tus filtros sirvan como una “lista blanca” para los resultados del registro.

La siguiente expresión de filtro muestra todos los mensajes del registro con nivel de prioridad “warning” o superior en todas las etiquetas:

    adb logcat *:W
    

Si ejecutas logcat desde tu computadora de desarrollo (en lugar de ejecutarlo en un shell de ADB remoto), también puedes establecer una expresión de filtro predeterminada exportando un valor para la variable de entorno ANDROID_LOG_TAGS:

    export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
    

Ten en cuenta que el filtro ANDROID_LOG_TAGS no se exporta a la instancia del emulador o dispositivo si ejecutas logcat desde un shell remoto o con adb shell logcat.

Cómo controlar el formato de los resultados de los registros

Los mensajes de registro contienen varios campos de metadatos además de la etiqueta y la prioridad. Puedes modificar el formato de salida para los mensajes de modo que muestren un campo de metadatos específico. Para hacerlo, usa la opción -v y especifica uno de los formatos de salida admitidos que se indican a continuación.

  • brief: Muestra la prioridad, la etiqueta y el PID del proceso que emite el mensaje.
  • long: Muestra todos los campos de metadatos y mensajes separados por líneas en blanco.
  • process: Muestra el PID únicamente.
  • raw: Muestra el mensaje del registro sin formato y sin otros campos de metadatos.
  • tag: Muestra la prioridad y la etiqueta únicamente.
  • thread: Es un formato heredado que muestra la prioridad, el PID y el TID del subproceso que emite el mensaje.
  • threadtime (opción predeterminada): Muestra la fecha, la hora de invocación, la prioridad, la etiqueta, el PID y el TID del subproceso que emite el mensaje.
  • time: muestra la fecha, la hora de invocación, la prioridad y la etiqueta, y el PID del proceso que emite el mensaje.

Al iniciar logcat, puedes especificar el formato de salida que desees usando la opción -v:

    [adb] logcat [-v <format>]
    

A continuación, te mostramos un ejemplo de generación de mensajes con formato de salida thread:

    adb logcat -v thread
    

Ten en cuenta que solo puedes especificar un formato de salida con la opción -v, pero puedes especificar todos los modificadores que tengan sentido. Logcat ignora los modificadores que no tienen sentido.

Modificadores de formato

Los modificadores de formato cambian el resultado de logcat en términos de cualquier combinación de uno o más de los siguientes modificadores. Para especificar un modificador de formato, usa la opción -v de la siguiente manera:

    adb logcat -b all -v color -d
    

Todos los mensajes de registro de Android tienen una etiqueta y una prioridad asociadas a ellos. Puedes combinar cualquier modificador de formato con cualquiera de las siguientes opciones de formato: brief, long, process, raw, tag, thread, threadtime y time.

Puedes obtener los detalles del modificador de formato escribiendo logcat -v --help en la línea de comandos.

  • color: Muestra cada nivel de prioridad con un color diferente.
  • descriptive: Muestra descripciones de eventos de búferes de registro. Este modificador afecta solo a los mensajes del búfer del registro de eventos y no funciona con otros búferes no binarios. Las descripciones de eventos provienen de la base de datos de etiquetas de registro de eventos.
  • epoch: Muestra la hora en segundos a partir del 1 de enero de 1970.
  • monotonic: Muestra el tiempo en segundos de la CPU a partir del último inicio.
  • printable: Garantiza que se escape cualquier contenido de registro binario.
  • uid: Si los controles de acceso lo permiten, muestra el UID o ID de Android del proceso registrado.
  • usec: Muestra la hora con precisión hasta microsegundos.
  • UTC: Muestra la hora como UTC.
  • year: Agrega el año a la hora que se muestra.
  • zone: Agrega la zona horaria local a la hora mostrada.

Cómo ver búferes de registro alternativos

El sistema de registro Android mantiene varios búferes circulares para los mensajes de registro, y no todos los mensajes de registro se envían al búfer circular predeterminado. Para ver mensajes de registro adicionales, puedes ejecutar el comando logcat con la opción -b para solicitar la visualización de un búfer circular alternativo. Puedes ver cualquiera de los siguientes búferes alternativos:

  • radio: Muestra el búfer que contiene mensajes de radio y telefonía.
  • events: Muestra los mensajes del búfer de eventos del sistema binario interpretados.
  • main: Muestra que el búfer del registro principal (predeterminado) no incluye mensajes de registro del sistema y las fallas.
  • system: Muestra el búfer de registro del sistema (predeterminado).
  • crash: Muestra el búfer de registro de fallas (predeterminado).
  • all: Muestra todos los búferes.
  • default: Informa los búferes main, system y crash.

La utilidad de la opción -b es la siguiente:

    [adb] logcat [-b <buffer>]
    

A continuación, te mostramos un ejemplo de visualización de un búfer de registro que contiene mensajes de radio y telefonía:

    adb logcat -b radio
    

También puedes especificar varios indicadores -b para todos los búferes que deseas imprimir, de la siguiente manera:

    logcat -b main -b radio -b events
    

Puedes especificar un único indicador -v con una lista de búferes separados por comas, por ejemplo:

    logcat -v main,radio,events
    

Registro desde el código

La clase Log te permite crear en tu código entradas de registro que aparezcan en la herramienta logcat. Entre los métodos de registro comunes se incluyen los siguientes:

Por ejemplo, usando la siguiente llamada:

Kotlin

    Log.i("MyActivity", "MyClass.getView() — get item number $position")
    

Java

    Log.i("MyActivity", "MyClass.getView() — get item number " + position);
    

Los resultados de logcat se aproximan a los siguientes:

    I/MyActivity( 1557): MyClass.getView() — get item number 1