Required dependencies

npm install @opentelemetry/api \
            @opentelemetry/sdk-node \
            @opentelemetry/sdk-trace-node \
            @opentelemetry/sdk-logs \
            @opentelemetry/resources \
            @opentelemetry/semantic-conventions \
            @opentelemetry/exporter-trace-otlp-http \
            @opentelemetry/exporter-logs-otlp-http

No native build steps are required. Individual instrumentation packages (e.g., instrumentation-pg, instrumentation-mongodb) may require that the library being instrumented is also installed separately.

Project setup

1. Copy the source/ directory into your project root, e.g. ./otel-contrib/.
2. Add path aliases in tsconfig.json if you want to import from sub-packages directly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@otel-contrib/*": ["otel-contrib/*/src"]
    }
  }
}

3. Create a tracing.ts file that is required before any other module (use Node.js -r flag or import it first in index.ts).
4. Set environment variables before starting your process:

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_PROPAGATORS=tracecontext,baggage

5. Ensure tracing.ts is loaded before any instrumented library (Express, pg, etc.) is required.

Public API

getPropagator

import { getPropagator } from './otel-contrib/auto-configuration-propagators/src';

function getPropagator(): TextMapPropagator

Reads the OTEL_PROPAGATORS environment variable, instantiates each named propagator, and returns a CompositePropagator. Use this when you want env-driven propagator selection without hard-coding propagator classes.

getNodeAutoInstrumentations

import {
  getNodeAutoInstrumentations,
  InstrumentationConfigMap,
} from './otel-contrib/auto-instrumentations-node/src';

function getNodeAutoInstrumentations(
  inputConfigs?: InstrumentationConfigMap
): Instrumentation[]

Returns an array of all supported Node.js Instrumentation instances, ready to pass to the OpenTelemetry SDK. Use InstrumentationConfigMap to enable, disable, or configure individual instrumentations by their package name key.

getResourceDetectors

import { getResourceDetectors } from './otel-contrib/auto-instrumentations-node/src';

function getResourceDetectors(): DetectorSync[]

Reads OTEL_NODE_RESOURCE_DETECTORS and returns the matching resource detector instances. Use this to populate resourceDetectors in NodeSDK options so the SDK automatically discovers cloud and container attributes at startup.

BaggageSpanProcessor

import { BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS } from './otel-contrib/baggage-span-processor/src';
import type { BaggageKeyPredicate } from './otel-contrib/baggage-span-processor/src';

class BaggageSpanProcessor implements SpanProcessor {
  constructor(baggageKeyPredicate: BaggageKeyPredicate) {}
}

Attaches Baggage entries as span attributes on every span start. Pass ALLOW_ALL_BAGGAGE_KEYS to copy all keys, or supply a predicate function (key: string) => boolean to filter which keys are propagated.

BaggageLogRecordProcessor

import { BaggageLogRecordProcessor, ALLOW_ALL_BAGGAGE_KEYS } from './otel-contrib/baggage-log-record-processor/src';
import type { BaggageKeyPredicate } from './otel-contrib/baggage-log-record-processor/src';

class BaggageLogRecordProcessor implements LogRecordProcessor {
  constructor(baggageKeyPredicate: BaggageKeyPredicate) {}
}

Attaches Baggage entries as log record attributes. Use it in a LoggerProvider to ensure every log emitted carries the same Baggage context that spans carry.

getWebAutoInstrumentations

import {
  getWebAutoInstrumentations,
  InstrumentationConfigMap,
} from './otel-contrib/auto-instrumentations-web/src';

function getWebAutoInstrumentations(
  inputConfigs?: InstrumentationConfigMap
): Instrumentation[]

Returns all supported browser instrumentations. Pass the result to a WebTracerProvider's registerInstrumentations helper. Use InstrumentationConfigMap to disable specific instrumentations such as @opentelemetry/instrumentation-document-load.

Working examples

Scenario - Node.js SDK bootstrap with all instrumentations

Initialize OpenTelemetry once at process start, using env-driven propagators and auto-detected resources.

// tracing.ts  (import this first in index.ts or use -r flag)
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations, getResourceDetectors } from './otel-contrib/auto-instrumentations-node/src';
import { getPropagator } from './otel-contrib/auto-configuration-propagators/src';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  instrumentations: getNodeAutoInstrumentations({
    '@opentelemetry/instrumentation-fs': { enabled: false },
  }),
  resourceDetectors: getResourceDetectors(),
  textMapPropagator: getPropagator(),
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown().then(() => process.exit(0));
});

Scenario - Propagate Baggage onto spans and logs

Add Baggage values (e.g. tenant ID) set in incoming request middleware so they appear on every span and log record automatically.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
import { LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS } from './otel-contrib/baggage-span-processor/src';
import { BaggageLogRecordProcessor } from './otel-contrib/baggage-log-record-processor/src';
import { getNodeAutoInstrumentations } from './otel-contrib/auto-instrumentations-node/src';

const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(
  new BaggageLogRecordProcessor(ALLOW_ALL_BAGGAGE_KEYS)
);
loggerProvider.addLogRecordProcessor(
  new SimpleLogRecordProcessor(new OTLPLogExporter())
);

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  spanProcessors: [new BaggageSpanProcessor(ALLOW_ALL_BAGGAGE_KEYS)],
  instrumentations: getNodeAutoInstrumentations(),
});

sdk.start();

Scenario - Filter Baggage keys selectively

Only propagate Baggage entries whose keys start with tenant. to avoid leaking internal headers onto spans.

