OpenTelemetry: Unificando Métricas, Logs e Traces

1. O que é OpenTelemetry?

Padrão aberto (CNCF) para gerar, coletar e exportar métricas, logs e traces. Instrumente uma vez e envie para qualquer backend (Prometheus, Loki, Tempo, Jaeger, etc.).

2. Os três pilares

• Métricas — números agregados (latência p99, taxa de erro)
• Logs — eventos discretos com contexto
• Traces — caminho de uma requisição entre serviços (spans)

O poder está em correlacionar os três via trace_id / request_id.

3. SDK + Collector

A app usa o SDK (ou auto-instrumentação) e exporta OTLP para o Collector. O Collector processa (batch, filter, sample) e exporta para os backends.

4. Instrumentação (Node.js)

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Python, Java, Go e .NET seguem o mesmo padrão: SDK + exporter OTLP.

5. Collector

receivers:
  otlp:
    protocols:
      grpc:
      http:
processors:
  batch:
exporters:
  otlp/tempo:
    endpoint: tempo:4317
  prometheus:
    endpoint: "0.0.0.0:8889"
  loki:
    endpoint: http://loki:3100/loki/api/v1/push
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [loki]

6. Grafana

• Prometheus → métricas e alertas
• Loki → logs (LogQL)
• Tempo/Jaeger → traces

Configure as três data sources e use correlação (métrica → trace → logs).

7. Boas práticas

• Semantic conventions (http.method, http.status_code…)
• Propagar contexto entre serviços
• Sampling inteligente em produção
• Collector próximo das apps (sidecar/DaemonSet)
• Config do Collector como código

OTel não é “mais uma ferramenta”: é o padrão que unifica instrumentação e permite trocar de backend. Combinado com Grafana/Prometheus/Loki/Tempo, forma base sólida de observabilidade.

8. Configurações explicadas

Instrumentação em Node.js

Esse código precisa rodar antes do restante da aplicação, para conseguir instrumentar as bibliotecas. Uma forma usual é colocá-lo em tracing.js e iniciar com node --require ./tracing.js app.js.

Collector

9. Configuração por variáveis de ambiente

O SDK também aceita variáveis padronizadas, o que evita deixar endereços no código:

OTEL_SERVICE_NAME=api-pedidos
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
node --require ./tracing.js app.js

OTEL_SERVICE_NAME dá nome ao serviço nos gráficos. Sem ele, os dados aparecem como unknown_service.

10. Erros comuns e como resolver