Entendendo na Prática: Logging Estruturado

O que e logging estruturado?

E a prática de emitir logs em formato parseável em vez de texto livre.

Logging estruturado e a prática de emitir logs em formato estruturado, tipicamente JSON, em vez de strings de texto livre. Enquanto um log tradicional seria algo como "2026-04-14 10:00:01 ERROR Pedido 12345 falhou: timeout", um log estruturado tem campos nomeados: timestamp, level, service, orderId, error, traceId. Essa diferença aparentemente simples tem impacto enorme na operabilidade do sistema. Com texto livre, buscar todos os erros de um usuário específico exige regex frageis. Com logs estruturados em JSON, e uma consulta simples por userId. Filtrar, agregar, criar alertas e correlacionar com traces distribuídos, tudo fica dramaticamente mais simples quando o log e máquina-legível desde o inicio.

Por que texto livre não escala

Logs de texto precisam de parsing fragil e não permitem consultas eficientes.

O problema com logs de texto livre aparece na escala. Com um único servidor e poucos usuários, um desenvolvedor pode fazer SSH e executar grep para encontrar erros. Mas quando o sistema tem vinte microservicos, cem pods no Kubernetes e processa milhões de eventos por dia, esse abordagem colapsa. Ferramentas de agregação de logs como Elasticsearch precisam parsear o texto para indexa-lo, e esse parsing e lento, fragil e frequentemente errado quando o formato do log muda. Além disso, campos como duration e user_id extraidos de texto livre perdem o tipo correto (número, string) que teriam em JSON. Logs estruturados eliminam o parsing: o campo ja esta la, com o tipo correto, pronto para indexação e consulta eficiente.

Formato JSON para logs

Um log JSON de qualidade tem campos obrigatórios e contexto suficiente para investigação.

Um log estruturado eficiente contem um conjunto mínimo de campos. Timestamp em ISO 8601 com fuso horário (ex: 2026-04-14T10:00:00.000Z) para ordenação correta. Level com o nível de severidade (DEBUG, INFO, WARN, ERROR). Service com o nome do serviço que emitiu o log. TraceId com o identificador da requisição para correlação. Message com a descrição legível do evento. Campos de contexto específicos da operação (orderId, userId, durationMs, statusCode). Em casos de erro, o stack trace dentro de um campo error. Esse formato e diretamente indexável pelo Elasticsearch sem configuração adicional. A chave e decidir quais campos são obrigatórios em todos os logs e garantir que o código os emita consistentemente, independentemente do desenvolvedor que escreve o log.

Niveis de log corretos

Usar o nível errado gera ruido ou cega o sistema a problemas reais.

Os níveis de log tem semanticas bem definidas que muitas equipes ignoram, gerando sistemas com alertas falsos ou problemas silenciosos. DEBUG e para informação detalhada de desenvolvimento, nunca deve aparecer em produção por padrão, pois gera volume massivo e custa caro em storage. INFO e para eventos normais e relevantes do ciclo de vida do negócio: usuário logou, pedido criado, pagamento processado. WARN e para situações anomalas que não causaram falha mas merecem atenção: retry bem-sucedido, configuração ausente com valor default, lentidao acima do esperado. ERROR e para falhas que impactaram o usuário ou operação: exceção não tratada, transação revertida, serviço externo indisponível. Usar ERROR para eventos normais de negócio e um antipadrao que dilui a capacidade de alertar em erros reais.

Correlation ID em microservicos

Um ID único que percorre todos os serviços torna o debugging possível.

Em uma arquitetura de microservicos, uma requisição do usuário passa por múltiplos serviços antes de retornar uma resposta. Sem um identificador comum, correlacionar os logs de todos esses serviços para uma única requisição e impossível. O Correlation ID (também chamado de Trace ID ou Request ID) e um identificador único gerado no ponto de entrada do sistema, geralmente no API gateway ou no primeiro serviço que recebe a requisição. Esse ID e propagado em headers HTTP (ex: X-Correlation-ID, traceparent do OpenTelemetry) para todos os serviços downstream e incluído em todos os logs. Com isso, uma consulta por traceId no Kibana retorna todos os logs de todos os serviços para aquela requisição específica, transformando o debugging de uma cacada em uma busca direta.

Stack ELK para centralização de logs

