rochasolutions
Infraestrutura

O Que São Logs Estruturados e Como Implementar na Aplicação?

Danilo Rocha6 min de leitura

O que são logs estruturados

Logs estruturados são registros de evento escritos em um formato fixo e previsível, normalmente JSON, em vez de uma frase livre. Cada informação relevante vira um campo próprio: hora, nível, serviço, id da requisição, mensagem. Isso transforma o log de texto solto em dado que uma ferramenta consegue filtrar, agrupar e consultar.

A diferença aparece na hora de investigar um problema. Um console.log('usuário 482 falhou no checkout') só serve para quem já sabe o que está procurando e tem paciência para rolar o arquivo até achar a linha certa. Um log estruturado com os campos userId: 482, event: checkout_failed e requestId: a93f permite buscar exatamente essa combinação em milhares de linhas, em qualquer ordem, sem depender do texto exato da mensagem.

Suponha um time de cinco pessoas respondendo a um incidente em produção. Com log em texto livre, cada pessoa escreve seu próprio grep tentando adivinhar a palavra certa. Com log estruturado, todo mundo filtra pelo mesmo requestId e chega ao mesmo conjunto de linhas, nos mesmos segundos.

Na prática, cada linha de log estruturado é um objeto JSON de uma só linha, sem quebra interna, para que o coletor consiga ler e indexar sem precisar reconstruir a mensagem a partir de várias linhas de arquivo. Uma linha típica se parece com {"level":"error","service":"checkout","requestId":"a93f","userId":482,"message":"pagamento recusado"}. Qualquer ferramenta de busca de log lê esse formato nativamente e permite filtrar por service e level ao mesmo tempo, sem regex.

Por que logs estruturados facilitam a correlação de eventos

Logs estruturados facilitam a correlação porque o mesmo campo aparece, com o mesmo nome, em todo serviço que participa da requisição. Sem esse contrato, cada aplicação grava log do seu próprio jeito e ninguém consegue ligar um evento ao outro.

Suponha um pedido de e-commerce que passa por quatro serviços diferentes: API de pedidos, serviço de pagamento, fila de envio de email, serviço de estoque. Se cada um registra requestId com o mesmo valor recebido no cabeçalho da requisição original, uma consulta única traz a história completa daquele pedido, na ordem em que aconteceu, independente de qual serviço escreveu cada linha.

Esse mesmo campo também é o que conecta o log ao resto da observabilidade de aplicação: uma métrica que disparou e um trace que ficou lento apontam para o mesmo requestId, e o log estruturado é o terceiro pilar que explica o que aconteceu dentro daquela requisição específica.

Como implementar logs estruturados passo a passo

Implementar log estruturado não exige trocar a stack nem reescrever a aplicação. A mudança é de disciplina no formato, aplicada em poucos pontos centrais do código.

  1. Escolha uma biblioteca de log que grave JSON por padrão, como Pino ou Winston em Node, structlog em Python, ou o logger nativo quando ele já suportar esse formato.
  2. Defina um conjunto fixo de campos obrigatórios em todo log: timestamp, nível, nome do serviço, requestId e a mensagem. Documente esses nomes para que todo serviço use exatamente os mesmos.
  3. Gere o requestId na borda do sistema, no primeiro serviço que recebe a requisição, e propague esse valor para todo serviço seguinte via cabeçalho HTTP ou metadado da fila.
  4. Adicione contexto de negócio quando fizer sentido, como userId ou orderId, sem transformar isso em regra geral: campo demais em todo log vira ruído, não contexto.
  5. Centralize a saída em um único coletor, como um serviço de agregação de log na nuvem, em vez de deixar cada servidor com seu próprio arquivo isolado.
  6. Defina o nível de cada log com critério: error para o que precisa de ação, warn para o que merece atenção, info para evento de negócio relevante, debug só em ambiente que não é produção.

Erros comuns ao estruturar logs

O erro mais comum é registrar texto dentro de um campo que deveria ser estruturado, como escrever message: "usuário 482, pedido 991, falhou" em vez de usar campos separados para userId e orderId. Isso recria o mesmo problema do log livre, só que disfarçado de JSON.

Outro erro é logar informação sensível sem perceber: senha, token, número de cartão. Um log estruturado é mais fácil de buscar, e isso inclui ser mais fácil de encontrar por quem não deveria ter acesso àquele dado. Qualquer campo que carregue informação sensível precisa ser mascarado antes de chegar ao coletor de log.

O terceiro erro é logar demais. Nível info em toda linha de código produz um volume que encarece o armazenamento e torna a busca mais lenta, sem agregar sinal nenhum. A régua prática é perguntar se aquele log ajudaria alguém a entender um incidente três meses depois. Se não ajudar, o nível certo é debug ou a linha nem deveria existir.

O quarto erro aparece quando a migração para log estruturado é parcial. Alguns serviços antigos continuam escrevendo texto livre enquanto os mais novos já gravam JSON, e o coletor central recebe os dois formatos misturados. Isso obriga o time a manter duas formas de buscar: uma consulta estruturada para os serviços novos e um grep manual para os antigos. A migração vale mais quando cobre, ao menos, os serviços que mais geram incidente, em vez de ficar só nos projetos criados depois da decisão.

Logs estruturados e observabilidade de aplicação

Log estruturado é a base sobre a qual o resto da observabilidade se apoia. Sem um formato consistente, nem o painel de monitoramento de erros consegue agrupar ocorrências do mesmo problema, porque cada linha de log chega com um texto levemente diferente da anterior.

A mesma disciplina de campo fixo que estrutura o log também sustenta o health check de um serviço: quando o endpoint de saúde registra o motivo exato de uma falha, em vez de só um código de status, o log estruturado dessa verificação já chega pronto para cruzar com o incidente que o time está investigando.

Se o seu time ainda depende de grep em arquivo de texto para entender o que aconteceu em produção, fale com a gente para revisar como a aplicação registra seus eventos antes do próximo incidente difícil de rastrear.