Logs produção: como estruturar em 5 passos práticos

Quando uma aplicação cai em produção, o log é a primeira testemunha. Mas se ele não segue uma estrutura, vira um amontoado de texto que ninguém lê. Estruturar logs não é frescura, é o que separa um diagnóstico de minutos de um de horas.

Neste guia, mostro 5 passos objetivos para estruturar logs em produção, do formato ao descarte. Sem ferramenta mágica, sem configuração mirabolante: o que funciona no uso real.

Passo 1: Defina um formato único e legível

Escolha JSON como formato padrão. Ele é legível por máquina e por humano, e facilita busca em ferramentas como ELK ou Splunk. Um log solto como "erro ao salvar usuário" não ajuda ninguém.

Dica: inclua timestamp em ISO 8601, nível, serviço, mensagem e contexto. Exemplo: {"timestamp":"2024-05-10T14:32:10Z","level":"error","service":"auth","message":"falha ao salvar usuário"}.

Erro comum: misturar formatos. Um log em texto puro e outro em JSON no mesmo sistema quebra a busca. Padronize desde o início.

Passo 2: Use níveis de log com critério

Níveis não são decoração. Use debug para desenvolvimento, info para eventos normais, warn para situações atípicas e error para falhas reais. Em produção, o padrão deve ser info ou warn, para evitar ruído.

Dica: configure o nível mínimo global e permita ajuste dinâmico por serviço. Se um erro aparece, você não quer reimplantar para ver o debug.

Erro comum: logar tudo como error. Isso acostuma o time a ignorar o alerta, e o erro real se perde no meio do alarme falso.

Passo 3: Inclua contexto que resolva o problema

Um log sem contexto é um bilhete sem remetente. Inclua ID do usuário, ID da requisição, operação executada e qualquer dado que ajude a reproduzir o problema. "Falha ao processar pagamento" é inútil sem o ID do pedido.

Dica: em cada entrada, adicione um campo request_id gerado na borda da aplicação. Ele permite rastrear a jornada completa de uma requisição.

Erro comum: logar dados sensíveis, como senha ou cartão. Contexto não é desculpa para vazar informação. Filtre antes de gravar.

Passo 4: Correlacione logs com IDs de rastreamento

Em arquitetura distribuída, um erro pode passar por três serviços. Sem correlação, você vê três logs soltos. Use um ID de rastreamento (trace ID) que atravessa todos os serviços e amarra a história.

Dica: propague o trace ID via cabeçalho HTTP ou contexto de mensageria. Ferramentas como OpenTelemetry fazem isso de forma padronizada.

Erro comum: gerar um novo ID em cada serviço. Isso quebra a correlação. O ID deve nascer na entrada e ser repassado adiante.

Passo 5: Defina política de retenção e rotação

Log em produção não é para guardar para sempre. Defina quanto tempo cada tipo de log fica armazenado, por motivos de custo e de privacidade. Erros podem ficar 30 dias, debug pode ser descartado em horas.

Dica: separe logs por criticidade em buckets diferentes. Assim, você paga armazenamento caro apenas para o que realmente importa.

Erro comum: guardar tudo indefinidamente. Além do custo, você acumula dado pessoal sem necessidade, o que pode violar a LGPD.

Checklist final

• [ ] Formato JSON padronizado em todos os serviços
• [ ] Níveis de log definidos e configurados por ambiente
• [ ] Contexto relevante incluído em cada entrada
• [ ] Trace ID propagado entre serviços
• [ ] Política de retenção documentada e aplicada

FAQ

Qual é o melhor formato para logs em produção?

O formato JSON é o mais recomendado por ser estruturado, legível por máquinas e fácil de integrar com ferramentas de busca e análise. Ele permite campos nomeados, o que facilita filtros e agregações. Evite texto livre, que dificulta a busca e a correlação.

Como escolher o nível de log adequado?

Use debug para desenvolvimento, info para eventos normais, warn para situações atípicas e error para falhas reais. Em produção, o padrão deve ser info ou warn. Ajuste o nível mínimo por ambiente e permita mudança dinâmica sem reimplantar.

O que é correlação de logs e por que importa?

Correlação é a capacidade de agrupar logs de uma mesma requisição ou transação, mesmo que ela passe por vários serviços. Usa-se um trace ID único que é propagado entre os serviços. Sem isso, é impossível reconstruir a jornada de um erro em arquitetura distribuída.

Quanto tempo devo reter logs de produção?

Não existe número fixo. Erros e auditoria podem ficar 30 dias ou mais, enquanto logs de debug podem ser descartados em horas. Avalie custo de armazenamento, requisitos legais e necessidade de troubleshooting. Separe por criticidade para otimizar custo.

Como evitar logs com dados sensíveis?

Implemente filtros no ponto de emissão, antes de gravar. Nunca logue senhas, tokens, cartões ou dados pessoais desnecessários. Use mascaramento ou remoção automática. Revise periodicamente o que está sendo gravado, principalmente em ambientes com LGPD.

Preciso de uma ferramenta cara para estruturar logs?

Não. A estrutura vem do formato e da disciplina do time. Ferramentas como ELK, Loki ou até um simples agregador de logs já funcionam bem. O custo está em armazenamento e processamento, então comece com o que resolve e evolua conforme a necessidade.