Conferir registros com o Logcat

A janela Logcat no Android Studio ajuda a depurar seu app mostrando registros do dispositivo em tempo real. Por exemplo, mensagens adicionadas ao app com a classe Log, mensagens de serviços executados no Android ou mensagens do sistema, como quando ocorre uma coleta de lixo. Quando um app gera uma exceção, o Logcat mostra uma mensagem seguida do stack trace associado contendo links para a linha de código.

Introdução à janela do Logcat

Para conferir as mensagens de registro do seu app, siga as etapas abaixo.

1. No Android Studio, crie e execute seu app em um dispositivo físico ou um emulador.
2. Selecione View > Tool Windows > Logcat na barra de menus.

Por padrão, o Logcat rola até o fim. Para desativar esse recurso, clique na visualização do Logcat ou role a tela para cima usando a roda do mouse. Para reativá-lo, clique em Scroll to the End na barra de ferramentas. Você também pode usar a barra de ferramentas para limpar, pausar ou reiniciar o Logcat.

Figura 1. O Logcat formata os registros para verificar informações úteis com mais facilidade, como tags e mensagens, e identificar diferentes tipos de registros, como avisos e erros.

Como ler registros

Cada registro tem uma data, um carimbo de data/hora, um ID do processo e da linha de execução, uma tag, o nome do pacote, a prioridade e uma mensagem associados a ele. As diferentes tags têm uma cor exclusiva que ajuda a identificar o tipo de registro. Cada entrada de registro tem a prioridade de FATAL, ERROR, WARNING, INFO, DEBUG ou VERBOSE.

Por exemplo, a mensagem de registro abaixo tem prioridade DEBUG e uma tag ProfileInstaller:

2022-12-29 04:00:18.823 30249-30321 ProfileInstaller        com.google.samples.apps.sunflower    D  Installing profile for com.google.samples.apps.sunflower

Configurar a visualização de registros

A visualização de registro padrão mostra a data, hora, ID do processo e da linha de execução, tag, nome do pacote, prioridade e mensagem associados a cada registro. Por padrão, as linhas de mensagem não são unidas na visualização de registro, mas você pode usar a opção Soft-Wrap na barra de ferramentas do Logcat.

Você pode alternar para a visualização Compact, que tem menos informações de exibição padrão, clicando em Configure Logcat Formating Options na barra de ferramentas Logcat.

Para configurar ainda mais a quantidade de informações mostradas, selecione Modify Views e escolha se você quer que o carimbo de data/hora, as tags, os IDs dos processos ou os nomes dos pacotes apareçam.

Mudar o esquema de cores

Para mudar o esquema de cores, acesse Android Studio > Settings > Editor > Color Scheme. Para mudar o esquema de cores da visualização de registro, selecione Android Logcat. Para mudar o esquema de cores do seu filtro, selecione Logcat Filter.

Outras opções de configuração

Para mais opções de configuração, acesse Android Studio > Settings > Tools > Logcat. Nesse menu, você pode escolher o tamanho do buffer do ciclo do Logcat, o filtro padrão para novas janelas do Logcat e se você quer adicionar filtros do histórico ao preenchimento automático.

Usar o Logcat em várias janelas

As guias ajudam você a alternar facilmente entre diferentes dispositivos ou consultas. É possível criar várias guias do Logcat clicando em New Tab . Clique com o botão direito do mouse em uma guia para renomeá-la e reorganizá-la.

Além disso, você pode dividir a visualização em uma guia para facilitar a comparação entre dois conjuntos de registros. Para criar uma divisão, clique com o botão direito do mouse na visualização de registro ou clique na opção Split Panels da barra de ferramentas. Em seguida, selecione Split Right ou Split Down. Para fechar uma divisão, clique com o botão direito do mouse e selecione Close. Cada divisão permite que você defina uma conexão de dispositivo, opções de visualização e consulta.

Figura 2. Divida as janelas do Logcat no Android Studio.

Na barra de ferramentas do Logcat, role até o fim dos registros ou clique em uma linha específica para que ela fique visível.

Registros de consultas usando a pesquisa de chave-valor

No Android Studio, é possível gerar pesquisas de chave-valor no campo de consulta principal. Esse sistema oferece precisão para o que você quer consultar e também exclui registros com base em chaves-valor. Você tem a opção de usar expressões regulares, mas não é necessário depender delas para consultas. Para conferir as sugestões, pressione Ctrl + Space no campo de consulta.

Figura 3. Pressione Ctrl + Space no campo de consulta para conferir uma lista de consultas sugeridas.

Abaixo estão alguns exemplos de chaves que podem ser usadas na consulta:

• tag: corresponde ao campo tag da entrada de registro.
• package: indica o nome do pacote do app de geração de registros.
• process: indica o nome do processo do app de geração de registros.
• message: corresponde à mensagem da entrada de registro.
• level: indica o nível de registro grave especificado ou maior, por exemplo, DEBUG.
• age: indica se o carimbo de data/hora de entrada é recente. Os valores são especificados como um número seguido de uma letra que especifica a unidade de tempo: s para segundos, m para minutos, h para horas e d para dias. Por exemplo, age: 5m filtra apenas as mensagens que foram registradas nos últimos 5 minutos.

Expressões regulares e de negação

Os campos abaixo oferecem suporte para expressões regulares e de negação que correspondem a: tag, package, message e line.

A negação é expressa anexando um sinal - ao nome do campo. Por exemplo, -tag:MyTag corresponde a entradas de registro em que tag não contém a string MyTag.

A expressão regular é expressa anexando um ~ ao nome do campo. Por exemplo, tag~:My.*Tag.

Modificadores de expressões regulares e de negação podem ser combinados. Por exemplo, -tag~:My.*Tag.

Operadores lógicos e parênteses

A linguagem de consulta oferece suporte aos operadores AND e OR expressos por &, | e parênteses. Exemplo:

(tag:foo | level:ERROR) & package:mine

A precedência normal do operador é aplicada, portanto:

tag:foo | level:ERROR & package:mine

É avaliado como:

tag:foo | (level:ERROR & package:mine)

Operadores lógicos implícitos

Se operadores lógicos não forem aplicados, a linguagem de consulta avaliará automaticamente vários termos de filtro key-value não negados com a mesma chave de OR e todo o restante com AND.

Exemplo:

tag:foo tag:bar package:myapp

É avaliado como:

(tag:foo | tag:bar) & package:myapp

Mas:

tag:foo -tag:bar package:myapp

É avaliado como:

tag:foo & -tag:bar & package:myapp

Se vários termos de consulta forem separados por espaços em branco sem um operador lógico, eles serão tratados como "AND" com precedência baixa. Por exemplo, o termo foo bar tag:bar1 | tag:bar2 é equivalente a 'foo bar' & (tag: bar1 | tag: bar2).

Consultas especiais

package:mine

A chave de pacote oferece suporte ao valor especial mine. Esse valor especial corresponde a todos os nomes de pacote contidos no projeto aberto.

level

A consulta level corresponde ao nível de registro da mensagem do Logcat, em que o nível da entrada de registro é maior ou igual ao nível da consulta.

Por exemplo, level:INFO corresponde a todas as entradas de registro com nível INFO, WARN, ERROR ou ASSERT. O nível não diferencia maiúsculas de minúsculas. Os níveis válidos são: VERBOSE, DEBUG, INFO, WARN, ERROR e ASSERT.

age

A consulta age corresponde às entradas baseadas no carimbo de data/hora e é formatada como age:<number><unit>, em que

• <number> é um número inteiro.
• <unit> é uma destas opções: s, m, h ou d (segundos, minutos, horas e dias).

Considerando a lista abaixo, a consulta age corresponde a mensagens de registro com um carimbo de data/hora no intervalo descrito pelo valor. Por exemplo: a consulta age:5m corresponde a entradas com um carimbo de data/hora de até cinco minutos atrás.

age:30s
age:5m
age:3h
age:1d

O carimbo de data/hora é comparado ao do host, não ao do dispositivo conectado. Se o horário do dispositivo não for definido corretamente, essa consulta poderá não funcionar como esperado.

Chave is

É possível usar a chave is desta forma:

• is:crash corresponde a entradas de registro que representam uma falha de aplicativo (nativo ou Java).
• is:stacktrace corresponde a entradas de registro que representam qualquer coisa parecida com um stack trace do Java, independente do nível de registro.

Chave name

A chave name permite fornecer um nome exclusivo para um filtro salvo, para que ele seja identificado com facilidade no menu suspenso do histórico de filtros. Embora não ocorra um erro quando name é especificado mais de uma vez, o ambiente de desenvolvimento integrado usa apenas o último valor especificado para name na consulta.

Conferir o histórico de consultas

Para conferir seu histórico de consultas, clique em Show history ao lado do campo de consulta. Para marcar uma consulta como favorita e mantê-la no topo da lista em todos os projetos do Studio, clique na estrela ao lado dela. Também é possível usar a chave name: para facilitar o reconhecimento das consultas favoritas. Para mais informações, consulte Consultas especiais.

Figura 4. Para adicionar uma consulta aos favoritos, clique na estrela ao lado dela.

Rastrear registros em falhas e reinicializações do app

Quando o Logcat detecta que o processo do app foi interrompido e reiniciado, ele mostra uma mensagem na saída, como PROCESS ENDED e PROCESS STARTED. A reinicialização do Logcat preserva a configuração da sessão, como divisões de guia, filtros e opções de visualização, para que você possa retornar a ela sem problemas.

Figura 5. Quando o processo do app é reiniciado, o Logcat mostra uma mensagem informando que o processo foi encerrado e iniciado de novo.