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

Autor: Pedro Tebaldi PM do KeepGreen| Revisão técnica: Ednilson Correa SRE

Publicado dez/2025Atualizado set/2026

A métrica diz que o sistema está lento. O trace mostra que a lentidão está no banco de dados. Já o log diz que o erro veio de um deadlock na tabela de transações às 14:32:07.483. Ou seja, no tripé da observabilidade, os logs são a verdade granular e imutável sobre o que aconteceu.

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, mas gerá-los de forma consistente, estruturada e correlacionável com os outros dois pilares.

Este guia técnico explica o que são logs, os principais tipos e como estruturar logs de qualidade. Depois disso, mostra como o padrão OpenTelemetry resolve a correlação entre pilares. Além disso, os números desta página saíram de um laboratório próprio, descrito ao longo do texto.

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.

Enquanto as métricas agregam valores ao longo do tempo, os traces mapeiam o caminho de uma requisição. Já 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, sem explicar o que aconteceu.

Tipos de logs

Logs não estruturados (texto livre)

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

Num teste com 50.000 eventos, a extração por expressão regular levou 11 ms. O parse de JSON levou 62 ms. A regex ganha por folga larga. O gargalo do texto livre não está na velocidade.

Acontece que a regex depende da frase, que muda sem aviso. Quando um serviço troca respondeu 200 em por status=200 apos, a mesma expressão encontra zero ocorrências entre 5.000 eventos. No entanto, nenhum erro aparece: o painel apenas mostra um número menor.

Logs estruturados (JSON)

JSON é o padrão moderno. Cada evento vira um objeto com campos consistentes: timestamp, nível de severidade, serviço de origem, mensagem e contexto adicional. Por 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. Além disso, permitem filtragem precisa por campo e viabilizam a correlação com traces pelo campo trace_id.

A objeção comum ao JSON é o custo de armazenamento. Para medir isso, o laboratório serializou os mesmos 50.000 eventos nas duas formas. Em seguida, comprimiu tudo com gzip nível 6, em 3 de setembro de 2026:

# 50.000 eventos identicos, serializados nas duas formas
node lab/mede-volume.cjs

texto livre        bruto  8,83 MB   185,2 B/evento   gzip 2,41 MB   razao 3,7:1
JSON estruturado   bruto 17,54 MB   367,9 B/evento   gzip 2,73 MB   razao 6,4:1

# extracao do status HTTP dos mesmos 50.000 eventos
regex sobre texto livre :  11 ms
parse do JSON + campo   :  62 ms

# um servico troca "respondeu 200 em" por "status=200 apos" (5.000 eventos)
a mesma regex encontra  :  0 deles
o campo JSON encontra   :  5.000

Em bruto, o JSON dobra o volume: 367,9 bytes por evento contra 185,2 do texto livre. Depois do gzip, porém, a diferença cai para 13%. Campo repetido comprime bem: a razão sobe de 3,7:1 para 6,4:1.

Por isso o argumento de custo contra log estruturado costuma ignorar o compressor. Em resumo, o texto livre é mais barato e mais rápido de ler. Já o JSON continua funcionando quando o formato da mensagem muda.

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. Formam 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. Esse identificador entra nos logs gerados durante aquela execução.

Diante de um incidente, o engenheiro parte de um alerta de métrica com latência elevada. Em seguida, abre o trace da requisição afetada e filtra os logs exatamente daquele trace. Dessa forma, os três pilares ficam navegáveis como um grafo conectado, não como silos separados.

A referência técnica é o modelo de dados de Logs do OpenTelemetry. Ele 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 carregar o mesmo conjunto obrigatório, com os nomes da convenção semântica do OpenTelemetry. A tabela abaixo traz o que cada campo faz e o que acontece quando ele falta.

Nível de detalhe e o que nunca entra no log

O segundo princípio é 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 precisam de ativação sob demanda, nunca em produção por padrão, porque o volume destrói a relação entre sinal e ruído.

Por fim, dado sensível nunca entra no log. Senha, token de acesso e dado pessoal identificável ficam de fora. O filtro no pipeline de exportação é o ponto mais confiável para esse controle, contudo ele só remove aquilo que você descreveu.

A armadilha de cardinalidade

Rótulo não é campo. No backend de logs, cada combinação distinta de rótulos cria um stream próprio, com índice e memória próprios. Colocar trace_id como rótulo parece organização, mas gera uma série por evento.

Para medir o tamanho do erro, os mesmos 2.000 eventos entraram no Grafana Loki 3.7.7 duas vezes, mudando apenas a escolha de rótulos:

# certo: rotulo so com valor de conjunto fechado
{app="loja", service_name="auth-api", level="WARN"}
  streams criados : 20            push -> HTTP 204

# errado: trace_id como rotulo, uma serie por evento
{app="loja", service_name="auth-api", level="WARN", trace_id="a16e540a..."}
  eventos aceitos : 100 de 2.000    push -> HTTP 429

maximum active stream limit exceeded when trying to create stream
{...}, reduce the number of active streams (reduce labels or reduce
label values), or contact your Loki administrator to see if the
limit can be increased

Com {app, service_name, level} saíram 20 streams para 2.000 eventos. No entanto, com o trace_id junto, o Loki aceitou 100 eventos e recusou os outros 1.900 com HTTP 429.

O limite deste laboratório é baixo de propósito, com max_streams_per_user em 200. Ainda assim, a forma da falha é a mesma em produção: a ingestão para de aceitar, em vez de ficar lenta. A documentação de cardinalidade do Loki trata o caso como erro de modelagem, não como limite a aumentar.

Portanto, a regra prática é direta. Rótulo serve para valor de conjunto fechado, como serviço, ambiente e nível. Identificador de alta cardinalidade vai no corpo da linha, onde continua pesquisável sem criar série nova.

O filtro só pega o que você descreveu

Para mostrar onde o filtro falha, o mesmo evento passou por três pipelines do OpenTelemetry Collector 0.160.0. São eles: sem filtro, apenas com o processor redaction e com redaction mais uma regra transform por chave.

# sem filtro
body: falha ao autenticar cliente 529.482.311-07 <ana.souza@cliente.com.br> senha=Trocar@2026

# so o processor redaction
body: falha ao autenticar cliente **** <****> senha=Trocar@2026

# redaction + transform com regra por chave
body: falha ao autenticar cliente **** <****> senha=[REDIGIDO]

O processor de redação do Collector mascarou CPF, e-mail e cartão, tanto no atributo quanto no corpo. Ou seja, os três têm formato reconhecível por expressão regular.

Já a senha passou intacta pelo mesmo filtro. O valor Trocar@2026 não casa com nenhum padrão de valor, porque senha não tem formato. Logo, a regra precisa ser pela chave, com replace_pattern sobre senha=, password= e token=.

Vale o cuidado de escrita: a configuração aceita a expressão regular em dois dialetos. Em blocked_values vai aspas simples com barra simples. Dentro do transform vai aspas duplas com barra dobrada. Além disso, o erro de boot não diz qual regra está errada.

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 o que aconteceu, com contexto completo e timestamp preciso. Portanto, a diferença entre logs úteis e inúteis está na estruturação, na consistência de campos e na correlação pelo trace_id.

O laboratório desta página mostra que as três decisões caras aparecem cedo. Timestamp ausente desloca o evento no tempo, rótulo de alta cardinalidade derruba a ingestão e filtro por valor deixa a senha passar. No entanto, nenhuma delas dá erro no dia em que é tomada.

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