Ferramenta de linha de comando Logcat

O Logcat é uma ferramenta de linha de comando que despeja um registro de mensagens do sistema, incluindo rastreamentos de pilha quando o dispositivo gera um erro e mensagens que você escreveu no seu 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.

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 um prompt de shell do seu emulador ou dispositivo conectado. Para ver a saída do registro usando adb, acesse o diretório platform-tools/ do seu SDK e execute:

    adb logcat
    

Para receber ajuda on-line do logcat, inicie um 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 apagar todos os buffers, use -b all -c.
-e <expr>, --regex=<expr> Imprime apenas as linhas em que a mensagem de registro corresponde a <expr>, onde <expr> é uma expressão regular.
-m <count>, --max-count=<count> Sai após imprimir o número de linhas <count>. Isso se destina 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> Escreve a saída da mensagem de registro em <filename>. O padrão é stdout.
-g, --buffer-size Imprime o tamanho do buffer de registro especificado e sai.
-n <count> Define o número máximo de registros rotacionados para <count>. O valor padrão é 4. Requer a opção -r.
-r <kbytes> Rotaciona o arquivo de registro a cada <kbytes> de saída. O valor padrão é 16. Requer a opção -f.
-s Equivalente à especificação de filtro '*:S' e é usado para preceder uma lista de especificações de filtro que adicionam conteúdo.
-v <format> Define o formato de saída das mensagens de registro. O padrão é o formato threadtime. Para ver uma lista de formatos permitidos, consulte Como controlar o formato de saída do registro.
-D, --dividers Imprime divisores entre cada buffer de registro.
-c Descarta (apaga) todo o registro e sai.
-t <count> Imprime apenas o número mais recente de linhas. Essa opção inclui a funcionalidade -d.
-t '<time>' Imprime as linhas mais recentes desde o período especificado. Essa opção inclui a funcionalidade -d. Confira 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> Imprime o número mais recente de linhas desde o período especificado. Essa opção não inclui a funcionalidade -d.
-T '<time>' Imprime as linhas mais recentes desde o período especificado. Essa opção não inclui a funcionalidade -d. Confira 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 Imprime (lê) as listas de permissões e proibições atuais e não aceita argumentos, da seguinte maneira:

    adb logcat -p
    
-P '<list> ...'
--prune '<list> ...' -P '<white_and_black_list>'
Escreve (define) as listas de permissões e proibições para ajustar o conteúdo do registro para uma finalidade específica. Você fornece um conteúdo misto de entradas das listas <white> e ~<black>, em que <white> (permissões) ou <black> (proibições) pode ser um UID, UID/PID ou PID. Com a orientação das estatísticas do Logcat (logcat -S), pode-se considerar ajustes nas listas de permissões e proibições para fins como:
  • Dar a maior longevidade ao conteúdo de geração de registros específico por meio das seleções de UID.
  • Lista de proibições de quem (UID) ou o que (PID) está consumindo esses recursos para ajudar a aumentar o logspan para que você possa ter mais visibilidade dos problemas que está diagnosticando.

Por padrão, o sistema de registro coloca automaticamente na lista de proibições 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 o GID dos processos, seja declarado como um infrator. Além disso, a adição de uma lista de proibições 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 não preserva as aspas, então a sintaxe para especificar listas de permissões e proibições é a seguinte:


    $ adb logcat -P '"<white_and_blacklist>"'

    or

    adb shell
    $ logcat -P '<white_and_blacklist>'
    

O exemplo a seguir especifica uma lista de permissões com PID 32676 e UID 675 e uma lista de proibições com PID 32677 e UID 897. O PID 32677 na lista de proibições é 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 proibições que você pode usar são as seguintes:


    ~! worst uid blacklist
    ~1000/! worst pid in system (1000)
    
--pid=<pid> ... Apenas imprimir 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, fornecendo 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 a partir 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ção
    • I: informação
    • W: aviso
    • E: erro
    • F: fatal
    • S: silenciosa (prioridade mais alta, em que nada é impresso)

Você pode ver uma lista de tags usadas no sistema, com prioridades, executando o Logcat e observando as duas primeiras colunas de cada mensagem, apresentadas como <priority>/<tag>.

A seguir, temos 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 que ele suprima outras mensagens para as tags especificadas.

Uma expressão de filtro segue o formato tag:priority ..., em que tag indica a tag em questão e priority indica o nível mínimo de prioridade a ser reportado 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 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 maneira excelente de garantir que a saída do registro fique restrita 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 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 (em vez de em um shell adb remoto), também é possível 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"
    

Observe que o filtro ANDROID_LOG_TAGS não será exportado para a instância do emulador/dispositivo se você estiver executando o Logcat a partir de 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 permitidos listados abaixo.

  • brief: exibe prioridade, tag e 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 apenas a prioridade e a tag.
  • thread:: um formato legado que mostra prioridade, PID e TID da linha de execução que está emitindo a mensagem.
  • threadtime (padrão): exibe a data, o tempo de invocação, a prioridade, a tag, o PID e o TID da linha de execução que está emitindo a mensagem.
  • time: exibe a data, a hora de invocação, a prioridade, a tag e o PID do processo que está emitindo a mensagem.

Ao iniciar o Logcat, é possível 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
    

Observe que você só pode especificar um formato de saída com a opção -v, mas é possível especificar todos os modificadores em que isso fizer sentido. O Logcat ignora modificadores que não fazem sentido.

Modificadores de formato

Modificadores de formato alteram 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: 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 de buffer de registro. Esse modificador afeta somente 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 código do Android do processo registrado.
  • usec: exibe a hora com precisão até microssegundos.
  • UTC: tempo de exibição como UTC.
  • year: adiciona o ano ao tempo exibido.
  • zone: adiciona o fuso horário local ao tempo 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 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 ver qualquer um dos seguintes buffers alternativos:

  • radio: exibe o buffer que contém mensagens relacionadas a rádio/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: informa sobre os buffers main, system e crash.

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
    

Você também pode especificar várias sinalizações -b para todos os buffers que você quer imprimir, da seguinte maneira:

    logcat -b main -b radio -b events
    

Você pode especificar uma única sinalização -v com uma lista separada por vírgulas de buffers, por exemplo:

    logcat -v main,radio,events
    

Como criar registros 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:

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