O Logcat é uma ferramenta de linha de comando que despeja um registro de mensagens do sistema, incluindo stack traces, quando o
dispositivo gera um erro e mensagens que você escreveu no app com a
classe Log
.
O assunto desta página é a ferramenta de linha de comando Logcat, mas você pode ver as mensagens de registro da janela Logcat no Android Studio. Para saber como ver 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 mais relevantes são: main
, que armazena a maioria dos registros de aplicativos,
system
, que armazena mensagens originadas do SO Android e
crash
, que armazena registros de falhas. Cada entrada de registro tem uma prioridade
(que pode ser VERBOSE
, DEBUG
, INFO
, WARNING
,
ERROR
ou FATAL
), uma tag que identifica a origem do registro
e a mensagem de registro em si.
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 exibidos por adb logcat
passam por quatro níveis de filtragem:
- Filtragem no tempo de compilação: dependendo das configurações de compilação, alguns registros podem ser removidos
completamente do binário. Por exemplo, o Proguard pode ser configurado para remover chamadas para
Log.d
do código Java. - Filtragem de 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 têm a tagMyApp
, as propriedades a seguir 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
- Filtragem de aplicativos: se nenhuma das propriedades for definida,
liblog
usará a prioridade mínima configurada por__android_log_set_minimum_priority
. A configuração padrão éINFO
. - Filtragem de exibição:
adb logcat
é compatível com filtros extras que podem reduzir a quantidade de registros mostrados emlogd
. Veja os detalhes abaixo.
Sintaxe de linha de comando
Para executar o Logcat pelo shell adb, o uso geral é o seguinte:
[adb] logcat [<option>] ... [<filter-spec>] ...
Você pode executar logcat
como um comando adb ou diretamente em uma solicitação de shell
do seu emulador ou dispositivo conectado. Para ver 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
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 conjunto de buffers main , system e crash
é usado por padrão. Consulte Como visualizar buffers de registro alternativos. |
-c, --clear |
Apaga (descarta) os buffers selecionados e sai. O conjunto de buffers padrão é main ,
system e crash . Para limpar todos os buffers, use
-b all -c .
|
|
Exibe apenas linhas em que a mensagem de registro corresponde a <expr> ,
em que <expr> é uma expressão regular. |
|
Sai após exibir um número de <count> linhas. Isso é destinado ao
pareamento com --regex , mas funcionará por conta própria. |
--print |
Pareado com --regex e --max-count
para permitir que o conteúdo ignore o filtro regex, mas ainda pare no
número correto de correspondências. |
-d |
Despeja 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 |
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 |
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,
vá para 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 ver uma
lista de formatos compatíveis, vá para a seção sobre o formato de saída do
registro de controle.
|
-D, --dividers |
Exibe divisores entre cada buffer de registro. |
-c |
Descarta (apaga) todo o registro e sai. |
-t <count> |
Exibe apenas o número mais recente de linhas. Essa opção inclui a funcionalidade
-d . |
-t '<time>' |
Exibe as linhas mais recentes desde o período especificado. Essa opção inclui a
funcionalidade -d . Consulte a opção -P para
ver informações sobre como citar parâmetros com espaços incorporados.
adb logcat -t '01-26 20:52:41.820' |
-T <count> |
Exibe o número mais recente de linhas desde o período especificado. Essa opção não
inclui a funcionalidade -d . |
-T '<time>' |
Exibe as linhas mais recentes desde o período especificado. Essa opção não inclui
a funcionalidade -d . Consulte a opção -P para
ver 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 |
Saída do registro em binário. |
-S, --statistics |
Inclui estatísticas na saída para ajudar você a identificar e segmentar criadores de spams de registro. |
-G <size> |
Define o tamanho do buffer do anel de registro. Pode adicionar
K ou M ao final para indicar
kilobytes ou megabytes. |
-p, --prune |
Exibe (lê) a lista de permissões e a lista de bloqueio e
não aceita argumentos, da seguinte maneira:
adb logcat -p |
-P '<list> ...'
|
Grava (define) a lista de permissões e a lista de bloqueio para ajustar o
conteúdo da geração de registros para uma finalidade específica. Você fornece um conteúdo misto de entradas de lista
permitidas e negadas, em que
<allowlist> ou <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 automaticamente o pior infrator nas estatísticas de registro de maneira dinâmica para 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. A adição de 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 GID dos processos, seja declarado como um infrator. Além disso, a adição de 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 a seguir 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"' Outras variações de comando de lista de permissões e de bloqueio que podem ser usadas são as seguintes: ~! worst uid denylist ~1000/! worst pid in system (1000) |
--pid=<pid> ... |
Apenas imprime registros do PID fornecido. |
--wrap |
Suspensão de 2 horas ou quando o buffer estiver prestes a encerrar, o que ocorrer primeiro. Melhora a eficiência da pesquisa ao fornecer uma ativação prestes a encerrar. |
Como filtrar a saída do registro
- A tag de uma mensagem de registro é uma string curta que indica o componente do sistema por meio do qual a mensagem é originada (por exemplo, “View” para o sistema de visualização).
- A prioridade é um dos seguintes 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 é exibido)
Você pode ver uma lista de tags usadas no sistema, com suas prioridades, executando
o logcat e observando as duas primeiras colunas de cada mensagem, apresentadas como
<priority>/<tag>
.
Veja a seguir um exemplo de saída breve de logcat exibida com o
comando logcat -v brief output
. Ele 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...}
Para reduzir a saída do registro a um nível mais razoável, você pode restringi-la usando expressões de filtro. Expressões de filtro permitem indicar ao sistema as combinações de tag e prioridade do seu interesse para ele suprimir outras mensagens para as tags especificadas.
Uma expressão de filtro segue esse 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 superiores são
gravadas no registro. Você pode fornecer quantas especificações de tag:priority
quiser em uma
única expressão de filtro. A série de especificações é delimitada por espaços em branco.
Aqui está um exemplo de uma expressão de filtro que suprime todas as mensagens de registro, exceto aquelas com a tag "ActivityManager", com prioridade "Informação" ou superior, e todas as mensagens de registro com tag "MyApp", com prioridade "Depuração" ou superior:
adb logcat ActivityManager:I MyApp:D *:S
O elemento final na expressão acima, *:S
, define o nível de prioridade de todas
as tags como "silencioso", garantindo que apenas as mensagens de registro com "ActivityManager" e "MyApp" sejam exibidas. Usar
*:S
é uma forma excelente de garantir que a saída do registro seja restrita aos filtros especificados
explicitamente, permitindo que seus filtros funcionem como uma lista de permissões para saída de
registro.
A expressão de filtro a seguir exibe todas as mensagens de registro com o nível de prioridade “aviso” e superior, em todas as tags:
adb logcat *:W
Se você estiver executando o Logcat no seu computador de desenvolvimento (e não 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 será exportado para a instância do emulador/dispositivo
se você estiver executando o logcat em um shell remoto ou usando adb shell
logcat
.
Formato de saída do registro de controle
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 exibam um campo de metadados específico. Para isso,
use a opção -v
e especifique um dos formatos de saída compatíveis listados
abaixo.
brief
: exibe a prioridade, a tag e o PID do processo que está emitindo a mensagem.long
: exibe todos os campos de metadados e mensagens separadas com linhas em branco.process
: exibe apenas o PID.raw
: exibe a mensagem de registro bruta, sem outros campos de metadados.tag
: exibe somente 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): exibe 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
: exibe a data, o momento de invocação, a prioridade, a tag e o PID do processo emitindo a mensagem.
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 saída
thread
:
adb logcat -v thread
Você só pode especificar um formato de saída com a opção -v
, mas
pode especificar o número de modificadores que fizer sentido. O Logcat ignora modificadores que não fazem sentido.
Modificadores de formato
Modificadores de formato mudam a saída do Logcat em termos de qualquer combinação de um ou mais
dos seguintes modificadores. Para especificar um modificador de formato, use a opção -v
da
seguinte maneira:
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 das seguintes opções de formato: brief
,
long
, process
, raw
, tag
,
thread
, threadtime
e time
.
É possível ver os detalhes do modificador de formato digitando 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 de log de eventos.epoch
: exibe o tempo em segundos a partir de 1º de janeiro de 1970.monotonic
: exibe 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, exibe o UID ou o ID do Android do processo registrado.usec
: exibe a hora com precisão de microssegundos.UTC
: tempo de exibição como UTC.year
: adiciona o ano ao horário exibido.zone
: adiciona o fuso horário local ao horário exibido.
Como ver buffers de registro alternativos
O sistema de registro do Android mantém vários buffers para mensagens de registro, e nem todas
as mensagens de registro são enviadas para o buffer circular padrão. Para ver 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 ver qualquer um dos seguintes buffers alternativos:
radio
: exibe o buffer que contém mensagens relacionadas a rádio e telefonia.events
: exibe as mensagens interpretadas do buffer de evento do sistema binário.main
: exibe o buffer de registro principal (padrão). Não contém mensagens de registro do sistema e de falhas.system
: exibe o buffer de registro do sistema (padrão).crash
: exibe o buffer do registro de falhas (padrão).all
: exibe 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 ver um buffer de registro que contém mensagens de rádio e telefonia:
adb logcat -b radio
Também é possível especificar várias sinalizações -b
para todos os buffers que você quiser exibir,
da seguinte maneira:
logcat -b main -b radio -b events
Você pode especificar uma única sinalização -b
com uma lista separada por vírgulas de buffers,
por exemplo:
logcat -b main,radio,events
Como criar registros a partir do código
A classe Log
permite a criação de entradas de registro no seu código que são exibidas
na ferramenta logcat. Métodos de registro em log 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 é semelhante a:
I/MyActivity( 1557): MyClass.getView() — get item number 1