Ferramenta de linha de comando Logcat

O Logcat é uma ferramenta de linha de comando que despeja um registro de mensagens do sistema, incluindo stack traces, quando o dispositivo gera um erro e mensagens que você escreveu no app com a classe Log.

O assunto desta página é a ferramenta de linha de comando Logcat, mas você pode ver as mensagens de registro da janela Logcat no Android Studio. Para saber como ver 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 mais relevantes são: main, que armazena a maioria dos registros de aplicativos, system, que armazena mensagens originadas do SO Android e crash, que armazena registros de falhas. Cada entrada de registro tem uma prioridade (que pode ser VERBOSE, DEBUG, INFO, WARNING, ERROR ou FATAL), uma tag que identifica a origem do registro e a mensagem de registro em si.

A interface 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 chamam a função __android_log_write. Por padrão, a função __android_log_logd_logger é chamada. Ela envia a entrada de registro para logd usando um soquete. A partir da API de nível 30, a função de registro pode ser mudada chamando __android_set_log_writer. Mais informações estão disponíveis na documentação do NDK.

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

  1. Filtragem no tempo de compilação: dependendo das configurações de compilação, alguns registros podem ser removidos completamente do binário. Por exemplo, o Proguard pode ser configurado para remover chamadas para Log.d do código Java.
  2. Filtragem de 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 têm a tag MyApp, as propriedades a seguir 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):
    • log.tag.MyApp
    • persist.log.tag.MyApp
    • log.tag
    • persist.log.tag
  3. Filtragem de aplicativos: se nenhuma das propriedades for definida, liblog usará a prioridade mínima configurada por __android_log_set_minimum_priority. A configuração padrão é INFO.
  4. Filtragem de exibição: adb logcat é compatível com filtros extras que podem reduzir a quantidade de registros mostrados em logd. Veja os detalhes abaixo.

Sintaxe de linha de comando

Para executar o Logcat pelo shell adb, o uso geral é o seguinte: 

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

Você pode executar logcat como um comando adb ou diretamente em uma solicitação de shell do seu emulador ou dispositivo conectado. Para ver a saída do registro usando adb, vá até o diretório platform-tools/ do SDK e execute:

adb logcat

Para receber ajuda on-line do logcat, inicie o dispositivo e execute: 

adb logcat --help

Você pode criar uma conexão de shell para um dispositivo e executar:

$ adb shell
# logcat

Opções

A tabela a seguir descreve as opções de linha de comando do logcat.

Opção Descrição
-b <buffer> Carrega um buffer de registro alternativo para visualização, como events ou radio. O conjunto de buffers main, system e crash é usado por padrão. Consulte Como visualizar buffers de registro alternativos.
-c, --clear Apaga (descarta) os buffers selecionados e sai. O conjunto de buffers padrão é main, system e crash. Para limpar todos os buffers, use -b all -c.
-e <expr>, --regex=<expr> Exibe apenas linhas em que a mensagem de registro corresponde a <expr>, em que <expr> é uma expressão regular.
-m <count>, --max-count=<count> Sai após exibir um número de <count> linhas. Isso é destinado ao pareamento com --regex, mas funcionará por conta própria.
--print Pareado com --regex e --max-count para permitir que o conteúdo ignore o filtro regex, mas ainda pare no número correto de correspondências.
-d Despeja o registro na tela e sai.
-f <filename> Grava a saída da mensagem de registro em <filename>. O padrão é stdout.
-g, --buffer-size Exibe o tamanho do buffer do registro especificado e sai.
-n <count> Define o número máximo de registros rotacionados para <count>. O valor padrão é 4. Exige a opção -r.
-r <kbytes> Rotaciona o arquivo de registros a cada <kbytes> de saída. O valor padrão é 16. Exige a opção -f.
-s Equivalente à expressão de filtro '*:S', que define a prioridade de todas as tags como silenciosa e é usado para preceder uma lista de expressões de filtro que adicionam conteúdo. Para saber mais, vá para a seção Como filtrar a saída do registro.
-v <format> Define o formato de saída das mensagens de registro. O padrão é o formato threadtime. Para ver uma lista de formatos compatíveis, vá para a seção sobre o formato de saída do registro de controle.
-D, --dividers Exibe divisores entre cada buffer de registro.
-c Descarta (apaga) todo o registro e sai.
-t <count> Exibe apenas o número mais recente de linhas. Essa opção inclui a funcionalidade -d.
-t '<time>' Exibe as linhas mais recentes desde o período especificado. Essa opção inclui a funcionalidade -d. Consulte a opção -P para ver informações sobre como citar parâmetros com espaços incorporados. 

