OpenTelemetry Node SDK

Q: Quais pacotes instalar?

@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, exportadores OTLP, @opentelemetry/api para spans manuais.

Q: Jaeger Local?

Execute o collector com o receptor OTLP em 4318. Aponte OTEL_EXPORTER_OTLP_ENDPOINT para lá.

Q: NestJS?

opentelemetry-instrumentation-nestjs-core ou spans manuais em interceptadores. Ainda carregue o SDK primeiro em main.ts.

Q: Workers BullMQ?

service.name separado (por exemplo, orders-worker). Inicie o SDK no ponto de entrada do worker da mesma forma que o HTTP.

Instrumente serviços Node.js 24 com o OpenTelemetry Node SDK - auto-instrumente drivers HTTP e de banco de dados, exporte traces OTLP e adicione spans manuais para lógica de negócios.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// src/instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({ [ATTR_SERVICE_NAME]: "orders-api" }),
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

// src/main.ts
import "./instrumentation.js";
import { startServer } from "./server.js";
startServer();

Quando usar isso:

Precisa de traces distribuídos entre microsserviços.
Depurando latência p99 com visualizações em cascata no Honeycomb/Datadog/Jaeger.
Padronizando a instrumentação antes de escolher um fornecedor de APM.
Substituindo o tempo console.time ad-hoc em produção.

Exemplo de Trabalho

// instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { Resource } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? "orders-api",
    [ATTR_SERVICE_VERSION]: process.env.APP_VERSION ?? "0.0.0",
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
    }),
    exportIntervalMillis: 60_000,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      "@opentelemetry/instrumentation-fs": { enabled: false },
    }),
  ],
});
 
sdk.start();
 
process.on("SIGTERM", () => sdk.shutdown());

// server.ts
import express from "express";
import { trace } from "@opentelemetry/api";
 
const app = express();
const tracer = trace.getTracer("orders");
 
app.get("/orders/:id", async (req, res) => {
  await tracer.startActiveSpan("loadOrder", async (span) => {
    span.setAttribute("order.id", req.params.id);
    const order = await db.findOrder(req.params.id);
    res.json(order);
  });
});
 
app.listen(3000);

O que isso demonstra:

Atributos de recurso identificam o serviço no backend de traces.
Endpoints OTLP separados para traces e métricas (comum em collectors).
Instrumentação FS desabilitada para reduzir ruído.
sdk.shutdown() gracioso em SIGTERM descarrega spans pendentes.

Mergulho Profundo

Como Funciona

O SDK registra tracers e meters no @opentelemetry/api global.
A auto-instrumentação aplica patches em http, https, fetch, pg, ioredis, etc. no momento do require.
Spans são exportados via OTLP (OpenTelemetry Protocol) para o collector ou agente.
O cabeçalho W3C traceparent propaga o contexto para chamadas HTTP downstream.

Variáveis de Ambiente

Variável	Propósito
`OTEL_SERVICE_NAME`	Atributo de recurso `service.name`
`OTEL_EXPORTER_OTLP_ENDPOINT`	URL base OTLP
`OTEL_TRACES_SAMPLER`	`parentbased_traceidratio` etc.
`OTEL_NODE_RESOURCE_DETECTORS`	cloud, container, host

Ordem de Carregamento

// CORRETO
import "./instrumentation";
import express from "express";
 
// ERRADO - faltam spans HTTP
import express from "express";
import "./instrumentation";

NestJS: import "./instrumentation" primeira linha em main.ts.
tsx dev: node --import ./src/instrumentation.ts src/main.ts.

Amostragem

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Amostragem de cabeça de 10% para serviços de alto RPS - ajuste custo vs cobertura.
Sempre amostre erros se o fornecedor suportar amostragem baseada em cauda.

Armadilhas

