O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Ferramenta de linha de comando Logcat

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.

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.
-e <expr>, --regex=<expr> Exibe apenas linhas em que a mensagem de registro corresponde a <expr>, em que <expr> é uma expressão regular.
-m <count>, --max-count=<count> Sair 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 é usada 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 de registros 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ê) 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ê oferece um conteúdo misto de entradas das listas <white> e ~<black>, em que <white> ou <black> pode ser um UID, UID/PID ou /PID. Com a orientação das estatísticas do logcat (logcat -S), é possível considerar mudanças nas listas de permissões e proibições para finalidades 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. Por esse motivo, 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 é 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 que ele suprima 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 os filtros sejam usados como uma "lista de permissões" para uma 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 (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"
    

O filtro ANDROID_LOG_TAGS não é 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 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, PID e 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 é possível especificar o número de modificadores que 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 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 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: exige 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 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
    

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 que você crie entradas de registro no seu código que são 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