Log Level no desenvolvimento de aplicativos: o que é, tipos de níveis e configuração

O que é Log Level?

Log Level é um atributo de cada mensagem de log que determina sua importância e urgência de processamento. As plataformas modernas iOS e Android suportam uma escala unificada de 6 a 7 níveis: do mais detalhado (Verbose/Trace) ao crítico (Error/Assert). A escolha do nível determina se a mensagem será gravada no log com a configuração atual da aplicação.

O conceito de Log Level é baseado no princípio da pirâmide de criticidade: quanto maior o nível, menos mensagens são exibidas nele. De acordo com Semaphore CI, 2024, em uma aplicação de produção a distribuição é a seguinte: Info — 60% das mensagens, Warn — 25%, Error — 10%, Debug — 5%. Mensagens Verbose devem estar completamente desativadas em produção.

Cada plataforma implementa o Log Level por meio de sua própria API. O Android usa android.util.Log com os métodos v(), d(), i(), w(), e(). A Apple usa OSLog com os níveis default, info, debug, error, fault. Bibliotecas como Timber e CocoaLumberjack adicionam funcionalidades extras sobre essas APIs padrão.

De acordo com Google I/O 2023, a escolha incorreta do Log Level é a causa de 40% dos problemas de desempenho em produção. Desenvolvedores deixam logs Debug em builds de lançamento, causando gravação excessiva em disco e desgaste acelerado da bateria.

Tipos de níveis de log: de Verbose a Assert

Verbose (TRACE) — o nível mais detalhado, destinado exclusivamente ao desenvolvimento. Neste nível, todos os cálculos intermediários, iterações de loop e resultados de cada etapa do algoritmo são exibidos. No Android, este nível corresponde a Log.v(), no iOS — OSLog com tipo debug (antes do iOS 14, os_trace era usado).

Debug — mensagens de depuração úteis durante o desenvolvimento e testes. Contêm informações sobre o estado de objetos-chave, resultados de consultas SQL e parâmetros de chamadas de API. Ao contrário do Verbose, as mensagens Debug são estruturadas e semanticamente significativas. No iOS, este nível corresponde a OSLogType.debug.

Info — mensagens informativas sobre eventos normais da aplicação: inicialização do SDK, autenticação bem-sucedida, abertura de tela, recebimento de dados do servidor. Mensagens Info não devem conter dados pessoais dos usuários e devem ser seguras para análise em produção. No iOS, OSLogType.info é usado, no Android — Log.i().

Warn — avisos sobre problemas potenciais. A aplicação continua funcionando, mas a situação requer atenção: tamanho do cache próximo ao limite, versão de API obsoleta, resposta de rede lenta, nova tentativa de conexão. No Android — Log.w(), no iOS — OSLogType.default (para avisos).

Error — erros críticos onde a aplicação não pode realizar a operação solicitada, mas continua funcionando: requisição de API falhou, perda de conexão, erro de gravação no banco de dados, falta de permissões. No iOS, OSLogType.error é usado para erros, no Android — Log.e().

Assert (WTF) — o nível mais alto, indicando uma situação que “não pode acontecer.” Usado para registrar bugs que violam invariantes fundamentais do sistema. No Android, mensagens Assert não são exibidas em builds de lançamento por padrão. No iOS, WTF (What a Terrible Failure) é tratado por meio de OSLogType.fault.

Uso de Log Level no Android

Android Log API — o mecanismo de log integrado do pacote android.util.Log. Fornece 6 métodos estáticos: Log.v(), Log.d(), Log.i(), Log.w(), Log.e() e Log.wtf(). Cada método recebe um tag (string identificadora da fonte) e msg (texto da mensagem).

class UserRepository {
    companion object {
        private val TAG = "UserRepo"
    }

    suspend fun loadUser(id: String): User {
        Log.d(TAG, "Carregando usuário com id: $id")

        return try {
            val response = api.fetchUser(id)
            Log.i(TAG, "Usuário carregado com sucesso")
            response.toUser()
        } catch (e: Exception) {
            Log.e(TAG, "Falha ao carregar o usuário: ${e.message}")
            throw e
        }
    }
}

Filtragem por níveis no Android Logcat é feita via ADB: adb logcat *:E mostrará apenas mensagens Error. Em builds de produção, todas as chamadas Log.v() e Log.d() são removidas pelo ProGuard/R8 quando a minificação está ativada. Log.i(), Log.w() e Log.e() permanecem, por isso é importante não exibir dados sensíveis por meio desses métodos.

Para filtragem personalizada em tempo de execução, o Android fornece Log.isLoggable(tag, level) — um método que verifica se o nível especificado está ativado para a tag fornecida. Isso permite ativar dinamicamente o log detalhado para um módulo específico sem recompilar a aplicação.

