Logs se tornam valiosos quando ajudam um engenheiro a responder rapidamente a uma pergunta de produção. Um grande volume de mensagens sem estrutura raramente alcança esse objetivo. A base de um logging útil é um modelo compartilhado de eventos, contexto consistente e controles explícitos para dados sensíveis.
Logging estruturado não significa envolver qualquer frase em JSON. Significa emitir campos estáveis, legíveis por máquinas e com significado compreendido entre serviços.
Projete um schema de eventos
Um evento prático costuma incluir:
- timestamp e severidade;
- serviço, ambiente e versão;
- nome e resultado do evento;
- identificadores de trace e span;
- identificador de request ou correlação;
- identificadores de negócio seguros quando realmente necessários;
- tipo do erro e mensagem sanitizada;
- versão do schema.
O trace_id deve vir do trace distribuído ativo. Criar um valor novo em cada linha destrói a correlação. Quando a requisição chega sem um contexto válido, a camada de instrumentação deve criar o trace uma vez e propagá-lo às chamadas seguintes.
Nomes devem descrever o ocorrido: payment.authorization.failed é mais útil que Something went wrong. Texto livre pode permanecer para leitura humana, mas consultas e alertas devem depender de campos estáveis.
Mantenha dados sensíveis fora dos logs
Logs são copiados, indexados, retidos e acessados por muitas ferramentas. Por isso, são um lugar inadequado para credenciais, tokens, cookies de sessão, corpos completos de requisição, dados de pagamento ou informações pessoais desnecessárias.
Prefira uma allowlist de campos permitidos em vez de tentar remover todos os campos perigosos depois. Quando identificadores forem necessários, use referências de escopo limitado, hashing quando apropriado e retenção alinhada à finalidade. A remoção de dados deve ser testada como qualquer outro controle de segurança.
Controle cardinalidade e custo
Campos de alta cardinalidade podem tornar plataformas de observabilidade lentas e caras. Nem todo valor pertence a uma label indexada. Trace IDs, IDs de usuário e URLs brutas podem ser úteis na busca, mas são perigosos como labels de métricas. Separe o modelo de eventos de log do modelo de métricas.
Sampling também exige intenção. Eventos de debug podem ser amostrados agressivamente; auditoria e erros raros talvez exijam captura completa. Limites de taxa devem proteger a aplicação e o pipeline durante tempestades de falhas.
Conecte logs, métricas e traces
Logs explicam eventos individuais, métricas revelam tendências e traces mostram o caminho da requisição. Eles funcionam melhor juntos. A propagação de contexto do OpenTelemetry conecta esses sinais sem criar um mecanismo de correlação diferente para cada serviço.
Um alerta deve começar em um sintoma — latência ou taxa de erros elevada — e levar o operador aos traces e eventos relevantes. Se for necessário reconstruir identificadores manualmente em três sistemas durante um incidente, o design está incompleto.
Trate o schema como contrato
Documente campos obrigatórios, valide-os em testes e evolua-os com uma versão explícita. Ofereça bibliotecas ou middleware compartilhados para que cada equipe não resolva propagação e proteção de dados de forma diferente.
Teste também a falha: o que acontece quando o collector fica indisponível? O logging bloqueia a requisição? Existe buffer? O que é descartado primeiro? Um sistema que causa uma indisponibilidade enquanto relata outra falhou em sua responsabilidade principal.
Padronizar logs não é produzir mais dados. É criar evidência confiável: segura para reter, consistente para consultar e conectada o suficiente para encurtar o caminho entre sintoma e causa.
Referência
O modelo de dados de logs do OpenTelemetry define campos estáveis, semântica de severidade e correlação com contexto de traces.