Project setup

1. Copy the source/ directory into your project root (e.g., ./otel-source/).
2. Install dependencies listed above via npm.
3. Extend your tsconfig.json from the provided base:

   {
     "extends": "./otel-source/tsconfig.base.json",
     "compilerOptions": {
       "outDir": "./dist",
       "rootDir": "./src"
     }
   }
   

4. For ESM output, use tsconfig.base.esm.json instead.
5. Set the OTLP exporter endpoint via environment variable before starting your process:

   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
   OTEL_SERVICE_NAME=my-service
   

6. Register your SDK providers at application startup (before any other imports that may use the API) - see examples below.
7. For browser bundling, copy the relevant bundler-tests/browser/webpack-5/ webpack config as a starting point.

Public API

DiagConsoleLogger

import { DiagConsoleLogger, diag, DiagLogLevel } from '@opentelemetry/api';

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);

A built-in diagnostic logger that writes OpenTelemetry internal messages to console. Use it during development to debug SDK initialization, exporter connectivity, and instrumentation registration. Pass a DiagLogLevel to control verbosity.

createContextKey

import { createContextKey, ROOT_CONTEXT } from '@opentelemetry/api';

const MY_KEY = createContextKey('my-service.myKey');
const ctx = ROOT_CONTEXT.setValue(MY_KEY, 'some-value');
const value = ctx.getValue(MY_KEY); // 'some-value'

Creates an immutable, unique key for storing typed values inside an OpenTelemetry Context. Use it when you need to propagate request-scoped data (user IDs, tenant IDs, feature flags) alongside traces without polluting global state.

ValueType

import { ValueType } from '@opentelemetry/api';

meter.createHistogram('http.request.duration', {
  description: 'HTTP request latency',
  unit: 'ms',
  valueType: ValueType.DOUBLE,
});

Enum with values INT and DOUBLE that controls how metric values are recorded and exported. Use ValueType.INT for counters and ValueType.DOUBLE for measurements that require fractional precision.

wrapTracer / SugaredTracer (experimental)

import { wrapTracer } from '@opentelemetry/api/experimental';
import { trace } from '@opentelemetry/api';

const tracer = wrapTracer(trace.getTracer('my-service', '1.0.0'));
await tracer.withActiveSpan('my-operation', async (span) => {
  // span is active for the duration of the callback
});

wrapTracer returns a SugaredTracer that adds convenience methods (withActiveSpan, startActiveSpan variants) on top of the standard Tracer. Useful for reducing boilerplate when you always want a span active for the duration of an async callback. The experimental sub-path export may change between minor versions.

Working examples

Scenario - Bootstrap tracing for a Node.js Express server

Configure a BasicTracerProvider with an OTLP HTTP exporter at application startup, before requiring Express or any business logic.

import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { W3CTraceContextPropagator } from '@opentelemetry/core';

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN);

const exporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318/v1/traces',
});

const provider = new BasicTracerProvider({
  // resource and sampler options go here
});

provider.addSpanProcessor(
  // BatchSpanProcessor from @opentelemetry/sdk-trace-base
  new (require('@opentelemetry/sdk-trace-base').BatchSpanProcessor)(exporter)
);
provider.register({
  propagator: new W3CTraceContextPropagator(),
});

Scenario - Emit structured log records

Use the Logs API and SDK to emit structured log records that are correlated with active trace context.

import { logs } from '@opentelemetry/api-logs';
import { LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(
  new SimpleLogRecordProcessor(new OTLPLogExporter())
);
logs.setGlobalLoggerProvider(loggerProvider);

const logger = logs.getLogger('my-service', '1.0.0');
logger.emit({
  body: 'User signed in',
  attributes: { 'user.id': '42', 'user.role': 'admin' },
});

Scenario - Record metrics with a histogram

Create a MeterProvider, register it globally, and record HTTP latency measurements.

import { metrics, ValueType } from '@opentelemetry/api';
import { MeterProvider } from '@opentelemetry/sdk-metrics';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';

const meterProvider = new MeterProvider({
  readers: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter(),
      exportIntervalMillis: 15000,
    }),
  ],
});
metrics.setGlobalMeterProvider(meterProvider);

const meter = metrics.getMeter('http-server', '1.0.0');
const latency = meter.createHistogram('http.server.duration', {
  unit: 'ms',
  valueType: ValueType.DOUBLE,
});