Uso de Log Level no iOS e macOS

OSLog — o sistema de log unificado da Apple, que substituiu o obsoleto NSLog. O OSLog fornece 5 níveis: debug, info, default (notice), error e fault. A principal vantagem é o log estruturado com suporte para strings formatadas e filtragem dinâmica via console.

import OSLog

let logger = Logger(
    subsystem: "com.example.app",
    category: "network"
)

func fetchData(from url: URL) {
    logger.debug("Starting request to \(url.absoluteString)")

    do {
        let data = try Data(contentsOf: url)
        logger.info("Received \(data.count) bytes")
    } catch {
        logger.error("Request failed: \(error.localizedDescription)")
    }
}

O sistema de filtragem do OSLog funciona no nível do sistema operacional. Mensagens Debug são gravadas apenas quando o depurador está conectado ou quando o argumento -com.apple.CoreData.Logging.debug 1 está ativado. Mensagens Info são coletadas na memória do dispositivo (até 512 KB) e acessíveis via Console.app. Mensagens Error e fault são gravadas continuamente e estão disponíveis para coleta por meio de sistemas de relatório de falhas.

Uma característica importante do OSLog: strings formatadas com espaços reservados. Em vez da interpolação de strings do Swift (que é sempre avaliada, independentemente do nível), o OSLog usa o formato os_log com %{public}@ e %{private}@ para distinguir dados sensíveis. Parâmetros privados são mascarados nos logs de produção.

Production vs Debug: como configurar a filtragem de níveis

A regra principal — um conjunto mínimo de níveis em produção: Info, Warn, Error, Assert. Debug e Verbose devem estar desativados. A razão não é tanto segurança, mas desempenho: cada chamada de log consome tempo de CPU para formatar a string, mesmo que a mensagem não seja exibida.

Formatação preguiçosa de strings

Otimização crítica — nunca use interpolação de strings em chamadas de log. Se a string for construída antes da chamada log(), o tempo de CPU é desperdiçado mesmo quando o nível está desativado. Use formatação preguiçosa por meio de lambdas ou condições de guarda.

No Android, o método Log.isLoggable() atende a esse propósito; no OSLog, strings formatadas nativas com espaços reservados são suportadas. O Timber para Android resolve o problema por meio de timber.log.Tree com verificação de nível dentro da árvore.

Mudança dinâmica de nível em tempo real

Remote Log Level — uma prática onde o nível de log é controlado a partir do servidor via Firebase Remote Config ou serviço similar. Se um erro complexo ocorrer em produção, o desenvolvedor pode ativar remotamente o log Debug para um módulo específico nos dispositivos de um grupo selecionado de usuários.

De acordo com Firebase, 2024, essa prática reduz o tempo de diagnóstico de bugs raros em 60% e permite obter uma imagem completa do problema sem instalar um build de depuração. A principal limitação é que o log só é ativado na próxima inicialização da aplicação após receber a configuração.

Filtragem automática por tipo de build

BuildConfig.DEBUG no Android e #if DEBUG no Swift são mecanismos padrão de compilação condicional que desativam níveis de depuração em builds de lançamento. Para uma arquitetura limpa, recomenda-se mover a seleção do Log Level para um contêiner DI ou fábrica de loggers para não poluir a lógica de negócios com diretivas condicionais.

Melhores práticas ao escolher o nível de log

Primeira regra — cada chamada de log deve responder à pergunta “quem, o quê, quando.” Quem — o componente ou módulo (tag no Android, category no iOS). O quê — o evento específico ou mudança de estado. Quando — o timestamp, adicionado automaticamente pelo sistema de log.

Segunda regra — não registre dados sensíveis por meio de Info e acima. Senhas, tokens, e-mails, números de telefone, coordenadas geográficas precisas são categoricamente proibidos em qualquer log que vá para produção. Se necessário, use mascaramento: “email: us***@example.com.”

Terceira regra — o nível Warn é responsabilidade do desenvolvedor, Error — da equipe. Warn significa “aqui há um problema potencial, fique de olho.” Error significa “aqui há um problema, corrija-o.” Não use Error para situações que são esperadas e tratadas (por exemplo, um erro 404 de API).

Quarta regra — consistência. Todo o projeto deve usar convenções de nomenclatura unificadas para tags e categorias. Recomenda-se ClassName.methodName para tags Android e module.subsystem para categorias iOS. Isso permite filtrar rapidamente os logs por componente.

Quinta regra — teste seus logs. Em testes unitários, verifique se o Log Level correto é chamado em cenários específicos. Existem bibliotecas mock de log para esse fim: Mockito para Android, Cuckoo para iOS. Verificar os níveis nos testes evita o vazamento de mensagens de depuração para produção.