Instrumentação após imports - faltam spans HTTP. Correção: instrumentação como primeira linha.
Instrumentação dupla - conflito entre agente do fornecedor e SDK OTel. Correção: escolha um caminho por sinal.
Atributos de span de alta cardinalidade - userId em cada span explode o custo. Correção: apenas atributos de baixa cardinalidade.
Ruído de spans FS - milhares de spans readFile. Correção: desabilitar @opentelemetry/instrumentation-fs.
Sem shutdown em SIGTERM - spans perdidos na implantação. Correção: sdk.shutdown() no manipulador de terminação.
Dev sem collector - erros de exportação inundam os logs. Correção: OTEL_TRACES_EXPORTER=none localmente ou execute Jaeger docker.

Alternativas

Alternativa	Use Quando	Não Use Quando
OTel Node SDK	Neutro em relação ao fornecedor, multi-sinal	Agente de fornecedor único sem configuração é suficiente
Datadog dd-trace	Totalmente no Datadog APM	Deseja portabilidade OTLP
Agente New Relic	Pilha apenas NR	OTLP multi-backend
Apenas logs manuais	Ferramenta interna pequena	APIs de SLA de produção

FAQs

Quais pacotes instalar?

@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, exportadores OTLP, @opentelemetry/api para spans manuais.

Funciona com Fastify?

Sim. A auto-instrumentação HTTP cobre o servidor subjacente do Fastify. Carregue a instrumentação antes do import do Fastify.

Sinal de logs em OTel?

O SDK de logs OTel está evoluindo. A maioria das equipes usa Pino stdout + injeção de trace_id para correlação de log-trace.

Instrumentação Prisma?

Instrumentação da comunidade ou spans manuais em torno de consultas. Habilite @opentelemetry/instrumentation-pg para drivers SQL brutos.

Jaeger Local?

Execute o collector com o receptor OTLP em 4318. Aponte OTEL_EXPORTER_OTLP_ENDPOINT para lá.

NestJS?

opentelemetry-instrumentation-nestjs-core ou spans manuais em interceptadores. Ainda carregue o SDK primeiro em main.ts.

Sobrecarga de desempenho?

Geralmente baixa porcentagem de um dígito com amostragem. Perfis com e sem em staging no RPS máximo.

Workers BullMQ?

service.name separado (por exemplo, orders-worker). Inicie o SDK no ponto de entrada do worker da mesma forma que o HTTP.

Relacionado

Noções Básicas de Observabilidade - introdução aos três pilares
Métricas que Importam - métricas RED
Ferramentas APM - padrões Datadog, Honeycomb
IDs de Correlação de Requisição - cabeçalho traceparent

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

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// src/instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({ [ATTR_SERVICE_NAME]: "orders-api" }),
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

// src/main.ts
import "./instrumentation.js";
import { startServer } from "./server.js";
startServer();

Quando usar isso:

Precisa de traces distribuídos entre microsserviços.
Depurando latência p99 com visualizações em cascata no Honeycomb/Datadog/Jaeger.
Padronizando a instrumentação antes de escolher um fornecedor de APM.
Substituindo o tempo console.time ad-hoc em produção.

Exemplo de Trabalho

// instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { Resource } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? "orders-api",
    [ATTR_SERVICE_VERSION]: process.env.APP_VERSION ?? "0.0.0",
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
    }),
    exportIntervalMillis: 60_000,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      "@opentelemetry/instrumentation-fs": { enabled: false },
    }),
  ],
});
 
sdk.start();
 
process.on("SIGTERM", () => sdk.shutdown());

// server.ts
import express from "express";
import { trace } from "@opentelemetry/api";
 
const app = express();
const tracer = trace.getTracer("orders");
 
app.get("/orders/:id", async (req, res) => {
  await tracer.startActiveSpan("loadOrder", async (span) => {
    span.setAttribute("order.id", req.params.id);
    const order = await db.findOrder(req.params.id);
    res.json(order);
  });
});
 
app.listen(3000);

O que isso demonstra:

Atributos de recurso identificam o serviço no backend de traces.
Endpoints OTLP separados para traces e métricas (comum em collectors).
Instrumentação FS desabilitada para reduzir ruído.
sdk.shutdown() gracioso em SIGTERM descarrega spans pendentes.

Mergulho Profundo

