diff --git a/docs/concepts/otlp/img/distributed-trace.png b/docs/concepts/otlp/img/distributed-trace.png new file mode 100644 index 0000000000000..1fb9655bb9462 Binary files /dev/null and b/docs/concepts/otlp/img/distributed-trace.png differ diff --git a/docs/concepts/otlp/index.mdx b/docs/concepts/otlp/index.mdx index 624a00d206b63..c434279e50be9 100644 --- a/docs/concepts/otlp/index.mdx +++ b/docs/concepts/otlp/index.mdx @@ -5,252 +5,18 @@ description: "Learn how to send OpenTelemetry trace data directly to Sentry from keywords: ["otlp", "otel", "opentelemetry"] --- -Sentry can ingest [OpenTelemetry](https://opentelemetry.io) traces and logs directly via the [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otel/protocol/). Sentry does not support ingesting OTLP metrics. - -## OpenTelemetry Traces - -If you have an existing OpenTelemetry trace instrumentation, you can configure your OpenTelemetry exporter to send traces to Sentry directly. Sentry's OTLP ingestion traces endpoint is currently in development, and has a few known limitations: - -- Span events are not supported. All span events are dropped during ingestion. -- Span links are partially supported. We ingest and display span links, but they cannot be searched, filtered, or aggregated. Links are shown in the [Trace View](/concepts/key-terms/tracing/trace-view/). -- Array attributes are partially supported. We ingest and display array attributes, but they cannot be searched, filtered, or aggregated. Array attributes are shown in the [Trace View](/concepts/key-terms/tracing/trace-view/). - -You can find the values of Sentry's OTLP traces endpoint and public key in your Sentry project settings. - -1. Go to the [Settings > Projects](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) page in Sentry. -2. Select a project from the list. -3. Go to the "Client Keys (DSN)" sub-page for this project under the "SDK Setup" heading. - -The easiest way to configure an OpenTelemetry exporter is with environment variables. You'll need to configure the trace endpoint URL, as well as the authentication headers. Set these variables on the server where your application is running. - -```bash {filename: .env} -export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="___OTLP_TRACES_URL___" -export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-sentry-auth=sentry sentry_key=___PUBLIC_KEY___" -``` - -If you prefer to explicitly configure an OpenTelemetry SDK or OTEL collector instance, see the following: - -### Using the OTEL Collector - -You can configure your OTEL collector instance to send traces to Sentry directly. This requires you to add an `otlphttp` exporter to your collector instance. Sentry's OTLP endpoints are project-specific, so you might also need to add a [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector) to route traces to the correct project. - -```yaml {filename: otel-collector.yaml} -exporters: - otlphttp: - traces_endpoint: ___OTLP_TRACES_URL___ - headers: - x-sentry-auth: "sentry sentry_key=___PUBLIC_KEY___" - compression: gzip - encoding: proto - timeout: 30s -``` - -### Using an OpenTelemetry SDK - -You can configure the OpenTelemetry Exporter directly in your application code. Here is an example with the OpenTelemetry Node SDK: - -```typescript {filename: app.ts} -import { NodeSDK } from "@opentelemetry/sdk-node"; -import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; - -const sdk = new NodeSDK({ - traceExporter: new OTLPTraceExporter({ - url: "___OTLP_TRACES_URL___", - headers: { - "x-sentry-auth": "sentry sentry_key=___PUBLIC_KEY___", - }, - }), -}); - -sdk.start(); -``` - -## OpenTelemetry Logs - - - -If you have an existing OpenTelemetry log instrumentation, you can configure your OpenTelemetry exporter to send logs to Sentry directly. Sentry's OTLP ingestion logs endpoint has the following known limitations: - -- Array attributes are partially supported. We ingest and display array attributes, but they cannot be searched, filtered, or aggregated. - -You can find the values of Sentry's OTLP logs endpoint and public key in your Sentry project settings. - -1. Go to the [Settings > Projects](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) page in Sentry. -2. Select a project from the list. -3. Go to the "Client Keys (DSN)" sub-page for this project under the "SDK Setup" heading. - -The easiest way to configure an OpenTelemetry exporter is with environment variables. You'll need to configure the logs endpoint URL, as well as the authentication headers. Set these variables on the server where your application is running. - -```bash {filename: .env} -export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="___OTLP_LOGS_URL___" -export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-sentry-auth=sentry sentry_key=___PUBLIC_KEY___" -``` - -If you prefer to explicitly configure an OpenTelemetry SDK or OTEL collector instance, see the following: - -### Using the OTEL Collector - -You can configure your OTEL collector instance to send logs to Sentry directly. This requires you to add an `otlphttp` exporter to your collector instance. Sentry's OTLP endpoints are project-specific, so you might also need to add a [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector) to route logs to the correct project. - -```yaml {filename: otel-collector.yaml} -exporters: - otlphttp: - logs_endpoint: ___OTLP_LOGS_URL___ - headers: - x-sentry-auth: "sentry sentry_key=___PUBLIC_KEY___" - compression: gzip - encoding: proto - timeout: 30s -``` - -### Using an OpenTelemetry SDK - -Alternatively, you can configure the OpenTelemetry Exporter directly in your application code. Here is an example with the OpenTelemetry Node SDK: - -```typescript {filename: app.ts} -import { - LoggerProvider, - BatchLogRecordProcessor, -} from "@opentelemetry/sdk-logs"; -import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http"; - -const logExporter = new OTLPLogExporter({ - url: "___OTLP_LOGS_URL___", - headers: { - "x-sentry-auth": "sentry sentry_key=___PUBLIC_KEY___", - }, -}); -const loggerProvider = new LoggerProvider({ - processors: [new BatchLogRecordProcessor(logExporter)], -}); - -const logger = loggerProvider.getLogger("default", "1.0.0"); -``` - -## Distributed Tracing between Sentry Instrumentation and OpenTelemetry Instrumentation - -If you have a frontend or services instrumented with the Sentry SDK, and you are also instrumenting with OpenTelemetry, you can use the `propagateTraceparent` exposed in the Sentry SDK to propagate the W3C Trace Context `traceparent` header to the OpenTelemetry instrumentation. This will allow you to continue traces from Sentry instrumented services. - -The following SDKs support the `propagateTraceparent` option: - -### JavaScript - -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - -### Mobile - -- -- -- -- - -## Dedicated Integrations +Sentry can ingest OTel traces and logs directly via the OpenTelemetry Protocol (OTLP). Sentry does not support ingesting OTLP metrics. -The following SDKs have dedicated integrations that make OTLP setup easy: +Sentry supports OTel in several ways, depending on your setup: -- +| Scenario | Solution | +|----------|----------| +| **Sentry frontend + OTel backend** | Use [propagateTraceparent](/concepts/otlp/sentry-with-otel/#linking-sentry-and-otlp-traces) to link frontend traces with OTLP instrumented backend services | +| **Sentry SDK + OTel in the same service** | Use the [OTLP Integration](/concepts/otlp/sentry-with-otel/#otlp-integration) to share trace context between Sentry and OTel | +| **OTel backend, no Sentry SDK** | Send [OTLP traces](/concepts/otlp/otlp-traces/) and [logs](/concepts/otlp/otlp-logs/) directly to Sentry via environment variables or collector config | ## OpenTelemetry Collector Guides -View the [OpenTelemetry Collector Guides](/product/drains/integration/opentelemetry-collector/#open-telemetry-collector-guides) to learn how to leverage the OpenTelemetry Collector to send traces and logs to Sentry from different sources like Kafka or Nginx. +View the [OTel Collector Guides](/product/drains/integration/opentelemetry-collector/#open-telemetry-collector-guides) to learn how to leverage the OTel Collector to send traces and logs to Sentry from different sources like Kafka or Nginx. diff --git a/docs/concepts/otlp/otlp-logs.mdx b/docs/concepts/otlp/otlp-logs.mdx new file mode 100644 index 0000000000000..c02faab80e87d --- /dev/null +++ b/docs/concepts/otlp/otlp-logs.mdx @@ -0,0 +1,61 @@ +--- +title: OTLP Logs +sidebar_title: OTLP Logs in Sentry +sidebar_order: 30 +description: "Send OpenTelemetry logs directly to Sentry without a Sentry SDK." +keywords: ["otlp", "otel", "opentelemetry", "logs", "logging"] +--- + + + +If you're using OTel without a Sentry SDK, you can send logs directly to Sentry's OTLP endpoint. You can find your endpoint URL and auth key in [Project settings > Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/). + +## Configuration + +```bash {filename: .env} +export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="___OTLP_LOGS_URL___" +export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-sentry-auth=sentry sentry_key=___PUBLIC_KEY___" +``` + +## Using the OTel Collector + +You can configure your OTel collector instance to send logs to Sentry directly. This requires you to add an `otlphttp` exporter to your collector instance. Sentry's OTLP endpoints are project-specific, so you might also need to add a [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector) to route logs to the correct project. + +```yaml {filename: otel-collector.yaml} +exporters: + otlphttp: + logs_endpoint: ___OTLP_LOGS_URL___ + headers: + x-sentry-auth: "sentry sentry_key=___PUBLIC_KEY___" + compression: gzip + encoding: proto + timeout: 30s +``` + +## Using an OTel SDK + +You can configure the OTel Exporter directly in your application code. Here is an example with the OTel Node SDK: + +```typescript {filename: app.ts} +import { + LoggerProvider, + BatchLogRecordProcessor, +} from "@opentelemetry/sdk-logs"; +import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http"; + +const logExporter = new OTLPLogExporter({ + url: "___OTLP_LOGS_URL___", + headers: { + "x-sentry-auth": "sentry sentry_key=___PUBLIC_KEY___", + }, +}); +const loggerProvider = new LoggerProvider({ + processors: [new BatchLogRecordProcessor(logExporter)], +}); + +const logger = loggerProvider.getLogger("default", "1.0.0"); +``` + +## Known Limitations + +- Array attributes are partially supported. We ingest and display array attributes, but they cannot be searched, filtered, or aggregated. diff --git a/docs/concepts/otlp/otlp-traces.mdx b/docs/concepts/otlp/otlp-traces.mdx new file mode 100644 index 0000000000000..a5ff79c27e987 --- /dev/null +++ b/docs/concepts/otlp/otlp-traces.mdx @@ -0,0 +1,86 @@ +--- +title: OTLP Traces +sidebar_title: OTLP Traces in Sentry +sidebar_order: 20 +description: "Send OpenTelemetry traces directly to Sentry without a Sentry SDK." +keywords: ["otlp", "otel", "opentelemetry", "traces", "tracing"] +--- + + + +If you're using OTel without a Sentry SDK, you can send traces directly to Sentry's OTLP endpoint. You can find your endpoint URL and auth key in [Project settings > Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/). + +## Configuration + +```bash {filename: .env} +export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="___OTLP_TRACES_URL___" +export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-sentry-auth=sentry sentry_key=___PUBLIC_KEY___" +``` + +## Using the OTel Collector + +You can configure your OTel collector instance to send traces to Sentry directly. This requires you to add an `otlphttp` exporter to your collector instance. Sentry's OTLP endpoints are project-specific, so you might also need to add a [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector) to route traces to the correct project. + +```yaml {filename: otel-collector.yaml} +exporters: + otlphttp: + traces_endpoint: ___OTLP_TRACES_URL___ + headers: + x-sentry-auth: "sentry sentry_key=___PUBLIC_KEY___" + compression: gzip + encoding: proto + timeout: 30s +``` + +### Sampling Traces + +If you want to reduce the volume of traces sent to Sentry, you can use the OTel Collector's [probabilistic sampler processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/probabilisticsamplerprocessor) to sample a percentage of your traffic. + +```yaml {filename: otel-collector.yaml} +processors: + probabilistic_sampler: + sampling_percentage: 10 # Send 10% of traces to Sentry + +exporters: + otlphttp/sentry: + traces_endpoint: ___OTLP_TRACES_URL___ + headers: + x-sentry-auth: "sentry sentry_key=___PUBLIC_KEY___" + compression: gzip + encoding: proto + +service: + pipelines: + traces: + receivers: [otlp] + processors: [probabilistic_sampler] + exporters: [otlphttp/sentry] +``` + +The probabilistic sampler uses consistent hashing on the trace ID, so all spans from the same trace are either sampled or dropped together. + +## Using an OTel SDK + +You can configure the OTel Exporter directly in your application code. Here is an example with the OTel Node SDK: + +```typescript {filename: app.ts} +import { NodeSDK } from "@opentelemetry/sdk-node"; +import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; + +const sdk = new NodeSDK({ + traceExporter: new OTLPTraceExporter({ + url: "___OTLP_TRACES_URL___", + headers: { + "x-sentry-auth": "sentry sentry_key=___PUBLIC_KEY___", + }, + }), +}); + +sdk.start(); +``` + +## Known Limitations + +- Span events are not supported. All span events are dropped during ingestion. +- Span links are partially supported. We ingest and display span links, but they cannot be searched, filtered, or aggregated. Links are shown in the [Trace View](/concepts/key-terms/tracing/trace-view/). +- Array attributes are partially supported. We ingest and display array attributes, but they cannot be searched, filtered, or aggregated. Array attributes are shown in the [Trace View](/concepts/key-terms/tracing/trace-view/). \ No newline at end of file diff --git a/docs/concepts/otlp/sentry-with-otel.mdx b/docs/concepts/otlp/sentry-with-otel.mdx new file mode 100644 index 0000000000000..5f164e99d827d --- /dev/null +++ b/docs/concepts/otlp/sentry-with-otel.mdx @@ -0,0 +1,86 @@ +--- +title: Sentry with OTel +sidebar_order: 10 +description: "Learn how to link Sentry SDK traces with OpenTelemetry instrumented services." +keywords: ["otlp", "otel", "opentelemetry", "propagateTraceparent", "integration"] +--- + +If you're using both Sentry SDKs and OpenTelemetry instrumentation, you can link them together for end-to-end [distributed tracing](/concepts/key-terms/tracing/distributed-tracing/). + +## Linking Sentry and OTLP Traces + +If you have a Sentry SDK on your frontend or mobile app making requests to an OTLP-instrumented backend, enable `propagateTraceparent` in your SDK initialization to link them into a single distributed trace. This sends the W3C `traceparent` header with outgoing requests, which your OTLP-instrumented backend will pick up and continue. + +This gives you end-to-end visibility: + +![Sentry Distributed Trace](./img/distributed-trace.png) + +The following SDKs support the `propagateTraceparent` option: + +
+ +
+ + ### JavaScript + + - + - + - + - + - + - + - + - + +
+
+ + ###   + + - + - + - + - + - + - + - + - + +
+
+ + ### Mobile + + - + - + - + - + +
+
+ +## OTLP Integration + +If you're running both a Sentry SDK and OTel instrumentation in the same backend service, use the OTLP Integration. This forces Sentry and OTel to share the same trace ID internally, so errors captured by Sentry are automatically linked to your OTLP traces. + +- +Coming Soon: +- +- +- diff --git a/docs/product/explore/logs/getting-started/index.mdx b/docs/product/explore/logs/getting-started/index.mdx index c248a86dfa3d0..c3bde28f9ffd9 100644 --- a/docs/product/explore/logs/getting-started/index.mdx +++ b/docs/product/explore/logs/getting-started/index.mdx @@ -340,4 +340,4 @@ We are actively working on adding support for more platforms, which we are track ### OpenTelemetry (OTLP) Endpoint -You can also send logs to Sentry via [Sentry's OpenTelemetry (OTLP) Logs endpoint](/concepts/otlp/#opentelemetry-logs). This can be used with any OpenTelemetry SDK, or with the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) to send logs to Sentry. This is useful if you're already using OpenTelemetry instrumentation or want to route logs through an OTLP collector. +You can also send logs to Sentry via [Sentry's OpenTelemetry (OTLP) Logs endpoint](/concepts/otlp/otlp-logs/). This can be used with any OpenTelemetry SDK, or with the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) to send logs to Sentry. This is useful if you're already using OpenTelemetry instrumentation or want to route logs through an OTLP collector.