// In your request handler:
const start = Date.now();
// ... handle request ...
latency.record(Date.now() - start, { 'http.method': 'GET', 'http.status_code': 200 });

File walkthrough

• .github/ - Contains all GitHub Actions CI workflows (unit tests, lint, publish, bundler tests, e2e, W3C integration) and issue/PR templates.
• api/ - Self-contained @opentelemetry/api package. All stable API contracts (tracing, metrics, context, baggage, diagnostics) live here; application code should depend only on this package at runtime.
• bundler-tests/ - Smoke-test entry points for Webpack 4/5 (browser and Node) that verify all SDK packages can be bundled together without errors.
• doc/ - Architecture decision records and contributor documentation not published to npm.
• e2e-tests/ - Full end-to-end test scenarios run against a live collector.
• examples/ - Standalone runnable demos (HTTP server, gRPC, Prometheus, etc.).
• experimental/ - Packages under active development with no stability guarantees; includes the SugaredTracer helper.
• integration-tests/ - Tests that verify backwards compatibility between API and SDK versions.
• packages/ - All stable SDK packages (sdk-trace-base, sdk-metrics, sdk-logs, core, exporters, propagators, resources, etc.).
• scripts/ - Release scripting, changelog generation, and monorepo maintenance utilities.
• semantic-conventions/ - Type-safe constants for OTel semantic conventions (attribute names, etc.).
• tsconfig.base.json / tsconfig.base.esm.json / tsconfig.base.esnext.json - Shared TypeScript compiler options extended by each package.
• lerna.json / nx.json - Monorepo orchestration: versioning, task caching, and pipeline dependencies.

Common pitfalls and fixes

• Provider registered after first use: The global trace/metrics/logs API returns a no-op if accessed before provider.register() is called. Fix: import and register providers in a dedicated instrumentation.ts file that is the very first import in index.ts.
• ESM/CJS interop with @opentelemetry/api: Some bundlers resolve both the CJS and ESM copy, creating two separate API singletons. Fix: add resolve.alias in webpack or moduleNameMapper in Jest to force a single copy of @opentelemetry/api.
• OTEL_EXPORTER_OTLP_ENDPOINT includes /v1/traces suffix: The OTLP HTTP exporter appends the signal path automatically. Fix: set the base URL only (e.g., http://localhost:4318), not http://localhost:4318/v1/traces.
• Experimental sub-path import failing in older Node: @opentelemetry/api/experimental requires Node 12+ exports field support. Fix: ensure "moduleResolution": "node16" or "bundler" in tsconfig.json.
• DiagLogLevel not imported when calling diag.setLogger: The second argument is required to activate logging; omitting it defaults to NONE. Fix: always pass DiagLogLevel.DEBUG or DiagLogLevel.INFO explicitly.
• Missing @types/node for Node.js SDK packages: Several SDK packages reference Node built-ins. Fix: npm install --save-dev @types/node and add "types": ["node"] to tsconfig.json.

Vibe-coding prompt template

I have the OpenTelemetry JS SDK monorepo source in the `source/` directory of
this project, and a usage guide at `USAGE.md`. The upstream npm package is
`user@example.com` (open-telemetry/opentelemetry-js on GitHub).

Please help me integrate OpenTelemetry into my existing Node.js TypeScript
project step by step:

1. Read `USAGE.md` and the relevant files under `source/api/src/` and
   `source/packages/` to understand the real exported symbols and types.
2. Create a `src/instrumentation.ts` file that initialises a
   BasicTracerProvider (with OTLP HTTP exporter), a MeterProvider (with
   PeriodicExportingMetricReader), and a LoggerProvider (with
   SimpleLogRecordProcessor). Register all three global providers.
3. Update `src/index.ts` to import `./instrumentation` as the very first line.
4. Add a typed helper that wraps an Express request handler in an active span,
   using only the real exports visible in `USAGE.md`.
5. Show the required `tsconfig.json` changes and environment variables.
6. Do not invent any API symbols - use only names documented in `USAGE.md`.

License and credit

The source is licensed under the Apache License 2.0. See source/LICENSE for the full text.

Upstream project: open-telemetry/opentelemetry-js, published on npm as @opentelemetry/api and related scoped packages.

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.