Noções Básicas de Observabilidade

8 exemplos para você começar com Observabilidade para backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

Fixe o Node 24.18.0 e carregue o SDK OTel antes de outras importações nos pontos de entrada de produção.

Exemplos Básicos

1. Três Pilares em Uma Requisição

Logs, métricas e traces descrevem o mesmo incidente de ângulos diferentes.

// Log (Pino)
logger.info({ requestId, statusCode: 200, durationMs: 45 }, "request_complete");
 
// Métrica (contador)
requestCounter.add(1, { method: "GET", route: "/users", status: "200" });
 
// Trace (atributo de span)
span.setAttribute("http.status_code", 200);

• Logs: eventos discretos com contexto - ótimos para depurar uma falha.
• Métricas: agregações ao longo do tempo - ótimas para SLOs e alertas.
• Traces: detalhamento de latência entre serviços - ótimos para requisições lentas.

Relacionado: Métricas que Importam - método RED

2. Endpoints de Health vs Readiness

Liveness e readiness servem a diferentes sondas do orquestrador.

app.get("/health", (_req, res) => res.json({ ok: true }));
 
app.get("/ready", async (_req, res) => {
  const dbOk = await db.ping();
  res.status(dbOk ? 200 : 503).json({ ready: dbOk });
});

• /health - processo ativo (liveness). Sem verificações de dependência.
• /ready - pode servir tráfego (readiness). Falha quando o DB está indisponível.
• Não registre falhas de readiness com error a cada sonda do kube - amostre ou use métricas.

Relacionado: Noções Básicas de Resiliência - falhe rápido ao iniciar

3. Esboço de Métricas RED

Taxa (Rate), Erros (Errors), Duração (Duration) - métricas mínimas de serviço HTTP.

import { metrics } from "@opentelemetry/api";
 
const meter = metrics.getMeter("orders-api");
const requestDuration = meter.createHistogram("http.server.duration", { unit: "ms" });
const requestCount = meter.createCounter("http.server.requests");
 
function recordRequest(method: string, route: string, status: number, ms: number) {
  requestCount.add(1, { method, route, status: String(status) });
  requestDuration.record(ms, { method, route, status: String(status) });
}

• Taxa - contador http.server.requests.
• Erros - mesmo contador filtrado por status=5xx.
• Duração - histograma para p50/p95/p99 no Prometheus ou Datadog.

Relacionado: SLOs e Orçamentos de Erro - SLO a partir de histogramas

4. Log Estruturado com trace_id

Correlacione logs a traces em UIs de APM.

import { trace } from "@opentelemetry/api";
 
const span = trace.getActiveSpan();
const traceId = span?.spanContext().traceId;
 
logger.info({ trace_id: traceId, event: "payment_captured" }, "payment ok");

• Muitas ferramentas de APM conectam linhas de log à cascata de trace por trace_id.
• Use um nome de campo consistente (trace_id) entre os serviços.
• O mixin do Pino pode injetar o trace_id automaticamente.

Relacionado: IDs de Correlação de Requisição - requestId vs trace_id

5. Contador para Eventos de Negócios

Métricas não são apenas HTTP - rastreie eventos de domínio.

const ordersCreated = meter.createCounter("orders.created");
ordersCreated.add(1, { plan: "pro", region: "eu" });

• Contadores de negócios alimentam dashboards de produto, não apenas de operações.
• Apenas rótulos de baixa cardinalidade - não userId em cada métrica.
• Combine com logs para depuração de pedidos individuais.

Relacionado: Noções Básicas de Logging - nomenclatura de campos de evento

6. Span para Instrumentação Manual

A auto-instrumentação perde os limites da sua lógica de negócios.

import { trace } from "@opentelemetry/api";
 
const tracer = trace.getTracer("billing");
 
async function capturePayment(orderId: string) {
  return tracer.startActiveSpan("capturePayment", async (span) => {
    span.setAttribute("order.id", orderId);
    try {
      return await stripeCapture(orderId);
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: 2 });
      throw err;
    } finally {
      span.end();
    }
  });
}

• Nomeie spans com base nas operações (capturePayment), não nos detalhes internos da função.
• recordException anexa o erro ao trace para rastreamento de erros em APM.
• Termine spans em finally - evite spans vazados em retornos antecipados.

Relacionado: OpenTelemetry Node SDK - configuração do SDK

Exemplos Intermediários

7. Bootstrap Mínimo do SDK OTel

Carregue a instrumentação antes das importações do Express/Fastify.

// src/instrumentation.ts - importe primeiro em main.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

• instrumentation.ts deve carregar antes de import express no arquivo de entrada.
• O exportador OTLP HTTP envia para o coletor sidecar (4318) ou agente SaaS.
• A auto-instrumentação cobre HTTP, fetch e drivers de banco de dados comuns.

Relacionado: OpenTelemetry Node SDK - configuração completa

8. Alerte sobre Sintomas, Não Logs

Notifique sobre queima de SLO, não sobre cada stack trace.

# Regra de alerta pseudo
alert: HighErrorRate
expr: rate(http_server_requests{status=~"5.."}[5m]) / rate(http_server_requests[5m]) > 0.05
for: 10m

• Sintoma: taxa elevada de 5xx durante 5 minutos.
• Não: linha de log ERROR única de um reinício de pod.
• Vincule alertas a SLOs e Orçamentos de Erro.

Relacionado: Melhores Práticas de Observabilidade - regras de alerta

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.