Como Funciona

O SDK registra tracers e meters no @opentelemetry/api global.
A auto-instrumentação aplica patches em http, https, fetch, pg, ioredis, etc. no momento do require.
Spans são exportados via OTLP (OpenTelemetry Protocol) para o collector ou agente.
O cabeçalho W3C traceparent propaga o contexto para chamadas HTTP downstream.

Variáveis de Ambiente

Variável	Propósito
`OTEL_SERVICE_NAME`	Atributo de recurso `service.name`
`OTEL_EXPORTER_OTLP_ENDPOINT`	URL base OTLP
`OTEL_TRACES_SAMPLER`	`parentbased_traceidratio` etc.
`OTEL_NODE_RESOURCE_DETECTORS`	cloud, container, host

Ordem de Carregamento

// CORRETO
import "./instrumentation";
import express from "express";
 
// ERRADO - faltam spans HTTP
import express from "express";
import "./instrumentation";

NestJS: import "./instrumentation" primeira linha em main.ts.
tsx dev: node --import ./src/instrumentation.ts src/main.ts.

Amostragem

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Amostragem de cabeça de 10% para serviços de alto RPS - ajuste custo vs cobertura.
Sempre amostre erros se o fornecedor suportar amostragem baseada em cauda.

Armadilhas

Instrumentação após imports - faltam spans HTTP. Correção: instrumentação como primeira linha.
Instrumentação dupla - conflito entre agente do fornecedor e SDK OTel. Correção: escolha um caminho por sinal.
Atributos de span de alta cardinalidade - userId em cada span explode o custo. Correção: apenas atributos de baixa cardinalidade.
Ruído de spans FS - milhares de spans readFile. Correção: desabilitar @opentelemetry/instrumentation-fs.
Sem shutdown em SIGTERM - spans perdidos na implantação. Correção: sdk.shutdown() no manipulador de terminação.
Dev sem collector - erros de exportação inundam os logs. Correção: OTEL_TRACES_EXPORTER=none localmente ou execute Jaeger docker.

Alternativas

Alternativa	Use Quando	Não Use Quando
OTel Node SDK	Neutro em relação ao fornecedor, multi-sinal	Agente de fornecedor único sem configuração é suficiente
Datadog dd-trace	Totalmente no Datadog APM	Deseja portabilidade OTLP
Agente New Relic	Pilha apenas NR	OTLP multi-backend
Apenas logs manuais	Ferramenta interna pequena	APIs de SLA de produção

FAQs

Quais pacotes instalar?

@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, exportadores OTLP, @opentelemetry/api para spans manuais.

Funciona com Fastify?

Sim. A auto-instrumentação HTTP cobre o servidor subjacente do Fastify. Carregue a instrumentação antes do import do Fastify.

Sinal de logs em OTel?

O SDK de logs OTel está evoluindo. A maioria das equipes usa Pino stdout + injeção de trace_id para correlação de log-trace.

Instrumentação Prisma?

Instrumentação da comunidade ou spans manuais em torno de consultas. Habilite @opentelemetry/instrumentation-pg para drivers SQL brutos.

Jaeger Local?

Execute o collector com o receptor OTLP em 4318. Aponte OTEL_EXPORTER_OTLP_ENDPOINT para lá.

NestJS?

opentelemetry-instrumentation-nestjs-core ou spans manuais em interceptadores. Ainda carregue o SDK primeiro em main.ts.

Sobrecarga de desempenho?

Geralmente baixa porcentagem de um dígito com amostragem. Perfis com e sem em staging no RPS máximo.

Workers BullMQ?

service.name separado (por exemplo, orders-worker). Inicie o SDK no ponto de entrada do worker da mesma forma que o HTTP.

Relacionado

Noções Básicas de Observabilidade - introdução aos três pilares
Métricas que Importam - métricas RED
Ferramentas APM - padrões Datadog, Honeycomb
IDs de Correlação de Requisição - cabeçalho traceparent

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

OpenTelemetry Node SDK

Buscar na documentação

OpenTelemetry Node SDK