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:
  • 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] 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:

    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