---

name: otel-js description: >- Instrument Node.js apps with OpenTelemetry. Use when a user asks to add distributed tracing, collect metrics, instrument HTTP requests, trace database queries, or set up observability for microservices. license: Apache-2.0 compatibility: 'Node.js 16+, Express, Fastify, NestJS' metadata: author: terminal-skills version: 1.0.0 category: devops tags: - opentelemetry - tracing - metrics - nodejs - observability

OpenTelemetry for Node.js

Overview

OpenTelemetry (OTel) is the standard for distributed tracing, metrics, and logs. Instrument your Node.js services once, and send telemetry to any backend (Jaeger, Grafana Tempo, Datadog, Honeycomb). Auto-instrumentation captures HTTP, database, and gRPC calls without code changes.

Instructions

Step 1: Auto-Instrumentation

npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http

// instrumentation.ts — OpenTelemetry setup (import BEFORE app code)
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]: 'api-service',
    [ATTR_SERVICE_VERSION]: process.env.npm_package_version || '1.0.0',
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/metrics',
    }),
    exportIntervalMillis: 30000,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-http': {
        ignoreIncomingPaths: ['/health', '/ready'],    // don't trace health checks
      },
      '@opentelemetry/instrumentation-express': { enabled: true },
      '@opentelemetry/instrumentation-pg': { enabled: true },
      '@opentelemetry/instrumentation-redis': { enabled: true },
    }),
  ],
})

sdk.start()
console.log('OpenTelemetry initialized')

process.on('SIGTERM', () => sdk.shutdown())

Step 2: Custom Spans

// services/orders.ts — Manual instrumentation for business logic
import { trace, SpanStatusCode } from '@opentelemetry/api'

const tracer = trace.getTracer('order-service')

export async function processOrder(orderId: string) {
  return tracer.startActiveSpan('processOrder', async (span) => {
    span.setAttribute('order.id', orderId)

    try {
      // Child span for payment
      const payment = await tracer.startActiveSpan('chargePayment', async (paymentSpan) => {
        paymentSpan.setAttribute('payment.provider', 'stripe')
        const result = await stripe.charges.create({ amount: 9999 })
        paymentSpan.setAttribute('payment.id', result.id)
        paymentSpan.end()
        return result
      })

      span.setAttribute('order.status', 'completed')
      span.setAttribute('payment.id', payment.id)
      span.setStatus({ code: SpanStatusCode.OK })
    } catch (err) {
      span.recordException(err)
      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
      throw err
    } finally {
      span.end()
    }
  })
}

Step 3: Run

# Start app with instrumentation loaded first
node --import ./instrumentation.ts src/server.ts

# Or in package.json
# "start": "node --import ./instrumentation.ts dist/server.js"

Guidelines

• Import instrumentation BEFORE your app code — auto-instrumentation patches libraries on import.
• Use --import flag (ESM) or -r flag (CJS) to load instrumentation first.
• Auto-instrumentation covers HTTP, Express, Fastify, PostgreSQL, Redis, MongoDB, gRPC.
• Add custom spans for business logic (order processing, payment flows) — auto-instrumentation only covers infrastructure.
• Send telemetry to an OTLP collector (Grafana Alloy, OTel Collector) for routing to multiple backends.