Ferramenta de linha de comando Logcat

O Logcat é uma ferramenta de linha de comando que despeja um registro de mensagens do sistema quando o dispositivo gera um erro e envia as mensagens que você escreveu no app usando 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 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 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:
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
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] logcat [<option>] ... [<filter-spec>] ...

Você pode executar logcat como um comando adb ou um prompt do shell no seu emulador ou dispositivo conectado. Para conferir 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

Crie uma conexão com o shell em um dispositivo e execute:

$ adb shell
# logcat

Opções

A tabela abaixo 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 a seção sobre como ver buffers de registro alternativos.
-c, --clear Limpa os buffers e as saídas selecionados. O conjunto de buffers padrão é main, system e crash. Para limpar todos os buffers, use -b all -c.
-e <expr>, --regex=<expr> Mostra 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 mostrar o número <count> de linhas. Isso é destinado ao pareamento com --regex, mas funcionará por conta própria.
--print Quando pareado com --regex e --max-count, permite que o conteúdo ignore o filtro regex, mas ainda pare no número correto de correspondências.
-d Mostra 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 Mostra 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, consulte 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 uma lista de formatos com suporte, consulte a seção sobre como controlar o formato de saída do registro.
-D, --dividers Mostra divisores entre cada buffer de registro.
-c Limpa todo o registro e sai.
-t <count> Mostra apenas o número mais recente de linhas. Essa opção inclui a funcionalidade -d.
-t '<time>' Mostra as linhas mais recentes desde o período especificado. Essa opção inclui a funcionalidade -d. Consulte a opção -P para informações sobre como citar parâmetros com espaços incorporados.

adb logcat -t '01-26 20:52:41.820'
-T <count> Mostra o número mais recente de linhas desde o período especificado. Essa opção não inclui a funcionalidade -d.
-T '<time>' Mostra as linhas mais recentes desde o período especificado. Essa opção não inclui a funcionalidade -d. Consulte a opção -P para 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 Gera os registros em binário.
-S, --statistics Inclui estatísticas na saída para ajudar a identificar e segmentar criadores de spams de registros.
-G <size> Define o tamanho do buffer do anel de registro. Você pode adicionar K ou M no final para indicar o tamanho em kilobytes ou megabytes.
-p, --prune Mostra a lista de permissões e de bloqueio, e não aceita argumentos, usado desta maneira:

adb logcat -p
-P '<list> ...'
--prune '<list> ...' -P '<allowlist_and_denylist>'
Grava a lista de permissões e de bloqueio para ajustar o conteúdo dos registros gerados para uma finalidade específica. Você fornece um conteúdo misto de entradas de lista permitidas e bloqueadas, em que <allowlist> e <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 com as seleções de UID.
  • Evitar que alguém (UID) ou algo (PID) consuma esses recursos para aumentar o logspan e melhorar a visibilidade dos problemas que você está diagnosticando.

Por padrão, o sistema de geração de registros impede o pior infrator nas estatísticas de registro de forma automática e dinâmica com o objetivo de 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.

Adicionar 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 o GID dos processos, seja declarado como um infrator. Adicionar 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. Portanto, a sintaxe para especificar a lista de permissões e de bloqueio é esta:


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

or

adb shell
$ logcat -P '<allowlist_and_denylist>'

O exemplo abaixo 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"'

Você pode usar as variações de listas de permissões e de bloqueio abaixo:


~! worst uid denylist
~1000/! worst pid in system (1000)
--pid=<pid> ... Mostra apenas registros do PID fornecido.
--uid=<uids> ... Mostra apenas mensagens de registro de UIDs presentes na lista separada por vírgulas <uids>. Não é feita uma busca de nome. Portanto, os UIDs precisam ser fornecidos como valores numéricos. Essa opção é útil apenas para os usuários "root", "log" e "system", porque só eles podem visualizar registros de outros usuários.
--wrap Fica suspenso por 2 horas ou quando o buffer está prestes a encerrar, o que ocorrer primeiro. Melhora a eficiência da pesquisa ao fornecer uma ativação prestes a encerrar.

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:

    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