1 O que você ganha ao combinar OpenTelemetry + Prometheus

OpenTelemetry padroniza como instrumentar aplicações e coletar sinais (traces, métricas e logs).
Já o Prometheus é um motor de métricas com modelo de coleta por scrape, ótimo para alertas e
painéis baseados em séries temporais.

Quando a instrumentação é bem feita, você consegue navegar do alerta para a causa raiz:
um spike de erro aparece no Prometheus, e o trace mostra exatamente onde a cadeia quebrou.

2 Arquitetura recomendada: coleta, exportação e ingestão

Em ambientes reais, a arquitetura mais estável costuma separar
instrumentação da aplicação do tráfego e transformações do backend.
Com OpenTelemetry, você normalmente passa por um Collector que centraliza decisões e exporta para destinos diferentes.

Um ponto operacional importante: métricas tendem a exigir consistência.
Nomes, rótulos (labels) e cardinalidade precisam estar sob controle desde o desenho.
Traces toleram mais variação, mas ainda exigem disciplina nos atributos essenciais.

3 Instrumentação com métricas: nomes, labels e cardinalidade

Métrica é “contrato”. Eu sigo um conjunto de práticas para manter o sistema saudável:
evitar explosão de labels, reduzir custo de armazenamento e manter queries simples.

Nomes

• Prefira prefixos e unidades consistentes (ex.: http_server_request_duration_seconds).
• Use convenções de semântica (contador, histograma, gauge) de forma correta.

Labels

• Use labels que “agregam” investigação: service.name, http.method, http.status_code.
• Evite labels com alta cardinalidade como IDs de usuário, tokens, URLs completas com parâmetros variáveis.
• Para rotas, prefira template (ex.: /users/{id}) ao invés de caminho literal.

Cardinalidade e custo

Prometheus armazena séries por combinação de labels. Se você injeta um label de alta cardinalidade,
você transforma observabilidade em um problema de escala.
Eu sempre reviso: “qual consulta eu preciso fazer, e quais labels são realmente necessários para isso?”

4 Exemplo técnico: Collector exportando métricas para Prometheus

Abaixo vai um exemplo realista de configuração do OpenTelemetry Collector para receber OTLP,
processar recursos e exportar métricas via Prometheus.
Ajuste nomes/portas de acordo com seu ambiente.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
  batch: {}

  # Opcional: reduza/normalize atributos (mantém consistência e controla cardinalidade).
  # Exemplo simples: limite de atributos não essenciais.
  attributes:
    actions:
      - key: service.instance.id
        action: delete
      - key: k8s.pod.uid
        action: delete

exporters:
  prometheus:
    endpoint: 0.0.0.0:9464
    # Quando habilitado, o Collector expõe um endpoint /metrics para o Prometheus fazer scrape.
    # As métricas exportadas devem vir como MetricData do pipeline do OTel.

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch, attributes]
      exporters: [prometheus]

Agora, no Prometheus, você aponta para o endpoint do Collector.
A ideia é simples: o Prometheus faz scrape no endereço do Collector, e o resto do ecossistema
consome as métricas normalmente.

scrape_configs:
  - job_name: 'otel-collector'
    scrape_interval: 15s
    static_configs:
      - targets: ['collector:9464']

O que verificar depois de colocar em produção:

• Consistência dos nomes das métricas e dos labels entre serviços.
• Cardinalidade (quantas séries estão sendo criadas) antes de escalar carga.
• Latência de observabilidade: tempo entre gerar evento e aparecer no Prometheus.
• Erros do pipeline: se o Collector estiver descartando dados, você precisa entender por quê.