Ferramenta de linha de comando Logcat

O Logcat é uma ferramenta de linha de comando que despeja um registro de mensagens do sistema, incluindo mensagens que você escreveu no app com a classe Log.

Esta página aborda a ferramenta de linha de comando logcat, mas você também pode acessar as mensagens de registro da janela Logcat no Android Studio. Para mais informações sobre como acessar e filtrar registros do Android Studio, consulte Gravar e visualizar registros com o Logcat.

Visão geral do sistema de registro

O sistema de registro do Android é um conjunto de buffers circulares estruturados que é mantido pelo processo logd do sistema. O conjunto de buffers disponíveis é fixo e definido pelo sistema. Os buffers mais relevantes são estes:

main: armazena a maioria dos registros de apps.
system: armazena mensagens originadas do SO Android.
crash: armazena registros de falhas. Cada entrada de registro tem uma prioridade, uma tag que identifica a origem e a mensagem do registro.

A interface C/C++ principal do sistema de registro é a biblioteca compartilhada liblog e o cabeçalho <android/log.h>. Todas as dependências de registro específicas da linguagem, incluindo android.util.Log, chamam a função __android_log_write em algum momento. Por padrão, a função __android_log_logd_logger é chamada. Ela envia a entrada de registro para logd usando um soquete. No nível 30 da API e mais recentes, é possível mudar a função de registro chamando __android_set_log_writer. Saiba mais na documentação do NDK.

Os registros mostrados por adb logcat passam por quatro níveis de filtragem:

Filtrar durante a compilação: Dependendo das configurações de compilação, alguns registros podem ser removidos do binário. Por exemplo, o Proguard pode ser configurado para remover chamadas para o Log.d do código Java.
Filtrar propriedades do sistema: liblog consulta um conjunto de propriedades do sistema para determinar o nível mínimo de gravidade a ser enviado para logd. Se os registros tiverem a tag MyApp, as propriedades abaixo são verificadas e precisam conter a primeira letra da gravidade mínima (V, D, I, W, E ou S) para desativar todos os registros:
Filtrar aplicativos: Se nenhuma das propriedades estiver definida, liblog vai usar a prioridade mínima definida por __android_log_set_minimum_priority. A configuração padrão é INFO.
Filtrar quantos registros são mostrados: adb logcat oferece suporte a mais filtros que podem reduzir a quantidade de registros mostrados em logd. Consulte a seção sobre como filtrar a saída do registro para mais detalhes.

Sintaxe de linha de comando

Para executar o logcat pelo shell adb, o uso geral é este:

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

Há também uma abreviação de adb logcat, que se expande para adb shell logcat.

Opções

O logcat tem várias opções. As opções disponíveis dependem da versão do sistema operacional do dispositivo que você está usando. Para conferir a ajuda de logcat específica para o dispositivo que você está usando, execute:

    adb logcat --help

Como o logcat é uma ferramenta para desenvolvedores de apps e sistemas operacionais, sendo que os desenvolvedores de apps geralmente preferem o Android Studio, muitas das opções só podem ser usadas como root.

Filtrar a saída do registro

A tag de uma mensagem de registro é uma string curta que indica o componente do sistema do qual a mensagem é originada. Por exemplo, a tag "View" mostra que ela foi originada no sistema de visualização.

A prioridade é um destes valores de caractere, ordenados da prioridade mais baixa para a mais alta:

V: detalhada (prioridade mais baixa)
D: depuração
I: informação
W: aviso
E: erro
F: fatal
S: silenciosa (prioridade mais alta, em que nada é mostrado)

Para acessar uma lista das tags com prioridades usadas no sistema, execute logcat e observe as duas primeiras colunas de cada mensagem, apresentadas como <priority>/<tag>.

Confira abaixo um exemplo de saída breve do logcat gerado com o comando logcat -v brief output. A saída mostra que a mensagem está relacionada ao nível de prioridade "I" e à tag "ActivityManager":

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

Uma forma de reduzir a saída do registro a um nível gerenciável é restringi-la usando expressões de filtro. As expressões de filtro permitem indicar ao sistema as combinações de prioridade de tag do seu interesse. O sistema suprime outras mensagens para as tags especificadas.

Uma expressão de filtro segue este formato tag:priority ..., em que tag indica a tag de interesse e priority indica o nível de prioridade mínimo a ser relatado para essa tag. Mensagens para essa tag na prioridade especificada ou em prioridades mais altas são gravadas no registro. Forneça quantas especificações tag:priority quiser em uma única expressão de filtro. A série de especificações é delimitada por espaços em branco.

Confira abaixo um exemplo de uma expressão de filtro que suprime todas as mensagens de registro, exceto aquelas com a tag "ActivityManager" com o nível de prioridade de "Informação" ou mais alto e aquelas com a tag "MyApp" com prioridade de "Depuração" ou mais alto:

adb logcat ActivityManager:I MyApp:D *:S

O elemento final na expressão anterior, *:S, define o nível de prioridade de todas as tags como "silenciosa", o que garante que apenas mensagens de registro com as tags "ActivityManager" e "MyApp" sejam mostradas. O uso de *:S garante que a saída do registro seja restrita aos filtros especificados de forma explícita. *:S permite que seus filtros funcionem como uma lista de permissões para a saída de registro.