adb logcat -t '01-26 20:52:41.820'
-T <count> Exibe o número mais recente de linhas desde o período especificado. Essa opção não inclui a funcionalidade -d.
-T '<time>' Exibe as linhas mais recentes desde o período especificado. Essa opção não inclui a funcionalidade -d. Consulte a opção -P para ver informações sobre como citar parâmetros com espaços incorporados. 

adb logcat -t '01-26 20:52:41.820'
-L, --last Despeja os registros antes da última reinicialização.
-B, --binary Saída do registro em binário.
-S, --statistics Inclui estatísticas na saída para ajudar você a identificar e segmentar criadores de spams de registro.
-G <size> Define o tamanho do buffer do anel de registro. Pode adicionar K ou M ao final para indicar kilobytes ou megabytes.
-p, --prune Exibe (lê) a lista de permissões e a lista de bloqueio e não aceita argumentos, da seguinte maneira: 

adb logcat -p
-P '<list> ...'
--prune '<list> ...' -P '<allowlist_and_denylist>' 		Grava (define) a lista de permissões e a lista de bloqueio para ajustar o conteúdo da geração de registros para uma finalidade específica. Você fornece um conteúdo misto de entradas de lista permitidas e negadas, em que <allowlist> ou <denylist> podem ser um UID, UID/PID ou PID. Com a orientação das estatísticas do Logcat (logcat -S), é possível considerar ajustes nas listas de permissões e de bloqueio para finalidades como:
  • Dar a maior longevidade ao conteúdo de geração de registros específico por meio das seleções de UID.
  • Evitar que alguém (UID) ou algo (PID) consuma esses recursos para ajudar a aumentar o logspan para que você tenha mais visibilidade dos problemas que está diagnosticando.

Por padrão, o sistema de geração de registros impede automaticamente o pior infrator nas estatísticas de registro de maneira dinâmica para liberar espaço para novas mensagens de registro. Depois de esgotar a heurística, o sistema remove as entradas mais antigas para liberar espaço para novas mensagens.

A adição de uma lista de permissões impede que seu número de identificação do Android (AID, na sigla em inglês), que se torna o AID e GID dos processos, seja declarado como um infrator. Além disso, a adição de uma lista de bloqueio ajuda a liberar espaço antes que os piores infratores sejam considerados. Você pode escolher o grau de liberação de espaço e pode desativar o processo para remover apenas o conteúdo das entradas mais antigas em cada buffer de registro.

Aspas

adb logcat não preserva as aspas, de modo que a sintaxe para especificar as listas de permissões e bloqueio é a seguinte: 


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

or

adb shell
$ logcat -P '<allowlist_and_denylist>'

O exemplo a seguir especifica uma lista de permissões com PID 32676 e UID 675 e uma lista de bloqueio com PID 32677 e UID 897. O PID 32677 na lista de bloqueio é ponderado para uma remoção mais rápida. 


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

Outras variações de comando de lista de permissões e de bloqueio que podem ser usadas são as seguintes: 


~! worst uid denylist
~1000/! worst pid in system (1000)
--pid=<pid> ... Apenas imprime registros do PID fornecido.
--wrap Suspensão de 2 horas ou quando o buffer estiver prestes a encerrar, o que ocorrer primeiro. Melhora a eficiência da pesquisa ao fornecer uma ativação prestes a encerrar.

Como filtrar a saída do registro

  • A tag de uma mensagem de registro é uma string curta que indica o componente do sistema por meio do qual a mensagem é originada (por exemplo, “View” para o sistema de visualização).
  • A prioridade é um dos seguintes 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 é exibido)

Você pode ver uma lista de tags usadas no sistema, com suas prioridades, executando o logcat e observando as duas primeiras colunas de cada mensagem, apresentadas como <priority>/<tag>.

Veja a seguir um exemplo de saída breve de logcat exibida com o comando logcat -v brief output. Ele 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...}

