From ade8e3155415df2593eafc2bbde78de2dd5a3721 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 13:32:47 +0200 Subject: [PATCH 1/3] docs(opentelemetry): Point README to documentation Co-Authored-By: GPT-6 --- docs/opentelemetry.md | 26 +++++++++ packages/opentelemetry/README.md | 98 +++----------------------------- 2 files changed, 34 insertions(+), 90 deletions(-) create mode 100644 docs/opentelemetry.md diff --git a/docs/opentelemetry.md b/docs/opentelemetry.md new file mode 100644 index 000000000000..d892be29aa54 --- /dev/null +++ b/docs/opentelemetry.md @@ -0,0 +1,26 @@ +# Sentry Tracer Provider + +For application setup, first choose how Sentry and OpenTelemetry should work together using the +[OpenTelemetry setup guide](../MIGRATION.md#choosing-an-opentelemetry-setup). + +`SentryTracerProvider` from `@sentry/opentelemetry` is a minimal OpenTelemetry tracer provider that creates native +Sentry spans directly. It is useful when code uses the global OpenTelemetry API and does not need the full +OpenTelemetry SDK span processor and exporter pipeline. + +After initializing Sentry with tracing enabled, the provider can be registered with the OpenTelemetry API: + +```js +import { trace } from '@opentelemetry/api'; +import { SentryTracerProvider } from '@sentry/opentelemetry'; + +trace.setGlobalTracerProvider(new SentryTracerProvider()); + +const span = trace.getTracer('example').startSpan('work'); +span.end(); +``` + +Prefer the SDK's `enableOpenTelemetrySetup` option for application setup, as described in the setup guide. The example +above illustrates the provider itself; it does not configure context management or trace propagation. + +`SentryTracerProvider` does not handle OpenTelemetry logs and metrics. If you already have your own OpenTelemetry +pipeline, follow the [custom setup guidance](../MIGRATION.md#3-your-own-opentelemetry-sentry-linked-to-it). diff --git a/packages/opentelemetry/README.md b/packages/opentelemetry/README.md index 18fbdad8bfab..9377cb658f4c 100644 --- a/packages/opentelemetry/README.md +++ b/packages/opentelemetry/README.md @@ -10,97 +10,15 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/opentelemetry.svg)](https://www.npmjs.com/package/@sentry/opentelemetry) [![npm dt](https://img.shields.io/npm/dt/@sentry/opentelemetry.svg)](https://www.npmjs.com/package/@sentry/opentelemetry) -This package allows you to send your OpenTelemetry trace data to Sentry via OpenTelemetry SpanProcessors. +OpenTelemetry support for Sentry’s JavaScript SDKs. -If you are using `@sentry/node`, OpenTelemetry support is included out of the box. This package is only necessary if you -are setting up OpenTelemetry support for Sentry yourself. +## Documentation -## Installation +- [Setup and migration](https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md#better-opentelemetry-interoperability) +- [Sentry tracer provider](https://github.com/getsentry/sentry-javascript/blob/develop/docs/opentelemetry.md) +- [OpenTelemetry documentation](https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/) -```bash -npm install @sentry/opentelemetry +## Support -# Or yarn -yarn add @sentry/opentelemetry -``` - -Note that `@sentry/opentelemetry` depends on the following peer dependencies: - -- `@opentelemetry/api` version `1.0.0` or greater - -## Usage - -This package exposes a few building blocks you can add to your OpenTelemetry setup in order to capture OpenTelemetry -traces to Sentry. - -This is how you can use this in your app: - -1. Initialize Sentry, e.g. `@sentry/node`! -2. Call `setupEventContextTrace(client)` -3. Add `SentrySampler` as sampler -4. Add `SentrySpanProcessor` as span processor -5. Register the Sentry context manager (`SentryAsyncLocalStorageContextManager`, or `wrapContextManagerClass` for a custom base) -6. Add `SentryPropagator` as propagator -7. Setup OTEL-powered async context strategy for Sentry via `setOpenTelemetryContextAsyncContextStrategy()` - -For example, you could set this up as follows: - -```js -import * as Sentry from '@sentry/node'; -import { - SentryAsyncLocalStorageContextManager, - SentryPropagator, - SentrySampler, - SentrySpanProcessor, - setupEventContextTrace, - setOpenTelemetryContextAsyncContextStrategy, -} from '@sentry/opentelemetry'; -import { context, propagation, trace } from '@opentelemetry/api'; - -function setupSentry() { - Sentry.init({ - dsn: 'xxx', - }); - - const client = Sentry.getClient(); - setupEventContextTrace(client); - - const provider = new BasicTracerProvider({ - sampler: new SentrySampler(client), - }); - provider.addSpanProcessor(new SentrySpanProcessor()); - - // Initialize the provider - trace.setGlobalTracerProvider(provider); - context.setGlobalContextManager(new SentryAsyncLocalStorageContextManager()); - - setOpenTelemetryContextAsyncContextStrategy(); -} -``` - -A full setup example can be found in -[node-experimental](https://github.com/getsentry/sentry-javascript/blob/develop/packages/node-experimental). - -## Sentry Tracer Provider - -`SentryTracerProvider` is a minimal OpenTelemetry tracer provider which creates native Sentry spans directly. -It is useful when code uses the global OpenTelemetry API and you do not need the full OpenTelemetry SDK span processor -and exporter pipeline. - -```js -import { trace } from '@opentelemetry/api'; -import { SentryTracerProvider } from '@sentry/opentelemetry'; - -trace.setGlobalTracerProvider(new SentryTracerProvider()); - -const span = trace.getTracer('example').startSpan('work'); -span.end(); -``` - -In `@sentry/node`, this is the default tracer provider. - -The `SentryTracerProvider` does not handle OpenTelemetry logs and metrics. - -## Links - -- [Official SDK Docs](https://docs.sentry.io/quickstart/) +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) From 98996187981b251c39d1015d74fc04cb90ad57a2 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 13:55:09 +0200 Subject: [PATCH 2/3] docs: Resolve new documentation links within the branch Co-Authored-By: GPT-6 --- packages/opentelemetry/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opentelemetry/README.md b/packages/opentelemetry/README.md index 9377cb658f4c..779469443a1b 100644 --- a/packages/opentelemetry/README.md +++ b/packages/opentelemetry/README.md @@ -15,7 +15,7 @@ OpenTelemetry support for Sentry’s JavaScript SDKs. ## Documentation - [Setup and migration](https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md#better-opentelemetry-interoperability) -- [Sentry tracer provider](https://github.com/getsentry/sentry-javascript/blob/develop/docs/opentelemetry.md) +- [Sentry tracer provider](../../docs/opentelemetry.md) - [OpenTelemetry documentation](https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/) ## Support From d14f8a8838bbb710f55722c8941cbee540403459 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 15:33:42 +0200 Subject: [PATCH 3/3] docs: Link OpenTelemetry README to public setup guides Co-Authored-By: GPT-6 --- docs/opentelemetry.md | 26 -------------------------- packages/opentelemetry/README.md | 4 ++-- 2 files changed, 2 insertions(+), 28 deletions(-) delete mode 100644 docs/opentelemetry.md diff --git a/docs/opentelemetry.md b/docs/opentelemetry.md deleted file mode 100644 index d892be29aa54..000000000000 --- a/docs/opentelemetry.md +++ /dev/null @@ -1,26 +0,0 @@ -# Sentry Tracer Provider - -For application setup, first choose how Sentry and OpenTelemetry should work together using the -[OpenTelemetry setup guide](../MIGRATION.md#choosing-an-opentelemetry-setup). - -`SentryTracerProvider` from `@sentry/opentelemetry` is a minimal OpenTelemetry tracer provider that creates native -Sentry spans directly. It is useful when code uses the global OpenTelemetry API and does not need the full -OpenTelemetry SDK span processor and exporter pipeline. - -After initializing Sentry with tracing enabled, the provider can be registered with the OpenTelemetry API: - -```js -import { trace } from '@opentelemetry/api'; -import { SentryTracerProvider } from '@sentry/opentelemetry'; - -trace.setGlobalTracerProvider(new SentryTracerProvider()); - -const span = trace.getTracer('example').startSpan('work'); -span.end(); -``` - -Prefer the SDK's `enableOpenTelemetrySetup` option for application setup, as described in the setup guide. The example -above illustrates the provider itself; it does not configure context management or trace propagation. - -`SentryTracerProvider` does not handle OpenTelemetry logs and metrics. If you already have your own OpenTelemetry -pipeline, follow the [custom setup guidance](../MIGRATION.md#3-your-own-opentelemetry-sentry-linked-to-it). diff --git a/packages/opentelemetry/README.md b/packages/opentelemetry/README.md index 779469443a1b..c568465a9fb4 100644 --- a/packages/opentelemetry/README.md +++ b/packages/opentelemetry/README.md @@ -14,9 +14,9 @@ OpenTelemetry support for Sentry’s JavaScript SDKs. ## Documentation -- [Setup and migration](https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md#better-opentelemetry-interoperability) -- [Sentry tracer provider](../../docs/opentelemetry.md) - [OpenTelemetry documentation](https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/) +- [Capture spans from OpenTelemetry APIs](https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/using-opentelemetry-apis/) +- [Use your own OpenTelemetry pipeline](https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/custom-setup/) ## Support