O Que É Structured Logging? Logs Legíveis por Máquina Explicados
Structured logging significa emitir entradas de log como dados chave-valor legíveis por máquina, normalmente JSON, em vez de strings de texto de forma livre.
A diferença entre um log que você pode inspecionar com grep e um log que você pode consultar é a estrutura. Structured logging trata cada linha de log como dados com campos nomeados, o que permite que sistemas de logging filtrem, agreguem e correlacionem em escala. É a prática que transforma logs de um último recurso em um sinal analítico de primeira classe.
Logs de texto vs logs estruturados
Uma linha de log tradicional comprime tudo em uma frase de prosa. Um log estruturado registra a mesma informação como campos discretos, como um level, uma mensagem, um user ID e uma duração, em um formato como JSON. O conteúdo é o mesmo; a diferença é que uma máquina pode extrair de forma confiável qualquer campo.
Por que a estrutura importa
Uma vez que os logs estão estruturados, você pode fazer perguntas precisas: mostre todo erro de um cliente, conte falhas por código de erro ou calcule a duração média de uma operação. Com texto não estruturado, essas perguntas exigem correspondência de padrões frágil. A estrutura é o que faz de um backend de logging um mecanismo de consulta em vez de uma caixa de busca.
Campos consistentes e contexto
O ganho cresce quando os campos são consistentes entre serviços. Um request ou trace ID compartilhado anexado a cada linha de log permite seguir uma requisição por vários componentes, e propriedades como environment ou versão permitem fatiar os logs do mesmo modo que você fatia métricas. Essa consistência é o que habilita a correlação entre logs, traces e métricas.
Structured logging em CI/CD
Quando os passos do pipeline emitem logs estruturados, com campos para o job, o commit, o runner e o resultado, você pode pesquisar em milhares de execuções de uma só vez. Isso torna prático detectar um padrão de falha que aparece de forma intermitente ao longo de muitos builds, em vez de ler um log de job por vez torcendo para percebê-lo.
Adotando
A maioria das linguagens tem bibliotecas de structured logging que cuidam da codificação para você. A principal disciplina é escolher nomes de campo de forma consistente e evitar valores de alta cardinalidade ou sensíveis nos campos. Bem feito, structured logging custa pouco para adotar e recompensa toda vez que você precisa investigar um incidente.
Principais conclusões
- Structured logging emite logs como dados chave-valor, não como prosa.
- Torna os logs filtráveis e agregáveis por máquinas.
- Campos consistentes como trace IDs permitem correlação entre sinais.
- Em CI/CD, permite pesquisar padrões de falha ao longo de muitas execuções.