import { BaggageSpanProcessor } from './otel-contrib/baggage-span-processor/src';
import type { BaggageKeyPredicate } from './otel-contrib/baggage-span-processor/src';

const tenantKeyOnly: BaggageKeyPredicate = (key: string) =>
  key.startsWith('tenant.');

const processor = new BaggageSpanProcessor(tenantKeyOnly);

// Register processor with your TracerProvider:
// tracerProvider.addSpanProcessor(processor);

Scenario - Browser auto-instrumentation with selective disabling

Set up browser tracing, disabling the long-task instrumentation which can be noisy in single-page apps.

import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { getWebAutoInstrumentations } from './otel-contrib/auto-instrumentations-web/src';

const provider = new WebTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: getWebAutoInstrumentations({
    '@opentelemetry/instrumentation-long-task': { enabled: false },
  }),
  tracerProvider: provider,
});

File walkthrough

• auto-configuration-propagators/ - Exports getPropagator() which reads OTEL_PROPAGATORS and constructs a composite propagator; entry in src/index.ts, logic in src/utils.ts.
• auto-instrumentations-node/ - Exports getNodeAutoInstrumentations and getResourceDetectors; aggregates all Node.js-compatible instrumentation packages into a single factory.
• auto-instrumentations-web/ - Exports getWebAutoInstrumentations; aggregates all browser-compatible instrumentation packages.
• baggage-log-record-processor/ - BaggageLogRecordProcessor class plus ALLOW_ALL_BAGGAGE_KEYS constant and BaggageKeyPredicate type for filtering Baggage onto log records.
• baggage-span-processor/ - BaggageSpanProcessor class plus ALLOW_ALL_BAGGAGE_KEYS constant and BaggageKeyPredicate type for filtering Baggage onto spans.
• contrib-test-utils/ - Internal test helpers; not intended for production use.
• host-metrics/ - Periodic collection of host-level CPU, memory, and network metrics via OpenTelemetry Metrics API.
• id-generator-aws-xray/ - Implements IdGenerator interface producing X-Ray-compatible 96-bit trace IDs.
• instrumentation-*/ - Individual library instrumentations; each follows the same InstrumentationBase pattern and is configured via InstrumentationConfig.
• propagation-utils/ - Helper functions shared by propagator packages for header parsing and serialization.
• propagator-*/ - Concrete TextMapPropagator implementations for various vendor and standard formats.
• redis-common/ and sql-common/ - Internal shared utilities for Redis and SQL instrumentation packages respectively.
• resource-detector-*/ - DetectorSync implementations that add cloud/container/CI attributes to the OpenTelemetry Resource.
• sampler-aws-xray/ - Sampler implementation delegating to AWS X-Ray centralized sampling rules.
• winston-transport/ - A Winston transport that emits log records into the OpenTelemetry Logs SDK.
• plugin-react-load/ - Instruments React component render timing via browser performance marks.

Common pitfalls and fixes

• tracing.ts imported too late: If any instrumented library (e.g., express, pg) is required before the SDK starts, its module is already loaded and monkey-patching is skipped. Fix: ensure tracing.ts is the very first import or use node -r ./tracing.js.
• OTEL_PROPAGATORS not set: getPropagator() falls back to a no-op propagator if the env var is absent or contains an unrecognized name. Fix: set OTEL_PROPAGATORS=tracecontext,baggage explicitly.
• ESM/CJS interop failures: The source packages are compiled as CommonJS. If your project uses "type": "module", you must either use a .cjs wrapper or configure your bundler's resolve.extensionAlias. Fix: add "moduleResolution": "node16" in tsconfig.json and use .js extensions in imports.
• Peer dependency version mismatch: Each instrumentation requires a specific range of @opentelemetry/api. Using mismatched API versions causes a no-op tracer. Fix: ensure a single @opentelemetry/api version is installed (npm ls @opentelemetry/api) and deduplicate if needed.
• BaggageSpanProcessor with no Baggage in context: If Baggage is not set on the active context before the span starts, no attributes are added. Fix: use propagation.setBaggage(context.active(), baggage) in your middleware before creating spans.
• Resource detectors timeout in local dev: Cloud detectors (AWS, GCP) make HTTP calls to metadata endpoints and will time out outside their respective environments, slowing startup. Fix: set OTEL_NODE_RESOURCE_DETECTORS=env,host,process locally.

Vibe-coding prompt template

I have the OpenTelemetry JS Contrib instrumentation source code in the `source/` directory
of my project. I also have a USAGE.md that documents all exports and patterns.

Upstream package: user@example.com
Source directory: ./source/
Documentation: ./USAGE.md

My project is a Node.js TypeScript Express application using PostgreSQL (pg) and Redis (ioredis).

Please help me integrate OpenTelemetry step by step:
1. Create a `tracing.ts` file that starts the NodeSDK using `getNodeAutoInstrumentations`
   from `source/auto-instrumentations-node/src` and `getPropagator` from
   `source/auto-configuration-propagators/src`.
2. Add a `BaggageSpanProcessor` from `source/baggage-span-processor/src` that copies
   all Baggage keys onto spans.
3. Wire `tracing.ts` as the first import in `index.ts`.
4. Set the required environment variables in a `.env.example` file.
5. Show me how to verify spans are being emitted using the OTLP HTTP exporter.

Use only the exports documented in USAGE.md and visible in the source files.
Do not invent any APIs. Show complete, runnable TypeScript files.

License and credit

This source is distributed under the Apache License 2.0. See source/auto-configuration-propagators/LICENSE or any per-package LICENSE file for the full text.

Upstream repository: open-telemetry/opentelemetry-js-contrib Upstream package: user@example.com

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.