Herramienta de línea de comandos Logcat

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Logcat es una herramienta de línea de comandos que vuelca un registro de mensajes del sistema cuando el dispositivo muestra un error y envía mensajes que escribiste 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 en la ventana Logcat de Android Studio. Si quieres obtener información para ver y filtrar registros desde Android Studio, consulta Cómo ver y escribir registros con Logcat.

Descripción general del sistema de registro

El sistema de registro de Android es un conjunto de búferes circulares estructurados que mantiene el proceso del sistema logd. El sistema fija y define el conjunto de búferes disponibles. Los búferes más relevantes son los siguientes:

  • main: Almacena la mayoría de los registros de la aplicación.
  • system: Almacena mensajes que se originan en el SO Android.
  • crash: Almacena registros de fallas. Cada entrada de registro tiene una prioridad, una etiqueta que identifica el origen del registro y el mensaje de registro real.

La interfaz principal para el sistema de registro es la biblioteca compartida liblog y su encabezado <android/log.h>. Todas las utilidades de registro específicas de lenguaje finalmente llaman a la función __android_log_write. De forma predeterminada, llama a la función __android_log_logd_logger, que envía la entrada de registro a logd mediante un socket. A partir del nivel de API 30, se puede cambiar la función de registro llamando a __android_set_log_writer. Puedes encontrar más información en la documentación del NDK.

Los registros que muestra adb logcat se someten a cuatro niveles de filtrado:

Filtrado en tiempo de compilación
Según los parámetros de configuración de compilación, es posible que algunos registros se quiten por completo del objeto binario. Por ejemplo, se puede configurar ProGuard para quitar llamadas a Log.d del código Java.
Filtrado de propiedades del sistema
liblog consulta un conjunto de propiedades del sistema para determinar el nivel de gravedad mínimo que se enviará a logd. Si tus registros tienen la etiqueta MyApp, se verifican las propiedades indicadas a continuación, las cuales deberían contener la primera letra de la gravedad mínima (V, D, I, W, E o S para inhabilitar todos los registros):
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
Filtrado de aplicaciones
Si no se configura ninguna de las propiedades, liblog usa la prioridad mínima establecida por __android_log_set_minimum_priority. El parámetro de configuración predeterminado es INFO.
Filtrado de visualización
adb logcat admite filtros adicionales que pueden reducir la cantidad de registros que se muestran en logd. Consulta la sección para filtrar resultados de registros si quieres obtener más detalles.

Sintaxis de la línea de comandos

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

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

Puedes ejecutar logcat como un comando adb o directamente en una solicitud de shell en tu emulador o dispositivo conectado. Para ver resultados de registro mediante adb, navega al directorio platform-tools/ del 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

Crea una conexión de shell a un dispositivo y ejecuta 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 un búfer de registro alternativo para visualización, como events o radio. El conjunto de búferes main, system y crash se usa de forma predeterminada. Consulta la sección para ver búferes de registro alternativos.
-c, --clear Borra 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 Si se vincula con --regex y --max-count, el contenido puede omitir el filtro de regex, pero se detiene en el número correcto de coincidencias.
-d Vuelca el registro en la pantalla y finaliza.
-f <filename> Escribe el resultado de los mensajes del 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> Fija 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 producción. El valor predeterminado es 16. Requiere la opción -f.
-s Equivale a la expresión de filtro '*:S', que establece la prioridad para todas las etiquetas en "silent" y se usa a fin de preceder a una lista de expresiones de filtro que agregan contenido. Si quieres obtener más información, ve a la sección para filtrar resultados de registros.
-v <format> Fija el formato de salida para los mensajes del registro. El formato predeterminado es threadtime. Si quieres obtener una lista de los formatos admitidos, consulta la sección para controlar el formato de los resultados de los registros.
-D, --dividers Imprime divisores entre cada búfer de registro.
-c 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 incorporados.

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 -d. Consulta la opción -P para obtener información sobre los parámetros de comillas con espacios incorporados.

adb logcat -t '01-26 20:52:41.820'
-L, --last Vuelca los registros anteriores al último reinicio.
-B, --binary Muestra el registro en binario.
-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. Puedes agregar K o M al final para indicar los kilobytes o megabytes.
-p, --prune Imprime la lista de entidades permitidas y la lista de bloqueo, y no toma argumentos, de la siguiente manera:

