Observabilidade com OpenTelemetry: logs, métricas e traces

Quando um serviço fica lento às três da manhã, a pergunta que define o tempo de resolução não é "está no ar?", mas "por quê?". Sistemas distribuídos modernos — microsserviços, filas, caches, múltiplos bancos — tornam essa segunda pergunta difícil de responder com dashboards estáticos. É aí que a conversa migra de monitoramento para observabilidade, e é aí que o OpenTelemetry entra como peça central.

Monitoramento vs. observabilidade

Os dois termos costumam ser tratados como sinônimos, mas resolvem problemas diferentes.

Monitoramento parte de perguntas conhecidas. Você sabe de antemão o que pode dar errado — CPU alta, taxa de erro 5xx, latência acima de um limite — e cria alertas e gráficos para essas hipóteses. É excelente para os "known unknowns".

Observabilidade é a propriedade de um sistema que permite inferir seu estado interno a partir dos dados que ele emite, sem precisar antecipar cada falha possível. O foco está nos "unknown unknowns": problemas que você não previu e, portanto, não tem um dashboard pronto para eles. Em vez de só responder "o erro aumentou?", você consegue perguntar "quais requisições falharam, para qual cliente, em qual versão do serviço, atravessando quais dependências?" — e fatiar os dados por essas dimensões em tempo de investigação.

A distinção é prática: monitoramento te avisa que algo quebrou; observabilidade te ajuda a descobrir o motivo, especialmente quando a causa é nova.

Os três pilares

A observabilidade costuma ser apoiada em três tipos de telemetria que se complementam.

Logs são registros discretos de eventos, idealmente estruturados (JSON) em vez de texto livre. Respondem "o que aconteceu neste ponto exato do código". São ricos em detalhe, mas caros de armazenar e difíceis de correlacionar sozinhos.

Métricas são agregações numéricas ao longo do tempo: contadores, gauges, histogramas. Respondem "qual é a magnitude e a tendência" — requisições por segundo, latência no percentil 99, uso de memória. São baratas, eficientes para alertar e ótimas para visão macro, mas perdem o detalhe individual de cada evento.

Traces mostram o caminho de uma requisição através de todos os serviços que ela toca. Respondem "por onde passou e onde gastou tempo". Um trace é composto de spans, e cada span representa uma unidade de trabalho (uma chamada HTTP, uma query no banco) com timestamp de início, duração, atributos e relação pai-filho com outros spans.

Isoladamente, cada pilar tem pontos cegos. O valor real aparece na correlação: uma métrica dispara um alerta, o trace daquela requisição lenta mostra qual span demorou, e os logs daquele span revelam a exceção. Para isso funcionar, os sinais precisam compartilhar identificadores comuns — e é exatamente o problema que o OpenTelemetry resolve.

OpenTelemetry: instrumentação vendor-neutral

OpenTelemetry (OTel) é um projeto da CNCF (Cloud Native Computing Foundation), resultado da fusão dos projetos OpenTracing e OpenCensus. É consistentemente apontado como um dos projetos mais ativos do ecossistema CNCF, normalmente o segundo em volume de atividade, atrás apenas do próprio Kubernetes.

A proposta central é separar a instrumentação do backend de análise. Antes do OTel, instrumentar a aplicação com o agente da ferramenta X te prendia à ferramenta X. Trocar de fornecedor significava reinstrumentar tudo. O OTel oferece um conjunto único e padronizado de APIs, SDKs e um protocolo de transporte (OTLP) para gerar e exportar logs, métricas e traces. A aplicação fala OTel; para onde os dados vão — Jaeger, Prometheus, ou qualquer backend compatível, comercial ou open source — é uma decisão de configuração, não de código.

Na prática você instrumenta uma vez e exporta para onde quiser. O exemplo abaixo, em Python, cria um span manualmente:

from opentelemetry import trace

tracer = trace.get_tracer("checkout-service")

def processar_pedido(pedido_id, itens):
    with tracer.start_as_current_span("processar_pedido") as span:
        span.set_attribute("pedido.id", pedido_id)
        span.set_attribute("pedido.itens", len(itens))
        cobrar_pagamento(pedido_id)  # cria spans-filho automaticamente

Boa parte da instrumentação nem precisa ser manual: existem bibliotecas de auto-instrumentação que interceptam frameworks web, clientes HTTP e drivers de banco populares, gerando spans sem alterar o código de negócio.

Context propagation: a cola dos traces

O recurso que faz um trace atravessar serviços é a propagação de contexto. Quando o serviço A chama o serviço B, ele precisa transmitir o trace_id (identificador do trace inteiro) e o span_id atual para que B crie seus spans como filhos do span de A, e não como um trace novo e desconexo.

O OTel faz isso injetando esse contexto nos cabeçalhos da requisição, seguindo o padrão W3C Trace Context — uma recomendação oficial do W3C que define o header traceparent:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Esse cabeçalho carrega quatro campos: versão, trace ID, span ID pai e flags. Como é um padrão aberto e independente de fornecedor, serviços instrumentados com SDKs diferentes ainda conseguem participar do mesmo trace distribuído. Sem propagação de contexto, você teria spans soltos; com ela, monta-se a árvore completa da requisição ponta a ponta.

Por onde começar

OTel não exige um big bang. Um caminho pragmático:

1. Comece pelos traces no fluxo mais crítico — eles dão o maior ganho inicial de visibilidade em sistemas distribuídos.
2. Use auto-instrumentação para cobrir frameworks e bibliotecas sem reescrever código.
3. Adote o OpenTelemetry Collector como camada intermediária: a aplicação envia tudo a ele, e o Collector processa, faz sampling e roteia para os backends — desacoplando ainda mais a app das ferramentas.
4. Garanta que logs, métricas e traces compartilhem trace_id para permitir correlação real.

A grande vitória do OpenTelemetry não é técnica e sim estratégica: ele transforma observabilidade em uma decisão de arquitetura aberta, e não em um contrato de aprisionamento com um fornecedor. Você instrumenta uma vez, no padrão da indústria, e mantém a liberdade de escolher e trocar de backend conforme custo, escala e necessidade evoluem.