-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
docs: Add missing OTLP integration docs and fix drift across SDKs #18441
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Changes from all commits
89c4850
96cfc6f
2d7dd02
3d63abb
c6de0ee
17a1178
8540ee1
8434915
4cece09
3e35289
d4ebc65
a786a30
d348f6d
fefea65
2596a60
fdad7fb
25ea04e
bc773fb
84d25a1
a169877
ab536f9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| --- | ||
| title: OpenTelemetry (OTLP) | ||
| description: "Learn about using OTLP to automatically send OpenTelemetry Traces to Sentry." | ||
| sidebar_order: 22 | ||
| keywords: ["otlp", "otel", "opentelemetry"] | ||
| --- | ||
|
|
||
| The OTLP exporter configures the Sentry SDK to automatically send trace data instrumented by an OpenTelemetry SDK to Sentry's [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otel/protocol/) [ingestion endpoint](/concepts/otlp). | ||
|
|
||
| ## Install | ||
|
|
||
| Add the `Sentry.OpenTelemetry.Exporter` NuGet package to your project: | ||
|
|
||
| ```shell {tabTitle:.NET Core CLI} | ||
| dotnet add package Sentry.OpenTelemetry.Exporter -v {{@inject packages.version('sentry.dotnet') }} | ||
| ``` | ||
|
|
||
| ```powershell {tabTitle:Package Manager} | ||
| Install-Package Sentry.OpenTelemetry.Exporter -Version {{@inject packages.version('sentry.dotnet') }} | ||
| ``` | ||
|
|
||
| ```shell {tabTitle:Paket CLI} | ||
| paket add Sentry.OpenTelemetry.Exporter --version {{@inject packages.version('sentry.dotnet') }} | ||
| ``` | ||
|
|
||
| This package includes the standard OpenTelemetry OTLP exporter as a transitive dependency. | ||
|
|
||
| To instrument outgoing HTTP requests using OpenTelemetry, also install [`OpenTelemetry.Instrumentation.Http`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http): | ||
|
|
||
| ```shell {tabTitle:.NET Core CLI} | ||
| dotnet add package OpenTelemetry.Instrumentation.Http | ||
| ``` | ||
|
|
||
| ```powershell {tabTitle:Package Manager} | ||
| Install-Package OpenTelemetry.Instrumentation.Http | ||
| ``` | ||
|
|
||
| ## Configure | ||
|
|
||
| You need to configure both the OpenTelemetry and Sentry SDKs to get trace data. | ||
|
|
||
| ### OpenTelemetry | ||
|
|
||
| Set up a `TracerProvider` using `AddSentryOtlpExporter` with your DSN. This automatically configures the OTLP endpoint and authentication headers derived from the DSN. | ||
|
|
||
| ```csharp | ||
| using var tracerProvider = Sdk.CreateTracerProviderBuilder() | ||
| .AddSource("MyApp") // the name of your ActivitySource | ||
| .AddHttpClientInstrumentation() | ||
| .AddSentryOtlpExporter("___PUBLIC_DSN___") | ||
| .Build(); | ||
| ``` | ||
|
|
||
| ### Sentry | ||
|
|
||
| Initialize Sentry and call `UseOtlp()` to disable Sentry's built-in span creation in favor of OpenTelemetry tracing. | ||
|
|
||
| ```csharp | ||
| SentrySdk.Init(options => | ||
| { | ||
| options.Dsn = "___PUBLIC_DSN___"; | ||
| options.UseOtlp(); | ||
| }); | ||
| ``` | ||
|
|
||
| ## Behavior | ||
|
|
||
| Under the hood, the OTLP exporter sets up the following parts: | ||
|
|
||
| * An OTLP exporter that automatically configures the ingestion endpoint from your Sentry DSN. This enables tracing in Sentry. **Note:** _Do not_ also set up tracing via the Sentry SDK (i.e. do not set `TracesSampleRate`). | ||
| * A `SentryPropagator` that injects `sentry-trace` and `baggage` headers alongside the standard W3C `traceparent`, ensuring [distributed tracing](/concepts/key-terms/tracing/distributed-tracing/) works | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The development documentation indicates we shouldn't be doing this. See:
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
But since it reflects current (incorrect) behavior, this PR is not blocked. |
||
| * Trace/Span linking for all other Sentry events such as Errors, Logs, and Metrics | ||
|
|
||
| Calling `UseOtlp()` on `SentryOptions` sets `DisableSentryTracing = true`, which turns off Sentry's automatic span creation from `SentryHttpMessageHandler`, `DiagnosticSource` listener, and Entity Framework interception to avoid duplicate spans. | ||
|
|
||
| ## Options | ||
|
|
||
| `AddSentryOtlpExporter` accepts the following parameters: | ||
|
|
||
| - `dsnString` (string): | ||
|
|
||
| Your Sentry DSN. The OTLP endpoint and authentication headers are derived from this automatically. | ||
|
|
||
| - `collectorUrl` (Uri, optional): | ||
|
|
||
| URL of your own OpenTelemetry collector. When set, the exporter will send traces to this URL instead of the Sentry OTLP endpoint derived from the DSN. | ||
|
|
||
| - `defaultTextMapPropagator` (TextMapPropagator, optional): | ||
|
|
||
| Override the default propagator. Defaults to `SentryPropagator`, which propagates `sentry-trace`, `baggage`, and W3C `traceparent` headers. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| --- | ||
| title: OpenTelemetry (OTLP) | ||
| description: "Learn about using OTLP to automatically send OpenTelemetry Traces to Sentry." | ||
| keywords: ["otlp", "otel", "opentelemetry"] | ||
| --- | ||
|
|
||
| The OTLP integration configures the Sentry SDK to automatically send trace data instrumented by an OpenTelemetry SDK to Sentry's [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otel/protocol/) [ingestion endpoint](/concepts/otlp). | ||
|
|
||
| <Alert level="warning" title="Mutually Exclusive With Sentry Tracing"> | ||
|
|
||
| Using Sentry tracing and OTLP tracing at the same time is not supported. If Sentry tracing is enabled (`traces_sample_rate`, `traces_sampler`, or `enable_tracing`), the integration will not be registered. | ||
|
|
||
| </Alert> | ||
|
|
||
| ## Install | ||
|
|
||
| Install the required OpenTelemetry packages via Composer: | ||
|
|
||
| ```bash | ||
| composer require \ | ||
| open-telemetry/sdk \ | ||
| open-telemetry/exporter-otlp | ||
| ``` | ||
|
|
||
| ## Configure | ||
|
|
||
| You need to configure both the OpenTelemetry and Sentry SDKs to get trace data. | ||
|
|
||
| ### OpenTelemetry | ||
|
|
||
| For the OpenTelemetry SDK, you need to [configure instrumentation](https://opentelemetry.io/docs/languages/php/instrumentation/) you want to capture. | ||
|
|
||
| ### Sentry | ||
|
|
||
| For the Sentry SDK, add the `OTLPIntegration` to your existing configuration. | ||
|
|
||
| ```php | ||
| \Sentry\init([ | ||
| 'dsn' => '___PUBLIC_DSN___', | ||
| // Add data like request headers and IP for users, if applicable; | ||
| // see https://docs.sentry.io/platforms/php/data-management/data-collected/ for more info | ||
| 'send_default_pii' => true, | ||
| 'integrations' => [ | ||
| new \Sentry\Integration\OTLPIntegration(), | ||
| ], | ||
| ]); | ||
| ``` | ||
|
|
||
| ## Behavior | ||
|
|
||
| Under the hood, the `OTLPIntegration` sets up the following parts: | ||
|
|
||
| * A [`SpanExporter`](https://opentelemetry.io/docs/concepts/components/#exporters) that automatically configures the OTLP ingestion endpoint from your Sentry DSN. This enables tracing in Sentry. **Note:** _Do not_ also set up tracing via the PHP SDK (i.e. do not set `traces_sample_rate`, `traces_sampler`, or `enable_tracing`). | ||
| * Trace/Span linking for all other Sentry events such as Errors, Logs, and Metrics | ||
|
|
||
| ## Options | ||
|
|
||
| You can pass the following arguments to the `OTLPIntegration` constructor: | ||
|
|
||
| - `setupOtlpTracesExporter` (bool): | ||
|
|
||
| Automatically configure an Exporter to send OTLP traces to the right project from the DSN or `collectorUrl`, defaults to `true`. | ||
|
|
||
| Set to `false` to set up the TracerProvider manually. | ||
|
|
||
| - `collectorUrl` (string|null): | ||
|
|
||
| URL of your own OpenTelemetry collector. When set, the exporter will send traces to this URL instead of the Sentry OTLP endpoint derived from the DSN. | ||
|
|
||
| ## Supported Versions | ||
|
|
||
| - PHP: 8.1+ (required by the OpenTelemetry SDK) | ||
| - sentry/sentry: 4.23.0+ |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| --- | ||
| title: OpenTelemetry (OTLP) | ||
| description: "Learn about using OTLP to automatically send OpenTelemetry Traces to Sentry." | ||
| keywords: ["otlp", "otel", "opentelemetry"] | ||
| --- | ||
|
|
||
| The OTLP integration configures the Sentry SDK to automatically send trace data instrumented by an OpenTelemetry SDK to Sentry's [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otel/protocol/) [ingestion endpoint](/concepts/otlp). | ||
|
|
||
| <Alert level="warning" title="Mutually Exclusive With Sentry Tracing"> | ||
|
|
||
| Using Sentry tracing and OTLP tracing at the same time is not supported. If Sentry tracing is enabled (`traces_sample_rate`, `traces_sampler`, or `enable_tracing`), the integration will not be registered. | ||
|
|
||
| </Alert> | ||
|
|
||
| ## Install | ||
|
|
||
| Install the required OpenTelemetry packages via Composer: | ||
|
|
||
| ```bash | ||
| composer require \ | ||
| sentry/sentry-laravel:"^4.25" \ | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit: I think we should have a |
||
| open-telemetry/sdk \ | ||
| open-telemetry/exporter-otlp | ||
| ``` | ||
|
|
||
| ## Configure | ||
|
|
||
| You need to configure both the OpenTelemetry and Sentry SDKs to get trace data. | ||
|
|
||
| ### OpenTelemetry | ||
|
|
||
| For the OpenTelemetry SDK, you need to [configure instrumentation](https://opentelemetry.io/docs/languages/php/instrumentation/) you want to capture. | ||
|
|
||
| ### Sentry | ||
|
|
||
| Add the `OTLPIntegration` class to the `integrations` array in `config/sentry.php`: | ||
|
|
||
| ```php {filename:config/sentry.php} | ||
| 'integrations' => [ | ||
| \Sentry\Integration\OTLPIntegration::class, | ||
| ], | ||
| ``` | ||
|
|
||
| ## Behavior | ||
|
|
||
| Under the hood, the `OTLPIntegration` sets up the following parts: | ||
|
|
||
| * A [`SpanExporter`](https://opentelemetry.io/docs/concepts/components/#exporters) that automatically configures the OTLP ingestion endpoint from your Sentry DSN. This enables tracing in Sentry. **Note:** _Do not_ also set up tracing via the PHP SDK (i.e. do not set `traces_sample_rate`, `traces_sampler`, or `enable_tracing`). | ||
| * Trace/Span linking for all other Sentry events such as Errors, Logs, and Metrics | ||
|
|
||
| ## Options | ||
|
|
||
| For details on available options (`setupOtlpTracesExporter`, `collectorUrl`), see the <PlatformLink to="/integrations/otlp/" fallbackPlatform="php">OTLP integration docs</PlatformLink>. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| --- | ||
| title: OpenTelemetry (OTLP) | ||
| description: "Learn about using OTLP to automatically send OpenTelemetry Traces to Sentry." | ||
| keywords: ["otlp", "otel", "opentelemetry"] | ||
| --- | ||
|
|
||
| The OTLP integration configures the Sentry SDK to automatically send trace data instrumented by an OpenTelemetry SDK to Sentry's [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otel/protocol/) [ingestion endpoint](/concepts/otlp). | ||
|
|
||
| <Alert level="warning" title="Mutually Exclusive With Sentry Tracing"> | ||
|
|
||
| Using Sentry tracing and OTLP tracing at the same time is not supported. If Sentry tracing is enabled (`traces_sample_rate`, `traces_sampler`, or `enable_tracing`), the integration will not be registered. | ||
|
|
||
| </Alert> | ||
|
|
||
| ## Install | ||
|
|
||
| Install the required OpenTelemetry packages via Composer: | ||
|
|
||
| ```bash | ||
| composer require \ | ||
| sentry/sentry-symfony:"^5.10" \ | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
| open-telemetry/sdk \ | ||
| open-telemetry/exporter-otlp | ||
| ``` | ||
|
|
||
| ## Configure | ||
|
|
||
| You need to configure both the OpenTelemetry and Sentry SDKs to get trace data. | ||
|
|
||
| ### OpenTelemetry | ||
|
|
||
| For the OpenTelemetry SDK, you need to [configure instrumentation](https://opentelemetry.io/docs/languages/php/instrumentation/) you want to capture. | ||
|
|
||
| ### Sentry | ||
|
|
||
| Add the `OTLPIntegration` to the integrations list in your Sentry bundle configuration: | ||
|
|
||
| ```yaml {filename:config/packages/sentry.yaml} | ||
| sentry: | ||
| options: | ||
| integrations: | ||
| - Sentry\Integration\OTLPIntegration | ||
| ``` | ||
|
|
||
| The `OTLPIntegration` is registered as a service by the Sentry Symfony bundle automatically. | ||
|
|
||
| ## Behavior | ||
|
|
||
| Under the hood, the `OTLPIntegration` sets up the following parts: | ||
|
|
||
| * A [`SpanExporter`](https://opentelemetry.io/docs/concepts/components/#exporters) that automatically configures the OTLP ingestion endpoint from your Sentry DSN. This enables tracing in Sentry. **Note:** _Do not_ also set up tracing via the PHP SDK (i.e. do not set `traces_sample_rate`, `traces_sampler`, or `enable_tracing`). | ||
| * Trace/Span linking for all other Sentry events such as Errors, Logs, and Metrics | ||
|
|
||
| ## Options | ||
|
|
||
| For details on available options (`setupOtlpTracesExporter`, `collectorUrl`), see the <PlatformLink to="/integrations/otlp/" fallbackPlatform="php">OTLP integration docs</PlatformLink>. | ||
Uh oh!
There was an error while loading. Please reload this page.