Observação: em alguns shells, o caractere "*" é reservado pelo shell. Se você está usando esse shell, coloque a expressão de filtro entre aspas: adb logcat "ActivityManager:I MyApp:D *:S"

A expressão de filtro abaixo mostra todas as mensagens de registro com o nível de prioridade “aviso” e mais altos em todas as tags:

adb logcat *:W

Se você está executando logcat no computador de desenvolvimento em vez de em um shell adb remoto, também poderá definir uma expressão de filtro padrão ao exportar um valor para a variável de ambiente ANDROID_LOG_TAGS:

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

O filtro ANDROID_LOG_TAGS não vai ser exportado para a instância do emulador ou dispositivo se você estiver executando logcat de um shell remoto ou usando adb shell logcat.

Controlar o formato de saída do registro

As mensagens de registro contêm alguns campos de metadados, além da tag e da prioridade. Você pode modificar o formato de saída das mensagens para que elas mostrem um campo de metadados específico. Para fazer isso, use a opção -v e especifique um destes formatos de saída com suporte:

brief: mostra a prioridade, a tag e o PID do processo que está emitindo a mensagem.
long: mostra todos os campos de metadados e mensagens separados por linhas em branco.
process: mostra apenas o PID.
raw: mostra a mensagem de registro bruta, sem outros campos de metadados.
tag: mostra apenas a prioridade e a tag.
thread:: um formato legado que mostra a prioridade, o PID e o TID da linha de execução emitindo a mensagem.
threadtime (padrão): mostra a data, o momento de invocação, a prioridade, a tag, o PID e o TID da linha de execução emitindo a mensagem.
time: mostra a data, o momento de invocação, a prioridade, a tag e o PID do processo emitindo a mensagem.

Ao iniciar o logcat, especifique o formato de saída que você quer com a opção -v:

[adb] logcat [-v <format>]

Confira um exemplo que mostra como gerar mensagens no formato de saída thread:

adb logcat -v thread

Só é possível especificar um formato de saída com a opção -v. No entanto, você pode especificar quantos modificadores quiser, desde que eles façam sentido. O logcat ignora os modificadores que não fazem sentido.

Modificadores de formato

Os modificadores de formato mudam a saída do logcat. Para especificar um modificador de formato, use a opção -v desta forma:

adb logcat -b all -v color -d

Cada mensagem do registro do Android é associada a uma tag e uma prioridade. Você pode combinar qualquer modificador de formato com qualquer uma destas opções:

brief
long
process
raw
tag
thread
threadtime
time

Para formatar os detalhes do modificador, insira logcat -v --help na linha de comando:

color: mostra cada nível de prioridade com uma cor diferente.
descriptive: mostra descrições de eventos do buffer de registro. Esse modificador afeta apenas as mensagens do buffer do log de eventos e não afeta os outros buffers não binários. As descrições de eventos são provenientes do banco de dados do log de eventos.
epoch: mostra o tempo em segundos a partir de 1º de janeiro de 1970.
monotonic: mostra o tempo em segundos da CPU a partir da última inicialização.
printable: garante que qualquer conteúdo de registro binário seja evitado.
uid: se permitido pelos controles de acesso, mostra o UID ou o ID do Android do processo registrado.
usec: mostra a hora com precisão em microssegundos.
UTC: mostra o horário como UTC.
year: adiciona o ano ao horário mostrado.
zone: adiciona o fuso horário local ao horário mostrado.

Acessar buffers de registro alternativos

O sistema de registro do Android mantém vários buffers para mensagens de registro, e nem todas são enviadas para o buffer circular padrão. Para acessar outras mensagens de registro, você pode executar o comando logcat com a opção -b para solicitar a visualização de um buffer circular alternativo. Você pode conferir qualquer um destes buffers alternativos:

radio: mostra o buffer que contém mensagens relacionadas a rádio e telefonia.
events: mostra as mensagens interpretadas do buffer de evento do sistema binário.
main: mostra o buffer de registro principal (padrão), que não contém mensagens de registro do sistema e de falhas.
system: mostra o buffer de registro do sistema (padrão).
crash: mostra o buffer de registro de falhas (padrão).
all: mostra todos os buffers.
default: relata buffers main, system e crash.

O uso da opção -b é o seguinte:

[adb] logcat [-b <buffer>]

Este é um exemplo de como acessar um buffer de registro que contém mensagens de rádio e telefonia:

adb logcat -b radio

Para especificar várias sinalizações -b para todos os buffers que você quer mostrar, insira o seguinte:

logcat -b main -b radio -b events

Especifique uma única sinalização -b com uma lista de buffers separada por vírgulas, por exemplo:

logcat -b main,radio,events

Criar registros no código

A classe Log permite criar entradas de registro no seu código que aparecem na ferramenta logcat. Métodos de registro comuns incluem:

Log.v(String, String) (detalhado)
Log.d(String, String) (depuração)
Log.i(String, String) (informações)
Log.w(String, String) (aviso)
Log.e(String, String) (erro)

Por exemplo, quando você usa esta chamada:

Kotlin

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

Java

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

A saída do logcat é parecida com:

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