adb logcat -p
-P '<list> ...'
--prune '<list> ...' -P '<allowlist_and_denylist>'
Escribe la lista de entidades permitidas y las listas de bloqueo a fin de ajustar el contenido de registro para un propósito específico. Proporcionas un contenido mixto de entradas de las fichas permitidas y rechazadas, en las que <allowlist> o <denylist> pueden ser UID, UID/PID o /PID. Con la guía de las estadísticas de logcat (logcat -S), se pueden considerar ajustes para la lista de entidades permitidas y las listas de bloqueo con fines como los siguientes:
  • Ofrecer la mayor longevidad a contenido de registro específico por medio de selecciones de UID
  • Impedir que alguien (UID) o algo (PID) consuma estos recursos a fin de ayudar a aumentar el intervalo de registro para que tengas más visibilidad de los problemas que estás diagnosticando

De forma predeterminada, el sistema de registro evita automáticamente 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.

Si agregas una lista de entidades permitidas, proteges tu número de identificación de Android (AID), que se convierte en el AID y GID de los procesos, para que no se identifique como una fuente de error. Si agregas una lista de bloqueo, ayudas 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 de entidades permitidas y listas de bloqueo es la siguiente:


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

or

adb shell
$ logcat -P '<allowlist_and_denylist>'

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


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

Puedes usar las siguientes variaciones de los comandos:


~! worst uid denylist
~1000/! worst pid in system (1000)
--pid=<pid> ... Solo imprime registros desde el PID dado.
--uid=<uids> ... Solo muestra los mensajes de registro de los UIDs presentes en la lista separada por comas <uids>. No se realiza la búsqueda de nombres, por lo que los UIDs se deben proporcionar como valores numéricos. Esta opción solo es útil para los usuarios "raíz", "registro" y "sistema", ya que solo ellos pueden ver los registros de otros usuarios.
--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 los resultados de los 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: Debug
    • I: Info
    • W: Warning
    • E: Error
    • F: Fatal
    • S: Silent (prioridad más alta en la que nunca se imprime nada)
  • Para obtener una lista de las etiquetas que se usan en el sistema con prioridades, ejecuta logcat y observa las dos primeras columnas de cada mensaje, indicadas como <priority>/<tag>.

    El siguiente es un ejemplo de un breve resultado de logcat obtenido con el comando logcat -v brief output. El resultado muestra que el mensaje se relaciona 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, restringe los resultados del registro usando expresiones de filtro. Las expresiones de filtro te permiten indicar al sistema las combinaciones de prioridad de etiqueta que te interesan. El sistema elimina 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. Proporciona 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, se muestra un ejemplo de una expresión de filtro que suprime todos los mensajes del registro, excepto aquellos con la etiqueta "ActivityManager" con prioridad "Info" o más alta y aquellos con la etiqueta "MyApp" con 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 de registro con "ActivityManager" y "MyApp". El uso de *:S garantiza que el resultado del registro se restrinja a los filtros que especificaste de forma explícita. *:S permite que tus filtros sirvan como una lista de entidades permitidas para el resultado del registro.

    Nota: En algunos shells, el shell se reserva el carácter "*". Si usas ese shell, encierra la expresión de filtro entre comillas: adb logcat "ActivityManager:I MyApp:D *:S".

    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 estás ejecutando logcat desde tu computadora de desarrollo en lugar de ejecutarla en un shell remoto adb también puedes establecer una expresión de filtro predeterminada si exportas un valor para la variable de entorno ANDROID_LOG_TAGS:

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

    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 ello, usa la opción -v y especifica uno de los siguientes formatos de salida admitidos:

    • 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 solo el PID.
    • 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.

    Cuando inicies logcat, especifica el formato de salida que quieras con 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
    

    Solo puedes especificar un formato de salida con la opción -v. Sin embargo, puedes especificar todos los modificadores que necesites, siempre que tengan sentido. logcat ignora los modificadores que no tienen sentido.

    Modificadores de formato

    Los modificadores de formato cambian el resultado de logcat. 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
    • time

    Para dar formato a los siguientes detalles del modificador, ingresa 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 en 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 que se muestra.

    Cómo ver los búferes de registro alternativos

    El sistema de registro de 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, ejecuta el comando logcat con la opción -b a fin de 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 el búfer de registro principal (predeterminado), que no contiene mensajes de registro de fallas ni del sistema.
    • 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: Muestra informes de 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
    

    A fin de especificar varias marcas -b para todos los búferes que deseas imprimir, ingresa lo siguiente:

    logcat -b main -b radio -b events
    

    Especifica una sola marca -b con una lista de búferes separados por comas, por ejemplo:

    logcat -b main,radio,events
    

    Registro desde el código

    La clase Log te permite crear entradas de registro en tu código que se muestran en la herramienta de 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);
    

    logcat genera un resultado similar al siguiente:

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