Skip to content

docs(otlp): Restructure OTLP page to elevate propagateTraceparent #16264

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.

Sign up for GitHub

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

Merged
jaffrepaul merged 8 commits into from
Feb 5, 2026
+242 −243
Merged

docs(otlp): Restructure OTLP page to elevate propagateTraceparent #16264

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f2ed0aa
restructure to elevate propagateTraceparent
jaffrepaul Jan 30, 2026
b704bad
separate concepts + refinements
jaffrepaul Feb 4, 2026
39fad72
layout & naming updates
jaffrepaul Feb 4, 2026
4e81fd1
fix urls
jaffrepaul Feb 5, 2026
4d33ca3
update OTLPIntegration list
jaffrepaul Feb 5, 2026
7af9ff2
add trace sampling option
jaffrepaul Feb 5, 2026
37decf0
move limitations to the bottom
jaffrepaul Feb 5, 2026
792c3b4
fix logs slug
jaffrepaul Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/concepts/otlp/img/distributed-trace.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
250 changes: 8 additions & 242 deletions docs/concepts/otlp/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<Include name="feature-available-open-beta-tracing.mdx" />

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

<Include name="feature-available-open-beta-logs.mdx" />

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

- <LinkWithPlatformIcon
platform="javascript.browser"
label="Browser JavaScript"
url="/platforms/javascript/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.angular"
label="Angular"
url="/platforms/javascript/guides/angular/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.astro"
label="Astro"
url="/platforms/javascript/guides/astro/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.ember"
label="Ember"
url="/platforms/javascript/guides/ember/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.gatsby"
label="Gatsby"
url="/platforms/javascript/guides/gatsby/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.nextjs"
label="Next.js"
url="/platforms/javascript/guides/nextjs/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.nuxt"
label="Nuxt"
url="/platforms/javascript/guides/nuxt/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.react"
label="React"
url="/platforms/javascript/guides/react/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.react-router"
label="React Router"
url="/platforms/javascript/guides/react-router/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.remix"
label="Remix"
url="/platforms/javascript/guides/remix/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.solid"
label="Solid"
url="/platforms/javascript/guides/solid/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.solidstart"
label="SolidStart"
url="/platforms/javascript/guides/solidstart/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.svelte"
label="Svelte"
url="/platforms/javascript/guides/svelte/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.sveltekit"
label="SvelteKit"
url="/platforms/javascript/guides/sveltekit/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.vue"
label="Vue"
url="/platforms/javascript/guides/vue/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="javascript.wasm"
label="Wasm"
url="/platforms/javascript/guides/wasm/configuration/options/#propagateTraceparent"
/>

### Mobile

- <LinkWithPlatformIcon
platform="android"
label="Android"
url="/platforms/android/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="dart.flutter"
label="Flutter"
url="/platforms/dart/guides/flutter/configuration/options/#propagateTraceparent"
/>
- <LinkWithPlatformIcon
platform="native"
label="Native"
url="/platforms/native/configuration/options/#propagate_traceparent"
/>
- <LinkWithPlatformIcon
platform="react-native"
label="React Native"
url="/platforms/react-native/configuration/options/#propagateTraceparent"
/>

## 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:

- <LinkWithPlatformIcon
platform="python"
label="Python"
url="/platforms/python/integrations/otlp"
/>
| 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.
61 changes: 61 additions & 0 deletions docs/concepts/otlp/otlp-logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"]
---

<Include name="feature-available-open-beta-logs.mdx" />

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.
Loading