opentelemetry-instrumentation

license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
name	opentelemetry-instrumentation
description	Use when adding distributed tracing, debugging missing spans, fixing W3C traceparent propagation, configuring OTLP exporters (gRPC vs HTTP), choosing sampling strategies, setting resource attributes, or wiring auto-instrumentation libraries. Triggers: spans missing in Datadog/Honeycomb/Jaeger, "service.name = unknown_service", trace assembly broken across services, async work losing context, OTLP collector unreachable, sampling rate decisions, ESM vs CJS auto-instrumentation loader bugs. NOT for vendor-specific SDKs (Datadog APM, New Relic), structured-logging-only setups, or pre-OTel tracers (Jaeger client, Zipkin Brave).
metadata	{"category":"DevOps & Infrastructure","tags":["opentelemetry","observability","tracing","metrics","otel","instrumentation"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"logging-observability","reason":"Logs join traces only through the OTLP log pipeline; that skill owns the structured-logging side of the correlation"},{"skill":"observability-apm-expert","reason":"Owns the backend/APM side (dashboards, SLOs, alerting) that consumes the spans and metrics this skill emits"},{"skill":"monitoring-stack-deployer","reason":"Deploys the OTel Collector, storage, and Grafana stack that the OTLP exporters configured here point at"}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

OpenTelemetry Instrumentation

OpenTelemetry is the vendor-neutral standard for traces, metrics, and logs. The SDK is split between what gets recorded (Tracer/Meter/Logger), how it's sampled, how it's exported, and what context propagates. Most pain comes from misaligning those four.

When to use

• New service that needs distributed tracing.
• Existing service emits spans, but trace assembly breaks across the network boundary.
• Vendor backend shows "unknown_service" or trace IDs that don't link.
• You're paying too much for traces and need head/tail sampling.
• Async work (worker_threads, queues) drops the parent context.
• ESM-on-Node startup runs auto-instrumentation too late, missing http/express patches.

Core capabilities

Node SDK setup (auto-instrumentation)

// instrumentation.ts — must be loaded BEFORE any instrumented module.
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';

const sdk = new ({
  : ({
    []: ,
    []: process.. ?? ,
    : process.. ?? ,
  }),
  :  ({ : process.. }),
  :  ({
    :  (),
    : ,
  }),
  : [({
    
    : { :  },
  })],
});
sdk.();