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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions