diff --git a/packages/opentelemetry/README.md b/packages/opentelemetry/README.md index 18fbdad8bfab..c568465a9fb4 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 +- [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/) -```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)