Skip to content

Add otlpIntegration to @sentry/server-utils #23082

Description

@andreiborza

Re-add the OTLP integration, natively in @sentry/``server-utils. Each SDK that already depends on server-utils re-exports it, so users get trace connect without installing anything extra.

The integration used to live in packages/node-core/src/light/integrations/otlpIntegration.ts, which was deleted along with node-core (#21469). It needs to come back in the shape PR #20297 landed on.

Scope

  • otlpIntegration() takes no options. Its only job is to register an external propagation context so Sentry errors and logs are linked to the active OTel trace/span.
  • It does not set up a span exporter, span processor, or tracer provider. Users configure their own OTLPTraceExporter and point it at Sentry.
  • Ship a getOtlpTracesEndpoint(dsn) helper that parses a DSN into { url, headers } for the Sentry OTLP traces endpoint, so wiring up the OTel side is a one-liner.

Usage should look roughly like:

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node';

const provider = new NodeTracerProvider({
  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter(Sentry.getOtlpTracesEndpoint('__DSN__')))],
});
provider.register();

Sentry.init({
  dsn: '__DSN__',
  integrations: [Sentry.otlpIntegration()],
});

Why @sentry/``server-utils

It is the shared base for exactly the right set of packages: all 17 server SDKs (node, bun, deno, cloudflare, vercel-edge, aws-serverless, google-cloud-serverless, nestjs, nitro, and the meta-frameworks) already depend on it, and no browser SDK does. So the OpenTelemetry dependency never reaches @sentry/browser, @sentry/react, etc.

Not @sentry/core, because core is the runtime-agnostic base with a single dependency today, it would own an @opentelemetry/api version range on behalf of every browser and edge user, and users cannot import from it directly anyway (it is transitive, so @sentry/core/otlp fails to resolve under pnpm's default layout and yarn PnP).

Implementation notes

  • Add @opentelemetry/api as a direct dependency of ``` @`` ````sentry/server-utils, which has no OpenTelemetry dependency today (@sentry/conventions` + `@sentry/core`). It lands in all 17 server SDKs and no browser SDK, which is the intended reach. 7 of the 17 already declare it directly; the other 10 reach it through `@sentry/node`.
  • Export otlpIntegration and getOtlpTracesEndpoint from the main index. No dedicated entrypoint. @sentry/server-utils is sideEffects: false with an ESM build, so bundler consumers that never reference them tree-shake the @opentelemetry/api import away (measured ~2.8 KB min+gzip for trace.getActiveSpan()). Nothing in the browser CDN bundles pulls server-utils, so those size budgets are unaffected.
  • Start with @sentry/node. That single re-export covers 11 packages, since most meta-frameworks do export * from '@sentry/node': node, astro, nestjs, nitro, nuxt, remix, solidstart, sveltekit, nextjs (server), react-router, tanstackstart-react.
  • Six need an explicit line added: aws-serverless, bun and google-cloud-serverless use named-only re-export lists off @sentry/node; cloudflare, vercel-edge and deno are separate runtimes with no @sentry/node dependency. @sentry/nextjs edge does export * from '@sentry/vercel-edge', so it follows from vercel-edge.
  • Docs should be explicit that otlpIntegration() on its own produces nothing visible. Users still configure their own tracer provider and OTLPTraceExporter; the integration only links Sentry errors and logs to the active OTel trace.
  • Port the tests from packages/node-core/test/light/integrations/otlpIntegration.test.ts.

Metadata

Metadata

Assignees

Labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions