Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

Ferramenta de linha de comando Logcat

O Logcat é uma ferramenta de linha de comando que gera um registro de mensagens do sistema, inclusive rastros de pilha quando o dispositivo apresenta um erro e mensagens escritas pelo seu aplicativo com a classe Log.

O assunto desta página é a ferramenta de linha de comando Logcat, mas você pode visualizar as mensagens de registro da janela Logcat no Android Studio. Para saber como visualizar e filtrar registros do Android Studio, consulte Gravar e visualizar logs com o Logcat.

Sintaxe de linha de comando

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

Você pode executar logcat como um comando adb ou diretamente em um prompt de shell do seu emulador ou dispositivo conectado. Para visualizar a saída do registro usando adb, acesse o diretório platform-tools/ do seu SDK e execute:

$ adb logcat

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 buffer main é usado por padrão. Consulte Como visualizar buffers de registro alternativos.
-c Limpa (apaga) todo o registro e sai.
-d Exibe o registro na tela e sai.
-f <filename> Grava a saída de mensagens de registro em <filename>. O padrão é stdout.
-g 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 Define a especificação do filtro padrão para silencioso.
-v <format> Define o formato de saída das mensagens de registro. O formato padrão é brief. Para obter uma lista de formatos permitidos, consulte Como controlar o formato de saída do registro.

Como iniciar o Logcat

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

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

Você pode usar o comando logcat do seu computador de desenvolvimento ou de um shell adb remoto em uma instância de emulador/dispositivo. Para visualizar a saída do registro em seu computador de desenvolvimento, use

$ adb logcat

e, em um shell adb remoto, use

# logcat

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

-c Limpa (apaga) todo o registro e sai.
-d Exibe o registro na tela e sai.
-f <filename> Grava a saída de mensagens de registro em <filename>. O padrão é stdout.
-g 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 Define a especificação do filtro padrão para silencioso.
-v <format> Define o formato de saída das mensagens de registro. O formato padrão é brief. Para obter uma lista de formatos permitidos, consulte Como controlar o formato de saída do registro.

Como filtrar a saída do registro

Cada mensagem do registro do Android é associada a uma tag e uma prioridade.

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

Para ver uma lista das tags usadas no sistema e suas prioridades, execute o Logcat e observe as duas primeiras colunas de cada mensagem, que são apresentadas como <priority>/<tag>.

Veja um exemplo de saída do Logcat que mostra que a mensagem está associada 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 volume mais razoável, você pode restringi-la usando expressões de filtragem. Expressões de filtragem permitem indicar ao sistema as combinações de tag e prioridade mais importantes para que ele suprima outras mensagens para as tags especificadas.

Uma expressão de filtragem segue o formato tag:priority ..., onde tag indica a tag em questão e priority indica o nível de prioridade mínima a ser reportada para a 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 só expressão de filtragem. A série de especificações é delimitada por espaços em branco.

Veja um exemplo de expressão de filtragem que suprime todas as mensagens de registro com a tag "ActivityManager", na prioridade “Informações" ou superior, e todas as mensagens com a tag "MyApp”, na prioridade “Depuração" ou superior:

adb logcat ActivityManager:I MyApp:D *:S

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

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

adb logcat *:W

Se você estiver executando o Logcat no seu computador de desenvolvimento (em vez de em um shell adb remoto), também é possível definir uma expressão de filtragem padrão ao exportar um valor para a variável de ambiente ANDROID_LOG_TAGS:

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

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

Como controlar o formato de saída do registro

Mensagens de registro contêm alguns campos de metadados, além da tag e da prioridade. Você pode modificar o formato da saída para as 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 permitidos listados abaixo.

  • brief — Exibe a prioridade/tag e o PID do processo que emite a mensagem (o formado padrão).
  • process — Exibe apenas o PID.
  • tag — Exibe apenas a prioridade/tag.
  • raw — Exibe a mensagem de registro bruta, sem outros campos de metadados.
  • time — Exibe a data, a hora de invocação, a prioridade/tag e o PID do processo que emite a mensagem.
  • threadtime — Exibe a data, a hora de invocação, a prioridade, a tag, o PID e o TID do thread que emite a mensagem.
  • long — Exibe todos os campos de metadados e mensagens separadas com linhas em branco.

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 mensagem thread:

adb logcat -v thread

Observe que só é possível especificar um formato de saída com a opção -v.

Como visualizar buffers de registro alternativos

O sistema de registro do Android mantém vários buffers para mensagens de registro e nem toda as mensagens de log são enviadas para o buffer circular padrão. Para ver mensagens de registro adicionais, você pode executar o comando logcat com a opção -b para solicitar a visualização de um buffer circular alternativo. Você pode visualizar qualquer um dos seguintes buffers alternativos:

  • radio — Visualize o buffer que contém mensagens relacionadas a rádio/telefonia.
  • events — Visualize o buffer que contém mensagens relacionadas a eventos.
  • main — Visualize o principal buffer de registro (padrão)

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

[adb] logcat [-b <buffer>]

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

adb logcat -b radio

Como visualizar stdout e stderr

Por padrão, o sistema Android envia saídas stdout e stderr (System.out e System.err) para /dev/null. Em processos que executam a VM Dalvik, você pode fazer com que o sistema grave uma cópia da saída no arquivo de registros. Nesse caso, sistema grava as mensagens no registro usando as tags stdout e stderr, ambas com a prioridade I.

Para rotear a saída dessa maneira, interrompa a execução da instância do emulador/dispositivo e use o comando de shell setprop para ativar o redirecionamento da saída. Isso é feito da seguinte maneira:

$ adb shell stop
$ adb shell setprop log.redirect-stdio true
$ adb shell start

O sistema mantém essa configuração até que você encerre a instância do emulador/dispositivo. Para usar essa configuração como padrão na instância do emulador/dispositivo, adicione uma entrada a /data/local.prop no dispositivo.

Como criar logs a partir do código

A classe Log permite criar entradas de registro no seu código que podem ser exibidas na ferramenta Logcat. Métodos de registro em log comuns incluem:

Por exemplo, quando você usa esta chamada:

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