Elasticsearch, Logstash e Kibana centralizam e tornam logs pesquisáveis.

A stack ELK e a combinação mais popular para centralização de logs. Logstash e um pipeline de ingestão que coleta logs de diversas fontes, os transforma e os envia ao Elasticsearch. Elasticsearch e um banco de busca distribuído que indexa os logs em JSON e permite consultas rápidas por qualquer campo. Kibana e a interface visual que permite buscar, filtrar, visualizar e criar dashboards sobre os logs indexados. Uma alternativa mais leve e o stack EFK: Elasticsearch + Fluentd (ou Fluent Bit, mais leve) + Kibana. Para quem usa AWS, CloudWatch Logs oferece funcionalidade similar sem infraestrutura própria. A stack ELK exige configuração e manutenção, mas oferece flexibilidade total e e gratuita, ideal para equipes que precisam controlar onde os logs ficam armazenados.

Custo e retenção de logs

Logs geram volume massivo, definir política de retenção e fundamental.

Logs podem facilmente se tornar o maior custo de infraestrutura de um sistema. Um microservico que emite 1000 eventos por segundo gera bilhões de logs por dia. Em serviços gerenciados como Datadog ou New Relic, o custo por gigabyte ingerido e significativo. Mesmo com ELK próprio, o storage do Elasticsearch escala com o volume. A estrategia correta e definir uma política de retenção por nível: logs de DEBUG podem ser descartados em 24 horas (ou nem enviados para produção). Logs de INFO, retidos por 7 dias. Logs de WARN e ERROR, por 30 dias. Logs de auditoria de segurança, por 1 ano ou mais por requisito regulatorio. Sampling também ajuda: para requisições de sucesso com alta frequência, armazenar apenas 1% dos logs INFO pode reduzir volume em 99% sem perder informação crítica sobre falhas.

Alertas baseados em logs

Logs estruturados permitem alertas precisos sobre eventos de negócio.

Uma das vantagens mais subestimadas do logging estruturado e a capacidade de criar alertas baseados em padrões de log. Com logs em JSON, e possível alertar quando a taxa de logs de nível ERROR passa de 10 por minuto no serviço de pagamentos, quando um campo específico como payment_gateway="timeout" aparece mais de 5 vezes em 1 minuto, ou quando o tempo de processamento de pedidos (campo duration_ms) ultrapassa 3000 em mais de 1% das requisições. Elasticsearch e Kibana suportam alertas nativamente. Grafana Loki, uma alternativa mais leve para logs, integra alertas diretamente com o Alertmanager do Prometheus. Esses alertas baseados em semântica de negócio, possibilitados pelos campos estruturados do JSON, são mais precisos e accionáveis do que alertas de infraestrutura genéricos.

Campos padrão recomendados

Padronizar campos entre todos os serviços e o que torna os logs consultáveis.

A maior armadilha do logging estruturado e cada serviço inventar seus próprios campos: um chama de userId, outro de user_id, outro de customerId. Isso torna consultas cross-service impossibeis. Definir um schema de campos obrigatórios compartilhado por todos os serviços e o que transforma uma coleção de logs isolados em uma plataforma de observabilidade coerente. Campos recomendados: timestamp (ISO 8601), level, service, traceId, spanId, userId, method (HTTP), path, statusCode, durationMs, error (em falhas). Ferramentas como Serilog no .NET e Logback no Java facilitam a adição desses campos de forma centralizada via enrichers ou MDC, garantindo que todos os logs do serviço incluam o traceId sem que cada desenvolvedor precise lembrar de incluir manualmente.

Resumo final

Logging estruturado e a base para operar sistemas com confianca.

Logging estruturado e uma das melhorias mais baratas e impactantes que uma equipe pode fazer na operabilidade de um sistema. A mudanca de texto livre para JSON não exige reescrever a aplicação, apenas configurar a biblioteca de logging corretamente. O retorno e imediato: debugging mais rápido, alertas mais precisos, correlação com traces distribuídos e consultas eficientes no Kibana ou equivalente. O investimento em definir um schema de campos padronizados para todos os serviços paga dividendos toda vez que um problema de produção precisa ser investigado. Em sistemas distribuídos, logging estruturado com Correlation ID e o que torna o debugging de uma requisição específica uma busca de 30 segundos em vez de uma investigação de 3 horas.