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 paralogd
. Se os registros tiverem a tagMyApp
, as propriedades abaixo são verificadas e precisam conter a primeira letra da gravidade mínima (V
,D
,I
,W
,E
ouS
) 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 emlogd
. 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çãoI
: informaçãoW
: avisoE
: erroF
: fatalS
: 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 buffersmain
,system
ecrash
.
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