Para reduzir a saída do registro a um nível mais razoável, você pode restringi-la usando expressões de filtro. Expressões de filtro permitem indicar ao sistema as combinações de tag e prioridade do seu interesse para ele suprimir outras mensagens para as tags especificadas.

Uma expressão de filtro segue esse 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 superiores são gravadas no registro. Você pode fornecer quantas especificações de tag:priority quiser em uma única expressão de filtro. A série de especificações é delimitada por espaços em branco.

Aqui está um exemplo de uma expressão de filtro que suprime todas as mensagens de registro, exceto aquelas com a tag "ActivityManager", com prioridade "Informação" ou superior, e todas as mensagens de registro com tag "MyApp", com prioridade "Depuração" ou superior:

adb logcat ActivityManager:I MyApp:D *:S

O elemento final na expressão acima, *:S, define o nível de prioridade de todas as tags como "silencioso", garantindo que apenas as mensagens de registro com "ActivityManager" e "MyApp" sejam exibidas. Usar *:S é uma forma excelente de garantir que a saída do registro seja restrita aos filtros especificados explicitamente, permitindo que seus filtros funcionem como uma lista de permissões para saída de registro.

A expressão de filtro a seguir exibe todas as mensagens de registro com o nível de prioridade “aviso” e superior, em todas as tags:

adb logcat *:W

Se você estiver executando o Logcat no seu computador de desenvolvimento (e não 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 será exportado para a instância do emulador/dispositivo se você estiver executando o logcat em um shell remoto ou usando adb shell logcat.

Formato de saída do registro de controle

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 exibam um campo de metadados específico. Para isso, use a opção -v e especifique um dos formatos de saída compatíveis listados abaixo.

  • brief: exibe a prioridade, a tag e o PID do processo que está emitindo a mensagem.
  • long: exibe todos os campos de metadados e mensagens separadas com linhas em branco.
  • process: exibe apenas o PID.
  • raw: exibe a mensagem de registro bruta, sem outros campos de metadados.
  • tag: exibe somente 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): exibe 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: exibe a data, o momento de invocação, a prioridade, a tag e o PID do processo emitindo a mensagem.

Ao iniciar o logcat, você pode especificar o formato de saída desejado usando a opção -v:

[adb] logcat [-v <format>]

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

adb logcat -v thread

Você só pode especificar um formato de saída com a opção -v, mas pode especificar o número de modificadores que fizer sentido. O Logcat ignora modificadores que não fazem sentido.

Modificadores de formato

Modificadores de formato mudam a saída do Logcat em termos de qualquer combinação de um ou mais dos seguintes modificadores. Para especificar um modificador de formato, use a opção -v da seguinte maneira: 

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 das seguintes opções de formato: brief, long, process, raw, tag, thread, threadtime e time.

É possível ver os detalhes do modificador de formato digitando 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 de log de eventos.
  • epoch: exibe o tempo em segundos a partir de 1º de janeiro de 1970.
  • monotonic: exibe 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, exibe o UID ou o ID do Android do processo registrado.
  • usec: exibe a hora com precisão de microssegundos.
  • UTC: tempo de exibição como UTC.
  • year: adiciona o ano ao horário exibido.
  • zone: adiciona o fuso horário local ao horário exibido.

Como ver buffers de registro alternativos

O sistema de registro do Android mantém vários buffers para mensagens de registro, e nem todas as mensagens de registro são enviadas para o buffer circular padrão. Para ver 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 ver qualquer um dos seguintes buffers alternativos:

  • radio: exibe o buffer que contém mensagens relacionadas a rádio e telefonia.
  • events: exibe as mensagens interpretadas do buffer de evento do sistema binário.
  • main: exibe o buffer de registro principal (padrão). Não contém mensagens de registro do sistema e de falhas.
  • system: exibe o buffer de registro do sistema (padrão).
  • crash: exibe o buffer do registro de falhas (padrão).
  • all: exibe 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 ver um buffer de registro que contém mensagens de rádio e telefonia: 

adb logcat -b radio

Também é possível especificar várias sinalizações -b para todos os buffers que você quiser exibir, da seguinte maneira: 

logcat -b main -b radio -b events

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

logcat -b main,radio,events

Como criar registros a partir do código

A classe Log permite a criação de entradas de registro no seu código que são exibidas na ferramenta logcat. Métodos de registro em log comuns incluem:

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 é semelhante a:

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