OpenTelemetry JavaScript (@opentelemetry/api)

@opentelemetry/api is the stable, vendor-neutral entry point for OpenTelemetry in JavaScript and TypeScript. It ships the interfaces, enums, and no-op default implementations for tracing, metrics, context propagation, and diagnostic logging, letting libraries and applications add instrumentation without depending on any specific telemetry backend or exporter.

The package performs no operations until an SDK (such as @opentelemetry/sdk-trace-node) registers itself as the global implementation, so it’s safe for library authors to bundle it as a direct dependency: end users who never configure an SDK pay no runtime cost beyond a handful of no-op calls. The rest of the OpenTelemetry JS ecosystem — SDKs, exporters, and auto-instrumentations for frameworks like Express and Next.js — builds on top of this same API surface, making it the de facto standard for observability instrumentation across the Node.js and browser JavaScript ecosystem.

What You Get

• Tracing API — Tracer, Span, SpanContext, and context propagation primitives for creating and linking distributed traces
• Metrics API — Counter, Gauge, Histogram, UpDownCounter, and observable instrument types for recording measurements
• Context API — a carrier for correlating spans and baggage across async boundaries and service calls
• Diagnostic logging (DiagLogger) for surfacing SDK and instrumentation issues without a hard console.log dependency
• No-op default implementations so instrumented code runs safely with zero telemetry backend configured

Common Use Cases

• Library authors adding built-in tracing/metrics hooks without forcing a specific telemetry vendor on consumers
• Application teams standardizing on OpenTelemetry before choosing (or while migrating between) backend vendors like Datadog, Honeycomb, or Grafana Tempo
• Platform teams building custom instrumentation for internal services that must interoperate with auto-instrumented third-party libraries

Under The Hood

Architecture — The API package centers on a define-then-delegate pattern: src/index.ts re-exports typed interfaces (Tracer, Span, Meter, ContextManager, TextMapPropagator, DiagLogger) alongside five module-level singletons (trace, context, diag, metrics, propagation), each instantiated from its own file (trace-api.ts, context-api.ts, etc.) specifically to preserve tree-shaking per signal. Each singleton (e.g. TraceAPI in src/api/trace.ts) wraps a ProxyTracerProvider/ProxyTracer that starts backed by a NoopTracer (src/trace/NoopTracer.ts, NonRecordingSpan.ts) and, when an SDK calls trace.setGlobalTracerProvider(), swaps its internal _delegate to the real implementation — so any Tracer instance obtained before SDK registration keeps working transparently after. Cross-realm/cross-bundle sharing of that single global state goes through src/internal/global-utils.ts, which stashes the registered API under a Symbol.for(‘opentelemetry.js.api.<major>’) key on globalThis, guarded by exact-version compatibility checks in internal/semver.ts (major must match exactly, minor of the caller must be <= minor of the registered global) to prevent a library using a newer, incompatible API surface from crashing an older SDK.

Tech Stack — Pure TypeScript with zero runtime dependencies, built to dual CJS/ESM/ESNext targets via three tsconfig files (tsconfig.json, tsconfig.esm.json, tsconfig.esnext.json) compiled with tsc —build, and a package.json exports map exposing esnext/module/types/default conditions plus a separate ./experimental subpath. It lives inside a large Nx/Lerna-managed monorepo (nx.json, lerna.json) alongside dozens of sibling SDK, exporter, and semantic-conventions packages, but the api package itself is dependency-free by design so instrumented libraries never drag in a full SDK. Dev tooling spans mocha+nyc for Node tests, Karma+webpack for browser/worker tests, dpdm for circular-dependency checks, ESLint/Prettier, and TypeDoc for API reference generation; engines targets Node >=8 while the README promises ES5+ browser compatibility for this package specifically.

Code Quality — Testing is substantial: 21 test files under test/common/** cover diag loggers, context managers, span-context validation, tracestate parsing, proxy-tracer/proxy-provider delegation, noop implementations, semver compatibility, plus a dedicated tree-shaking test and a Node 8 backcompat script, with nyc coverage wired into npm test. Source files are small and single-responsibility (one class per file: NonRecordingSpan.ts, ProxyTracer.ts, NoopMeter.ts), consistently carry SPDX license headers and TSDoc comments with @since version tags on public exports, and lean on TypeScript’s type system rather than runtime checks. internal/semver.ts is representative of the project’s discipline — the exact compatibility rules are documented inline before the implementation, backed by a matching semver.test.ts.

API Design — Ergonomics favor library authors: the entire getting-started snippet is const tracer = trace.getTracer('name', 'version'); const span = tracer.startSpan('op'); span.end();, with the safe no-op default meaning zero required setup for consumers who don’t want telemetry. Naming tracks the OpenTelemetry spec closely (Tracer/Span/SpanContext/SpanKind, Meter/Counter/Histogram/Gauge, ContextManager, TextMapPropagator), matching every other language’s OpenTelemetry SDK and easing cross-language onboarding. Minor friction: a few exports are kept only for back-compat (a deprecated SpanAttributes alias, a TODO comment to remove ProxyTracerProvider in the next major), and the experimental metrics/tracing surface lives behind a separate /experimental subpath import that isn’t obvious without reading the docs.