Logcat — o que é, níveis de logging e trabalho com logs

O que é Logcat no Android

Logcat é um buffer do sistema Android onde todos os processos (incluindo o kernel Linux, system_server e aplicações) escrevem mensagens num formato específico. A ferramenta logcat, incluída no Android SDK, lê este buffer e exibe mensagens em tempo real. A partir do Android 4.1 (API 16), o acesso ao Logcat é restrito: as aplicações só podem ler os seus próprios logs, e os logs do sistema são acessíveis via ADB com acesso de depuração.

Cada mensagem Logcat contém cinco campos: data e hora, PID (identificador de processo), TID (identificador de thread), nível de log e tag. O formato é fixo e idêntico em todas as versões do Android. Isto permite usar as utilidades grep, awk e sed para filtrar logs em pipelines CI/CD sem dependência do IDE.

Os logs são armazenados num buffer circular de tamanho fixo: 256 KB para main, 256 KB para system e 256 KB para events (Android 5+). Quando o buffer transborda, as mensagens antigas são eliminadas. O desenvolvedor pode alterar o tamanho do buffer através da propriedade PROP logcat.size ou nas opções de desenvolvedor do dispositivo.

Níveis de log e tags: estrutura da mensagem Logcat

Seis níveis de logging determinam a importância da mensagem. O Android usa níveis padrão semelhantes a outras plataformas, mas com nomes de constantes próprios na classe Log. Escolher o nível correto ajuda a filtrar logs de forma eficiente e a evitar que mensagens críticas se percam entre as secundárias.

Tags: organização de mensagens por módulos

A tag é uma string de até 23 caracteres que identifica a origem da mensagem. Recomenda-se usar o nome da classe ou módulo como tag: MainActivity, AuthManager, NetworkModule. Isto permite filtrar logs por um componente específico da aplicação. Para uniformidade na equipa, pode criar constantes de tags num ficheiro separado ou usar a biblioteca Timber, que insere automaticamente a tag com base no nome da classe.

Logs de crash e stack trace de exceções

Quando ocorre uma exceção não tratada, o Android escreve automaticamente o stack trace completo no Logcat, indicando a classe, o método, a linha de código e a cadeia de chamadas. O log de crash contém o tipo de exceção (NullPointerException, RuntimeException), a mensagem e a sequência de chamadas desde o ponto da falha até ao ponto de entrada da aplicação. Para analisar logs de crash de dispositivos de utilizadores, utiliza-se o Firebase Crashlytics, que sincroniza o stack trace com o mapa de ofuscação (mapping.txt para Android).

Logcat no Android Studio: interface, filtros e pesquisa

Android Studio fornece uma interface gráfica Logcat acessível através de View → Tool Windows → Logcat (Alt + 6). A janela Logcat atualiza-se em tempo real, mostra todas as mensagens do dispositivo conectado e permite configurar filtros flexíveis para isolar a informação desejada do fluxo geral.

Filtragem por nível e tag

A lista suspensa Log Level filtra mensagens por nível mínimo: selecione WARN para ver apenas avisos e erros, ocultando VERBOSE, DEBUG e INFO. O campo Search permite pesquisar por texto da mensagem ou tag — são suportadas expressões regulares, o que é conveniente para encontrar mensagens por padrão.

Filtros guardados

Os Saved Filters são uma funcionalidade poderosa do Logcat no Android Studio. Pode criar um filtro que mostra apenas mensagens com a tag da sua aplicação (tag:MyApp) e nível WARN+. Os filtros são preservados entre sessões e estão disponíveis na lista suspensa. Para projetos com vários módulos, crie um filtro separado para cada módulo.

# Expressão de exemplo para filtrar logs da aplicação
tag:"MyApp" level:WARN # Somente WARN+ para MyApp
package:"com.mycompany" # Todos os logs do pacote
-tag:"okhttp" # Excluir logs do OkHttp

Exportação e análise

Os logs do Logcat podem ser exportados para um ficheiro de texto através do ícone Save to File. Isto é útil para anexar a tickets no Jira ou analisar sessões longas. O log exportado pode ser aberto em qualquer editor de texto e pode aplicar-se grep para procurar padrões. Para visualização formatada, use a utilidade logcat-color.

ADB logcat: comandos de terminal para trabalho avançado

ADB logcat é a versão de consola do Logcat, acessível através do Android Debug Bridge. A sua principal vantagem é a capacidade de execução em servidores CI, em scripts de automação e em dispositivos sem Android Studio. O ADB logcat suporta todos os mesmos filtros que a interface gráfica, mas com a flexibilidade da linha de comandos.

Comandos básicos

O comando adb logcat sem argumentos exibe todo o buffer em tempo real. Use Ctrl+C para parar. O sinalizador -c limpa o buffer antes de iniciar a gravação — é útil quando precisa de isolar os logs do teste atual das mensagens anteriores. O sinalizador -b seleciona o tipo de buffer: main, system, events, crash (Android 12+).

# Limpar o buffer e iniciar a gravação de logs com a tag MyApp
adb logcat -c
adb logcat MyApp:D *:S

# Guardar logs em ficheiro
adb logcat -d > logcat_dump.txt

# Filtragem por PID do processo
adb logcat --pid=12345

Filtragem com grep e awk

Combinar ADB com utilidades Unix oferece máxima flexibilidade. Por exemplo, o filtro "*:S TAG:D" mostra apenas mensagens com a tag TAG de nível DEBUG e superior, ocultando todas as outras. Para ver apenas exceções, use grep -i exception. Para analisar a frequência de erros, aplique sort | uniq -c na coluna da tag.

Logcat em CI/CD

Em servidores CI, o Logcat é utilizado para recolher diagnósticos durante a execução de testes de UI. Um pipeline típico: limpar o buffer antes de executar os testes, guardar o dump de logs como artefacto de compilação após a execução dos testes. Se um teste falhar, os logs podem determinar se a falha foi causada por ANR, exceção não tratada ou timeout de rede.

Logging no código: Log.d, Log.e e Timber

A classe android.util.Log é a API integrada para escrever mensagens no Logcat. Log.v, Log.d, Log.i, Log.w, Log.e e Log.wtf aceitam uma tag (string) e uma mensagem (string) ou uma mensagem + Throwable. Para formatar mensagens, use String.format ou modelos de string Kotlin — evite concatenação de strings, que cria objetos desnecessários no heap.

Biblioteca Timber

Timber é uma biblioteca popular de Jake Wharton que elimina as deficiências da API Log integrada. A Timber insere automaticamente a tag com base no nome da classe que chamou o logging e não requer a passagem de uma tag em cada chamada. A Timber também suporta logging condicional: em compilações Release, as chamadas Timber.v e Timber.d podem ser desativadas com uma única linha em Application.onCreate.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // API Log integrada
        Log.d("MainActivity", "onCreate called")

        // Timber — tag automática por nome de classe
        Timber.d("onCreate called")
    }

    private fun loadData() {
        try {
            val result = fetchFromNetwork()
            Timber.i("Data loaded: $result")
        } catch (e: IOException) {
            Timber.e(e, "Failed to load data")
        }
    }
}

Logging condicional para Release

Em compilações Release, recomenda-se desativar os logs VERBOSE e DEBUG para reduzir a carga no buffer Logcat e evitar a fuga de informação sensível. A Timber resolve este problema através de PlantingTree: na variante Debug, planta-se DebugTree (regista tudo), em Release — CrashReportingTree (regista apenas ERROR através do Crashlytics). A API Log integrada não suporta logging condicional — o desenvolvedor precisa de envolver cada chamada com if (BuildConfig.DEBUG).