Vercel OTel

@vercel/otel is Vercel’s official wrapper around the OpenTelemetry JavaScript SDK, built to make distributed tracing practical inside Next.js apps deployed to Vercel’s edge and serverless runtimes. Instead of hand-assembling a tracer provider, context manager, propagators, and exporters yourself, you call a single registerOTel() function from instrumentation.ts and the package configures sensible defaults for you — automatic fetch instrumentation, W3C trace-context and baggage propagation, and an exporter that reports spans directly into Vercel’s built-in Observability tooling when deployed there.

The package is explicitly designed to work across Vercel’s split runtime model: the same public API compiles to separate edge and Node.js builds via conditional package exports, so tracing works identically whether a route runs on the Edge Runtime or a serverless Node.js function. When no Vercel telemetry integration is configured, it falls back cleanly to a standard OTLP HTTP exporter driven by the usual OTEL_EXPORTER_OTLP_* environment variables, so the same instrumentation code works self-hosted, on other platforms, or against any OpenTelemetry collector.

Under the hood it composes standard @opentelemetry/sdk-trace-base, sdk-logs, and sdk-metrics providers rather than replacing them, so anything built against the vendor-neutral OpenTelemetry API — custom spans, meters, log records — continues to work unmodified. Vercel-specific behavior (request-context propagation, draining spans when a serverless function suspends, reporting into the platform’s telemetry API) is isolated into its own module rather than leaking into the public configuration surface.

What You Get

• registerOTel() entry point - a single function (string shorthand or full config object) that stands up a complete tracer/logger/meter provider stack from instrumentation.ts
• Automatic fetch instrumentation - outbound fetch() calls are traced by default, with per-call overrides for span naming, attributes, and context propagation directly in fetch(url, { opentelemetry: {...} })
• Dual edge/Node builds - conditional package exports ship separate bundles for the Edge Runtime, Cloudflare-style workerd/worker environments, and Node.js from one API
• Built-in Vercel telemetry integration - spans report directly into Vercel’s Observability dashboard when running on the platform, with no exporter configuration needed
• Standard OTLP fallback - when not on Vercel (or no integration is configured), spans export over OTLP HTTP (JSON or protobuf) driven by standard OTEL_EXPORTER_OTLP_* env vars
• Config-or-env-var parity - propagators, samplers, and span processors can be set via the registerOTel() config object or standard OTEL_* environment variables, matching the OpenTelemetry spec’s own conventions

Common Use Cases

• Enabling tracing in a new Next.js app - add registerOTel('my-app') to instrumentation.ts to get end-to-end request tracing with zero further configuration
• Debugging slow API routes - trace outbound fetch() calls automatically to see which downstream service call is adding latency to a serverless function
• Shipping traces to a self-hosted collector - set OTEL_EXPORTER_OTLP_ENDPOINT to point spans at any OpenTelemetry Collector instead of Vercel’s built-in exporter, for teams standardizing on their own observability stack
• Sampling high-traffic routes - configure traceSampler (e.g. traceidratio) to trace a percentage of requests on high-volume endpoints instead of every invocation
• Correlating traces across services - use the built-in W3C trace-context and baggage propagators so a trace initiated in one service continues through downstream calls to other instrumented services

Under The Hood

Architecture The package centers on a single Sdk class (src/sdk.ts) that composes the standard OpenTelemetry provider stack — BasicTracerProvider, LoggerProvider, MeterProvider — behind one start()/shutdown() lifecycle triggered by the exported registerOTel() function. Concerns are separated into dedicated modules: exporters/ for OTLP HTTP transports, instrumentations/ for the fetch instrumentation, processor/ for span-processing behavior (including a FilterWhenDrainedSpanProcessor that suppresses exports once a serverless invocation has been drained), propagators/ for W3C trace-context handling, and vercel-request-context/ isolating all Vercel-platform-specific integration (reading the request’s telemetry context and reporting spans into Vercel’s own API) away from the vendor-neutral configuration surface. Package exports use conditional resolution (edge, workerd, worker, node, import) so the same public API resolves to different bundles depending on the consuming runtime, which is the core architectural constraint the whole package is built around.

Tech Stack Written in TypeScript against the @opentelemetry/api, sdk-trace-base, sdk-logs, sdk-metrics, resources, and instrumentation packages as peer dependencies, keeping the published bundle free of duplicated OpenTelemetry runtime code. The repository is a pnpm/Turborepo monorepo managed with Changesets for versioned releases, with the package itself built via a custom esbuild-driven build.ts script plus a separate TypeScript declaration-only pass and a Typedoc-generated API reference site. Sibling packages in the same monorepo (collector, bridge-emulator, an experimental otelzero) support local development and testing rather than shipping as part of the published library.

Code Quality Unit tests (Vitest) cover the OTLP protobuf serialization path, the W3C trace-context propagator, and resource-attribute utilities, but the central Sdk class and the fetch instrumentation itself are exercised primarily through separate end-to-end test suites (tests/e2e, apps/sample, apps/multiple-exporters) rather than unit tests, so core registration logic is verified at a higher level rather than in isolation. TypeScript runs in strict mode via a shared typescript-config package, and a shared eslint-config plus dedicated CI workflows for ESLint, type-checking, unit tests, and both dev and prod end-to-end tests gate every change.

API Design registerOTel() accepts either a bare service-name string or a full configuration object, so the common case is a one-line call while advanced users retain access to samplers, span/log processors, resource detectors, and custom instrumentations. Defaults are deliberately opinionated — fetch instrumentation and Vercel’s own exporter are enabled automatically — while every default can be overridden with the same string-or-object pattern ("auto", "none", or a concrete instance) used consistently across propagators, samplers, and processors. Per-call tracing overrides are exposed through a fetch(url, { opentelemetry: {...} }) extension rather than a separate API, keeping the surface area small for a library whose entire job is running invisibly in the background.