Logs na Observabilidade: o que são, tipos e como implementar

Se a métrica diz “o sistema está lento” e o trace diz “a lentidão está no banco de dados”, é o log que diz “o erro foi causado por um deadlock na tabela de transações às 14:32:07.483”. No tripé da observabilidade, os logs são a verdade granular e imutável sobre o que aconteceu — a fonte primária de evidência em qualquer diagnóstico de incidente.

Logs são o pilar mais antigo da observabilidade. Muito antes de métricas e traces existirem como conceitos formais, sistemas já escreviam logs. O desafio em ambientes distribuídos modernos não é gerar logs — é gerá-los de forma consistente, estruturada e correlacionável com os outros dois pilares.

Este guia técnico explica o que são logs no contexto da observabilidade moderna, os principais tipos, como estruturar logs de qualidade e como o padrão OpenTelemetry resolve o problema de correlação entre pilares.

O que são logs?

Logs são registros imutáveis com timestamp de eventos que ocorreram em um sistema. Cada linha de log documenta um momento específico: uma requisição recebida, uma exceção lançada, uma transação completada ou uma conexão encerrada.

Diferentemente das métricas — que agregam valores ao longo do tempo — e dos traces — que mapeiam o caminho de uma requisição — os logs capturam o contexto completo de um evento individual. São a fonte de detalhe quando métricas e traces apontam onde está o problema mas não explicam exatamente o que aconteceu.

Tipos de logs

Logs não estruturados (texto livre)

O formato mais antigo e ainda mais comum. Cada linha é texto em formato livre, legível por humanos mas difícil de processar por máquinas. Exemplo: 2024-03-15 14:32:07 ERROR Database connection failed: timeout after 30s.

O problema com logs não estruturados é que extrair informações específicas exige regex complexo. Em ambientes com alto volume de logs, isso se torna um gargalo operacional crítico.

Logs estruturados (JSON)

O padrão moderno. Cada evento é representado como um objeto JSON com campos consistentes: timestamp, nível de severidade, serviço de origem, mensagem e contexto adicional. Exemplo:

{"timestamp":"2024-03-15T14:32:07.483Z","level":"ERROR","service":"payment-api","trace_id":"abc123","duration_ms":30000}

Logs estruturados são diretamente ingeríveis por plataformas de gerenciamento de logs, permitem filtragem precisa por campo e viabilizam a correlação com traces pelo campo trace_id.

Logs de eventos

Registros de ações discretas com significado de negócio: um usuário fez login, um pagamento foi processado, uma configuração foi alterada. São distintos dos logs de aplicação porque representam fatos sobre o domínio, não sobre a execução técnica. São a base de auditoria e compliance.

Como logs se integram ao tripé da observabilidade

A correlação entre os três pilares é o que transforma dados isolados em diagnóstico completo. O padrão OpenTelemetry resolve essa correlação ao propagar um trace_id único por toda a requisição e injetá-lo nos logs gerados durante aquela execução.

Isso significa que, diante de um incidente, o engenheiro consegue partir de um alerta de métrica (latência elevada), abrir o trace da requisição afetada (para ver onde o atraso ocorreu) e então filtrar os logs exatamente daquele trace (para ver a mensagem de erro específica). Os três pilares se tornam navegáveis como um grafo conectado, não como silos separados.

A referência técnica para implementação de logs correlacionados é a especificação de Logs do OpenTelemetry, que define os campos semânticos obrigatórios e o formato de exportação compatível com qualquer backend de observabilidade.

Boas práticas de logging para observabilidade

O primeiro princípio é a consistência de campos. Todo log do sistema deve ter os mesmos campos obrigatórios: timestamp em UTC com milissegundos, nível de severidade padronizado (DEBUG, INFO, WARN, ERROR, FATAL), nome do serviço e trace_id quando disponível.

O segundo é o nível de detalhe adequado. Logs de ERROR devem incluir o stack trace completo e o contexto da operação que falhou. Logs de DEBUG devem ser ativados sob demanda — nunca em produção por padrão, pois o volume destrói a relação sinal/ruído.

O terceiro é a exclusão de dados sensíveis. Logs nunca devem conter senhas, tokens de acesso ou dados pessoais identificáveis. Filtros de sanitização no pipeline de exportação são a abordagem mais confiável para garantir esse controle.

Conclusão

Logs são o pilar de detalhe da observabilidade. Enquanto métricas revelam que algo está errado e traces mostram onde, os logs explicam exatamente o quê aconteceu, com contexto completo e timestamp preciso. Em ambientes modernos, a diferença entre logs úteis e logs inúteis está na estruturação, na consistência de campos e na correlação com os outros pilares pelo trace_id.

A adoção do padrão OpenTelemetry para instrumentação de logs é o caminho mais sólido para garantir correlação automática e compatibilidade com qualquer plataforma de observabilidade. Para estruturar sua estratégia de logging e observabilidade, fale com nossos especialistas.