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 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] 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 .
|
|
Mostra apenas linhas em que a mensagem de registro corresponde a <expr> ,
em que <expr> é uma expressão regular. |
|
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> ...'
|
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:
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 -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çã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