From f68333607b5af1d564c9848e0b0c3bc089def985 Mon Sep 17 00:00:00 2001 From: paulj Date: Mon, 26 Jan 2026 23:55:23 -0500 Subject: [PATCH 01/14] 1st pass exporter content --- docs/concepts/otlp/index.mdx | 1 + docs/concepts/otlp/sentry-exporter.mdx | 182 +++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 docs/concepts/otlp/sentry-exporter.mdx diff --git a/docs/concepts/otlp/index.mdx b/docs/concepts/otlp/index.mdx index 5fde69f3f4272..97f5d08ac3cb3 100644 --- a/docs/concepts/otlp/index.mdx +++ b/docs/concepts/otlp/index.mdx @@ -23,5 +23,6 @@ If you're using a Sentry SDK alongside OTel instrumentation, you can connect the If you're using OTel without a Sentry SDK, or want to ingest telemetry from infrastructure sources: - **[Direct Export](/concepts/otlp/direct/)** - Configure your OTel SDK to send traces and logs directly to Sentry's OTLP endpoints +- **[Sentry Exporter](/concepts/otlp/sentry-exporter/)** - Route telemetry from multiple services to different Sentry projects through a single collector instance - **[Forwarding](/concepts/otlp/forwarding/)** - Use the OpenTelemetry Collector, Vector, or Fluent Bit to forward data from infrastructure sources (CloudWatch, Kafka, Nginx, syslog, etc.) - **[Log and Trace Drains](/product/drains/)** - Send telemetry from managed hosting platforms (Vercel, Cloudflare, Heroku, etc.) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx new file mode 100644 index 0000000000000..7ed0a8815c4a2 --- /dev/null +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -0,0 +1,182 @@ +--- +title: Sentry Exporter +sidebar_order: 10 +description: "Route OpenTelemetry traces and logs from multiple services to different Sentry projects through a single collector instance." +keywords: ["otlp", "otel", "opentelemetry", "collector", "exporter", "routing"] +--- + +The Sentry exporter is an OpenTelemetry Collector component that sends traces and logs to Sentry with automatic project routing. Unlike the generic `otlphttp` exporter, it routes telemetry from multiple services to different Sentry projects through a single collector instance, no routing connector required. + +## When to Use the Sentry Exporter + +Use the Sentry exporter when: + +- You have multiple services that should send to different Sentry projects +- You want to avoid managing per-project DSNs in your collector config +- You need automatic project creation for new services + +For single-project setups, the standard `otlphttp` exporter with a project DSN is sufficient. + +## Prerequisites + +### OpenTelemetry Collector Distribution + +The Sentry exporter is included in [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib). Use `otelcol-contrib` or build a custom collector that includes the `sentryexporter` component. + +### Sentry Auth Token + +Create an Internal Integration in Sentry: + +1. Go to **Settings > Developer Settings > Internal Integrations** +2. Click **Create New Integration** +3. Set permissions: + - **Project**: Read (required) + - **Project**: Write (required if using `auto_create_projects`) +4. Save and copy the token + +Store the token as an environment variable: + +```bash +export SENTRY_AUTH_TOKEN="sntrys_eyJ..." +``` + +### Organization Slug + +Find your organization slug at **Settings > General Settings**, or extract it from your Sentry URL: `https://sentry.io/organizations/{org-slug}/` + +## Configuration Reference + +### Required + +| Parameter | Type | Description | +|-----------|------|-------------| +| `url` | string | Base Sentry URL (e.g., `https://sentry.io`) | +| `org_slug` | string | Your Sentry organization slug | +| `auth_token` | string | Internal Integration token | + +### Optional + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `auto_create_projects` | bool | `false` | Create missing projects automatically | +| `routing.project_from_attribute` | string | `service.name` | Resource attribute for routing | +| `routing.attribute_to_project_mapping` | map | - | Map attribute values to project slugs | +| `http.timeout` | duration | `30s` | HTTP client timeout | +| `sending_queue.enabled` | bool | `true` | Enable the sending queue | + +## Examples + +### Basic Setup + +Routes telemetry based on `service.name`. A service with `service.name: payments-api` sends to the `payments-api` project. + +```yaml +receivers: + otlp: + protocols: + http: + endpoint: 0.0.0.0:4318 + grpc: + endpoint: 0.0.0.0:4317 + +exporters: + sentry: + url: https://sentry.io + org_slug: ${env:SENTRY_ORG_SLUG} + auth_token: ${env:SENTRY_AUTH_TOKEN} + +processors: + batch: + timeout: 1s + send_batch_size: 512 + +service: + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [sentry] + logs: + receivers: [otlp] + processors: [batch] + exporters: [sentry] +``` + +### With Automatic Project Creation + +Creates Sentry projects on-the-fly when a service name doesn't match an existing project: + +```yaml +exporters: + sentry: + url: https://sentry.io + org_slug: ${env:SENTRY_ORG_SLUG} + auth_token: ${env:SENTRY_AUTH_TOKEN} + auto_create_projects: true +``` + +Project creation happens asynchronously, so the first batch of data for a new project may be dropped while the project is being provisioned. + +### With Custom Project Mapping + +Map service names to different Sentry project slugs: + +```yaml +exporters: + sentry: + url: https://sentry.io + org_slug: ${env:SENTRY_ORG_SLUG} + auth_token: ${env:SENTRY_AUTH_TOKEN} + routing: + project_from_attribute: service.name + attribute_to_project_mapping: + orders-service: ecommerce-orders + products-service: ecommerce-products + api-gateway: ecommerce-gateway +``` + +Services not in the mapping use their `service.name` directly as the project slug. + +### With Custom Routing Attribute + +Route by a different resource attribute: + +```yaml +exporters: + sentry: + url: https://sentry.io + org_slug: ${env:SENTRY_ORG_SLUG} + auth_token: ${env:SENTRY_AUTH_TOKEN} + routing: + project_from_attribute: deployment.environment + attribute_to_project_mapping: + production: prod-monitoring + staging: staging-monitoring +``` + +## Rate Limiting + +The exporter automatically respects Sentry's rate limits: + +- Parses `X-Sentry-Rate-Limits` headers from responses +- Maintains per-project, per-category (traces/logs) rate limit deadlines +- Returns throttle errors to the collector queue for automatic retry +- Falls back to 60-second backoff on HTTP 429 without headers + +## Known Limitations + +| Limitation | Impact | Mitigation | +|------------|--------|------------| +| Missing routing attribute | Data is dropped with a warning | Ensure `service.name` is set on all resources | +| Auto-create startup loss | First batch for new projects may be dropped | Subsequent data flows normally | +| Cache drift | Deleted projects cause 403 until cache eviction | Avoid deleting projects while collector is running | +| No per-batch retry | Multi-project batches cannot safely retry | Use sending queue for reliability | +| Single organization | One org per exporter instance | Deploy multiple exporters for multi-org | + +## Connecting Sentry SDK Errors to Traces + + + +## Troubleshooting + + \ No newline at end of file From 9c343e70052c9954716d9f507cb5e1fe6c95bed8 Mon Sep 17 00:00:00 2001 From: paulj Date: Tue, 27 Jan 2026 00:11:22 -0500 Subject: [PATCH 02/14] fix build issue --- docs/concepts/otlp/sentry-exporter.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index 7ed0a8815c4a2..f0493f6cb7690 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -175,8 +175,8 @@ The exporter automatically respects Sentry's rate limits: ## Connecting Sentry SDK Errors to Traces - +{/* TODO: create example */} ## Troubleshooting - \ No newline at end of file +{/* TODO: gather set up issues */} \ No newline at end of file From c2f7da4d60f148ca3f135b6906f232f039d5c55b Mon Sep 17 00:00:00 2001 From: paulj Date: Tue, 27 Jan 2026 10:49:31 -0500 Subject: [PATCH 03/14] add skill section for setup --- docs/concepts/otlp/sentry-exporter.mdx | 34 +++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index f0493f6cb7690..fd46bd11580fd 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -179,4 +179,36 @@ The exporter automatically respects Sentry's rate limits: ## Troubleshooting -{/* TODO: gather set up issues */} \ No newline at end of file +{/* TODO: gather set up issues */} + +## Claude Code Setup Assistant + +If you use [Claude Code](https://code.claude.com), an interactive setup skill is available to help you configure the Sentry exporter step-by-step. + +### Installation + +Install the skill using one of these methods: + +{/* TODO: add installation instructions */} + +**Manual Installation:** +{/* TODO: add installation instructions */} + +### Usage + +Once installed, invoke the skill with: +``` +/sentry-otel-exporter +``` + +Or simply ask Claude Code: +``` +"Help me set up the Sentry OpenTelemetry Exporter" +``` + +The skill will guide you through: +- Creating a Sentry auth token +- Choosing the right routing strategy +- Generating collector configuration +- Testing and verifying the setup +- Troubleshooting common issues \ No newline at end of file From 00d92e6b2486f485d365e6c30bc78d8d0d590d9c Mon Sep 17 00:00:00 2001 From: paulj Date: Mon, 2 Feb 2026 17:25:05 -0500 Subject: [PATCH 04/14] post exporter official merge edits --- docs/concepts/otlp/sentry-exporter.mdx | 34 +++++++++++++++++++++----- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index fd46bd11580fd..fcdd6b4405e1b 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -7,6 +7,8 @@ keywords: ["otlp", "otel", "opentelemetry", "collector", "exporter", "routing"] The Sentry exporter is an OpenTelemetry Collector component that sends traces and logs to Sentry with automatic project routing. Unlike the generic `otlphttp` exporter, it routes telemetry from multiple services to different Sentry projects through a single collector instance, no routing connector required. +For the full specification and source code, see the [sentryexporter documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter) in otel-collector-contrib. + ## When to Use the Sentry Exporter Use the Sentry exporter when: @@ -61,8 +63,9 @@ Find your organization slug at **Settings > General Settings**, or extract it fr | `auto_create_projects` | bool | `false` | Create missing projects automatically | | `routing.project_from_attribute` | string | `service.name` | Resource attribute for routing | | `routing.attribute_to_project_mapping` | map | - | Map attribute values to project slugs | -| `http.timeout` | duration | `30s` | HTTP client timeout | -| `sending_queue.enabled` | bool | `true` | Enable the sending queue | +| `timeout` | duration | `30s` | Exporter timeout | +| `http` | object | - | Standard [confighttp](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp) client settings (timeout, TLS, headers) | +| `sending_queue` | object | enabled | Queue settings from exporterhelper | ## Examples @@ -74,10 +77,10 @@ Routes telemetry based on `service.name`. A service with `service.name: payments receivers: otlp: protocols: - http: - endpoint: 0.0.0.0:4318 grpc: endpoint: 0.0.0.0:4317 + http: + endpoint: 0.0.0.0:4318 exporters: sentry: @@ -87,8 +90,6 @@ exporters: processors: batch: - timeout: 1s - send_batch_size: 512 service: pipelines: @@ -154,6 +155,22 @@ exporters: staging: staging-monitoring ``` +### With Custom HTTP Settings + +Configure timeout and TLS for self-hosted Sentry: + +```yaml +exporters: + sentry: + url: https://sentry.example.com + org_slug: ${env:SENTRY_ORG_SLUG} + auth_token: ${env:SENTRY_AUTH_TOKEN} + timeout: 20s + http: + tls: + insecure_skip_verify: true +``` + ## Rate Limiting The exporter automatically respects Sentry's rate limits: @@ -163,6 +180,10 @@ The exporter automatically respects Sentry's rate limits: - Returns throttle errors to the collector queue for automatic retry - Falls back to 60-second backoff on HTTP 429 without headers +## Stability + +The Sentry exporter has **alpha** stability for traces and logs. + ## Known Limitations | Limitation | Impact | Mitigation | @@ -172,6 +193,7 @@ The exporter automatically respects Sentry's rate limits: | Cache drift | Deleted projects cause 403 until cache eviction | Avoid deleting projects while collector is running | | No per-batch retry | Multi-project batches cannot safely retry | Use sending queue for reliability | | Single organization | One org per exporter instance | Deploy multiple exporters for multi-org | +| No trace connectedness guarantee | The exporter cannot independently ensure trace spans are connected | Configure SDK sampling and trace propagation appropriately | ## Connecting Sentry SDK Errors to Traces From 9f2c6b257f4a385996bc18c3e53db1b784ad1177 Mon Sep 17 00:00:00 2001 From: paulj Date: Mon, 2 Feb 2026 17:33:40 -0500 Subject: [PATCH 05/14] reword --- docs/concepts/otlp/sentry-exporter.mdx | 125 ++++++++++--------------- 1 file changed, 52 insertions(+), 73 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index fcdd6b4405e1b..5915bb40a1be2 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -5,38 +5,36 @@ description: "Route OpenTelemetry traces and logs from multiple services to diff keywords: ["otlp", "otel", "opentelemetry", "collector", "exporter", "routing"] --- -The Sentry exporter is an OpenTelemetry Collector component that sends traces and logs to Sentry with automatic project routing. Unlike the generic `otlphttp` exporter, it routes telemetry from multiple services to different Sentry projects through a single collector instance, no routing connector required. + + The Sentry Exporter has **alpha** stability for traces and logs. + -For the full specification and source code, see the [sentryexporter documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter) in otel-collector-contrib. +The Sentry Exporter routes telemetry from multiple services to different Sentry projects through a single collector instance. Without it, you'd need to configure separate DSNs for each project or set up additional routing connectors. -## When to Use the Sentry Exporter +## When to Use `sentry` vs `otlphttp` Exporters -Use the Sentry exporter when: - -- You have multiple services that should send to different Sentry projects -- You want to avoid managing per-project DSNs in your collector config -- You need automatic project creation for new services - -For single-project setups, the standard `otlphttp` exporter with a project DSN is sufficient. +| Scenario | Recommended Exporter | +|----------|---------------------| +| Single project, all services share one DSN | `otlphttp` | +| Multiple projects, need per-service routing | `sentry` | +| Dynamic environments with auto-provisioning | `sentry` with `auto_create_projects` | ## Prerequisites -### OpenTelemetry Collector Distribution +### Collector Distribution -The Sentry exporter is included in [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib). Use `otelcol-contrib` or build a custom collector that includes the `sentryexporter` component. +The Sentry Exporter is included in [otelcol-contrib](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib). For the full specification, see the [source code](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter). -### Sentry Auth Token +### Auth Token -Create an Internal Integration in Sentry: +In your Sentry account, create an Internal Integration with the required permissions: 1. Go to **Settings > Developer Settings > Internal Integrations** 2. Click **Create New Integration** 3. Set permissions: - - **Project**: Read (required) - - **Project**: Write (required if using `auto_create_projects`) -4. Save and copy the token - -Store the token as an environment variable: + - **Project: Read** - required for endpoint resolution + - **Project: Write** - only if using `auto_create_projects` +4. Copy the token and store it securely: ```bash export SENTRY_AUTH_TOKEN="sntrys_eyJ..." @@ -44,7 +42,7 @@ export SENTRY_AUTH_TOKEN="sntrys_eyJ..." ### Organization Slug -Find your organization slug at **Settings > General Settings**, or extract it from your Sentry URL: `https://sentry.io/organizations/{org-slug}/` +In your Sentry account, go to **Settings > General Settings** to find your organization slug. Alternatively, you can find it in your Sentry URL: `https://sentry.io/organizations/{org-slug}/` ## Configuration Reference @@ -52,7 +50,7 @@ Find your organization slug at **Settings > General Settings**, or extract it fr | Parameter | Type | Description | |-----------|------|-------------| -| `url` | string | Base Sentry URL (e.g., `https://sentry.io`) | +| `url` | string | Base URL of your Sentry instance | | `org_slug` | string | Your Sentry organization slug | | `auth_token` | string | Internal Integration token | @@ -64,16 +62,14 @@ Find your organization slug at **Settings > General Settings**, or extract it fr | `routing.project_from_attribute` | string | `service.name` | Resource attribute for routing | | `routing.attribute_to_project_mapping` | map | - | Map attribute values to project slugs | | `timeout` | duration | `30s` | Exporter timeout | -| `http` | object | - | Standard [confighttp](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp) client settings (timeout, TLS, headers) | +| `http` | object | collector defaults | Standard [confighttp](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp) client settings (timeout, TLS, headers) | | `sending_queue` | object | enabled | Queue settings from exporterhelper | -## Examples +## Basic Configuration -### Basic Setup +By default, the exporter routes telemetry based on `service.name`. A service with `service.name: payments-api` sends to a Sentry project with slug `payments-api`. -Routes telemetry based on `service.name`. A service with `service.name: payments-api` sends to the `payments-api` project. - -```yaml +```yaml {filename:otel-collector-config.yaml} receivers: otlp: protocols: @@ -103,51 +99,48 @@ service: exporters: [sentry] ``` -### With Automatic Project Creation +## Routing Options + +### Automatic Project Creation -Creates Sentry projects on-the-fly when a service name doesn't match an existing project: +When services spin up dynamically (Kubernetes deployments, serverless functions), you may not have pre-created Sentry projects. Enable `auto_create_projects` to provision them on-demand: ```yaml exporters: sentry: - url: https://sentry.io - org_slug: ${env:SENTRY_ORG_SLUG} - auth_token: ${env:SENTRY_AUTH_TOKEN} + # ... required fields auto_create_projects: true ``` -Project creation happens asynchronously, so the first batch of data for a new project may be dropped while the project is being provisioned. + + Project creation is asynchronous. The first batch of data for a new project may be dropped while provisioning completes. + -### With Custom Project Mapping +### Custom Project Mapping -Map service names to different Sentry project slugs: +When your service names don't match your Sentry project slugs (legacy naming, organizational conventions), map them explicitly: ```yaml exporters: sentry: - url: https://sentry.io - org_slug: ${env:SENTRY_ORG_SLUG} - auth_token: ${env:SENTRY_AUTH_TOKEN} + # ... required fields routing: - project_from_attribute: service.name attribute_to_project_mapping: orders-service: ecommerce-orders products-service: ecommerce-products api-gateway: ecommerce-gateway ``` -Services not in the mapping use their `service.name` directly as the project slug. +Services not in the mapping fall back to using `service.name` as the project slug. -### With Custom Routing Attribute +### Routing by Different Attributes -Route by a different resource attribute: +Route by environment, team, or any other resource attribute instead of service name: ```yaml exporters: sentry: - url: https://sentry.io - org_slug: ${env:SENTRY_ORG_SLUG} - auth_token: ${env:SENTRY_AUTH_TOKEN} + # ... required fields routing: project_from_attribute: deployment.environment attribute_to_project_mapping: @@ -155,9 +148,9 @@ exporters: staging: staging-monitoring ``` -### With Custom HTTP Settings +## Self-Hosted Sentry -Configure timeout and TLS for self-hosted Sentry: +For self-hosted installations, configure the base URL and any required TLS settings: ```yaml exporters: @@ -168,40 +161,26 @@ exporters: timeout: 20s http: tls: - insecure_skip_verify: true + insecure_skip_verify: true # Only for development ``` ## Rate Limiting -The exporter automatically respects Sentry's rate limits: +The exporter respects Sentry's rate limits automatically: -- Parses `X-Sentry-Rate-Limits` headers from responses -- Maintains per-project, per-category (traces/logs) rate limit deadlines -- Returns throttle errors to the collector queue for automatic retry +- Parses `X-Sentry-Rate-Limits` headers +- Tracks per-project, per-category (traces/logs) rate limit deadlines +- Returns throttle errors to the collector queue for retry - Falls back to 60-second backoff on HTTP 429 without headers -## Stability - -The Sentry exporter has **alpha** stability for traces and logs. - -## Known Limitations - -| Limitation | Impact | Mitigation | -|------------|--------|------------| -| Missing routing attribute | Data is dropped with a warning | Ensure `service.name` is set on all resources | -| Auto-create startup loss | First batch for new projects may be dropped | Subsequent data flows normally | -| Cache drift | Deleted projects cause 403 until cache eviction | Avoid deleting projects while collector is running | -| No per-batch retry | Multi-project batches cannot safely retry | Use sending queue for reliability | -| Single organization | One org per exporter instance | Deploy multiple exporters for multi-org | -| No trace connectedness guarantee | The exporter cannot independently ensure trace spans are connected | Configure SDK sampling and trace propagation appropriately | - -## Connecting Sentry SDK Errors to Traces - -{/* TODO: create example */} - -## Troubleshooting +## Limitations -{/* TODO: gather set up issues */} +| Limitation | Mitigation | +|------------|------------| +| Missing routing attribute drops data | Ensure `service.name` is set on all resources | +| First batch for auto-created projects may drop | Subsequent data flows normally after provisioning | +| Deleted projects cause 403 until cache evicts | Avoid deleting projects while collector is running | +| Single organization per exporter | Deploy multiple exporters for multi-org setups | ## Claude Code Setup Assistant From 01147cbe468023001ac50e8cd935e22a1e8f2fb8 Mon Sep 17 00:00:00 2001 From: paulj Date: Mon, 2 Feb 2026 18:45:49 -0500 Subject: [PATCH 06/14] skill section --- docs/concepts/otlp/sentry-exporter.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index 5915bb40a1be2..fb1f9751e926e 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -182,34 +182,32 @@ The exporter respects Sentry's rate limits automatically: | Deleted projects cause 403 until cache evicts | Avoid deleting projects while collector is running | | Single organization per exporter | Deploy multiple exporters for multi-org setups | -## Claude Code Setup Assistant +## Additional Tools -If you use [Claude Code](https://code.claude.com), an interactive setup skill is available to help you configure the Sentry exporter step-by-step. + -### Installation +If you use [Claude Code](https://code.claude.com), a setup skill can guide you through configuration step-by-step. -Install the skill using one of these methods: +**Installation:** {/* TODO: add installation instructions */} -**Manual Installation:** -{/* TODO: add installation instructions */} - -### Usage +**Usage:** Once installed, invoke the skill with: ``` /sentry-otel-exporter ``` -Or simply ask Claude Code: +Or ask Claude Code: ``` "Help me set up the Sentry OpenTelemetry Exporter" ``` -The skill will guide you through: +The skill guides you through: - Creating a Sentry auth token - Choosing the right routing strategy - Generating collector configuration - Testing and verifying the setup -- Troubleshooting common issues \ No newline at end of file + + \ No newline at end of file From 51029b27568c98fe4efdb7f1ccb6a8137682e917 Mon Sep 17 00:00:00 2001 From: paulj Date: Tue, 3 Feb 2026 14:32:50 -0500 Subject: [PATCH 07/14] tweaks --- docs/concepts/otlp/sentry-exporter.mdx | 36 +++++++++----------------- 1 file changed, 12 insertions(+), 24 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index fb1f9751e926e..12e831cda1e0f 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -11,7 +11,7 @@ keywords: ["otlp", "otel", "opentelemetry", "collector", "exporter", "routing"] The Sentry Exporter routes telemetry from multiple services to different Sentry projects through a single collector instance. Without it, you'd need to configure separate DSNs for each project or set up additional routing connectors. -## When to Use `sentry` vs `otlphttp` Exporters +## When to Use `sentry` vs `otlphttp` Exporter | Scenario | Recommended Exporter | |----------|---------------------| @@ -23,18 +23,22 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry ### Collector Distribution -The Sentry Exporter is included in [otelcol-contrib](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib). For the full specification, see the [source code](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter). +The Sentry Exporter is included in [otelcol-contrib](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib), the pre-built OpenTelemetry Collector distribution. There is no build step required, just download and run `otelcol-contrib` with your configuration. For the full specification, see the [source code](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter). ### Auth Token In your Sentry account, create an Internal Integration with the required permissions: -1. Go to **Settings > Developer Settings > Internal Integrations** +1. Navigate to **[Custom Integrations](https://sentry.io/orgredirect/organizations/:orgslug/settings/developer-settings/)** 2. Click **Create New Integration** -3. Set permissions: - - **Project: Read** - required for endpoint resolution - - **Project: Write** - only if using `auto_create_projects` -4. Copy the token and store it securely: +3. Choose **Internal Integration** (not Public) +4. Give it a name (e.g., "OTEL Collector") +5. Set permissions: + - **Project: Read** — required + - **Project: Write** — required for `auto_create_projects` +6. Click **Save Changes** +7. After saving, click **Create New Token** +8. Copy the token and store it securely, you won't be able to see it again ```bash export SENTRY_AUTH_TOKEN="sntrys_eyJ..." @@ -42,7 +46,7 @@ export SENTRY_AUTH_TOKEN="sntrys_eyJ..." ### Organization Slug -In your Sentry account, go to **Settings > General Settings** to find your organization slug. Alternatively, you can find it in your Sentry URL: `https://sentry.io/organizations/{org-slug}/` +In your Sentry account, go to **[General Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/)** to find your organization slug. Alternatively, you can find it in your Sentry URL: `https://sentry.io/organizations/{org-slug}/` ## Configuration Reference @@ -148,22 +152,6 @@ exporters: staging: staging-monitoring ``` -## Self-Hosted Sentry - -For self-hosted installations, configure the base URL and any required TLS settings: - -```yaml -exporters: - sentry: - url: https://sentry.example.com - org_slug: ${env:SENTRY_ORG_SLUG} - auth_token: ${env:SENTRY_AUTH_TOKEN} - timeout: 20s - http: - tls: - insecure_skip_verify: true # Only for development -``` - ## Rate Limiting The exporter respects Sentry's rate limits automatically: From 988a0681103bdab8c68e3ed248b6a5533cef647d Mon Sep 17 00:00:00 2001 From: paulj Date: Tue, 3 Feb 2026 20:32:26 -0500 Subject: [PATCH 08/14] update skill section --- docs/concepts/otlp/sentry-exporter.mdx | 83 ++++++++++++++++---------- 1 file changed, 52 insertions(+), 31 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index 12e831cda1e0f..a3875f09bda6c 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -19,6 +19,57 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry | Multiple projects, need per-service routing | `sentry` | | Dynamic environments with auto-provisioning | `sentry` with `auto_create_projects` | +## AI-Assisted Setup + + + +If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), a setup skill can guide you through configuration interactively. + +The skill walks you through: +- Creating a Sentry Internal Integration with the required permissions +- Choosing the right routing strategy (`service.name`, custom attributes, or auto-creation) +- Generating a complete collector configuration for your use case +- Configuring self-hosted Sentry with TLS if needed +- Troubleshooting common issues + +**Installation:** + +Install the [Sentry plugin](https://github.com/getsentry/sentry-for-claude): + +From the Claude Marketplace: +```bash +/plugin marketplace update claude-plugins-official +/plugin install sentry +``` + +Or from local source: +```bash +git clone https://github.com/getsentry/sentry-for-claude.git +cd sentry-for-claude +/plugin marketplace add /path/to/sentry-for-claude +/plugin install sentry@local +``` + +Restart Claude Code to activate the plugin. + +**Usage:** + +Once installed, invoke the skill: + +``` +/sentry-otel-exporter +``` + +Or ask Claude Code: + +``` +"Help me set up the Sentry OpenTelemetry Exporter" +``` + +Claude will interactively guide you through the setup process, generating configuration tailored to your environment. + + + ## Prerequisites ### Collector Distribution @@ -168,34 +219,4 @@ The exporter respects Sentry's rate limits automatically: | Missing routing attribute drops data | Ensure `service.name` is set on all resources | | First batch for auto-created projects may drop | Subsequent data flows normally after provisioning | | Deleted projects cause 403 until cache evicts | Avoid deleting projects while collector is running | -| Single organization per exporter | Deploy multiple exporters for multi-org setups | - -## Additional Tools - - - -If you use [Claude Code](https://code.claude.com), a setup skill can guide you through configuration step-by-step. - -**Installation:** - -{/* TODO: add installation instructions */} - -**Usage:** - -Once installed, invoke the skill with: -``` -/sentry-otel-exporter -``` - -Or ask Claude Code: -``` -"Help me set up the Sentry OpenTelemetry Exporter" -``` - -The skill guides you through: -- Creating a Sentry auth token -- Choosing the right routing strategy -- Generating collector configuration -- Testing and verifying the setup - - \ No newline at end of file +| Single organization per exporter | Deploy multiple exporters for multi-org setups | \ No newline at end of file From f1d4f7bcc8815e29c42cacde3837887f14490acb Mon Sep 17 00:00:00 2001 From: paulj Date: Wed, 4 Feb 2026 10:23:02 -0500 Subject: [PATCH 09/14] tweaks --- docs/concepts/otlp/sentry-exporter.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index a3875f09bda6c..e35892eb00262 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -21,7 +21,7 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry ## AI-Assisted Setup - + If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), a setup skill can guide you through configuration interactively. @@ -92,7 +92,7 @@ In your Sentry account, create an Internal Integration with the required permiss 8. Copy the token and store it securely, you won't be able to see it again ```bash -export SENTRY_AUTH_TOKEN="sntrys_eyJ..." +export SENTRY_AUTH_TOKEN="abc123..." ``` ### Organization Slug From 11c8eb6452a3da3f45fe1cd47691afd9cc26e835 Mon Sep 17 00:00:00 2001 From: paulj Date: Wed, 4 Feb 2026 11:24:52 -0500 Subject: [PATCH 10/14] revise skill section to use the correct repo --- docs/concepts/otlp/sentry-exporter.mdx | 35 +++++++++----------------- 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index e35892eb00262..1a07a29f3aeef 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -21,9 +21,9 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry ## AI-Assisted Setup - + -If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), a setup skill can guide you through configuration interactively. +If you use an AI coding assistant, the `sentry-otel-exporter-setup` skill can guide you through configuration interactively. The skill walks you through: - Creating a Sentry Internal Integration with the required permissions @@ -32,42 +32,31 @@ The skill walks you through: - Configuring self-hosted Sentry with TLS if needed - Troubleshooting common issues -**Installation:** +**Installation (Claude Code):** -Install the [Sentry plugin](https://github.com/getsentry/sentry-for-claude): - -From the Claude Marketplace: ```bash -/plugin marketplace update claude-plugins-official -/plugin install sentry +git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \ + mkdir -p ~/.claude/skills && \ + cp -r /tmp/sentry-skills/skills/* ~/.claude/skills/ && \ + rm -rf /tmp/sentry-skills ``` -Or from local source: -```bash -git clone https://github.com/getsentry/sentry-for-claude.git -cd sentry-for-claude -/plugin marketplace add /path/to/sentry-for-claude -/plugin install sentry@local -``` - -Restart Claude Code to activate the plugin. +See the [Sentry Agent Skills](https://github.com/getsentry/sentry-agent-skills) repo for other agents. **Usage:** -Once installed, invoke the skill: +Ask your AI assistant: ``` -/sentry-otel-exporter +"Set up OTel Collector with Sentry" ``` -Or ask Claude Code: +Or: ``` -"Help me set up the Sentry OpenTelemetry Exporter" +"Configure OpenTelemetry for Sentry with multi-project routing" ``` -Claude will interactively guide you through the setup process, generating configuration tailored to your environment. - ## Prerequisites From 57222203d84a95882314277e991869e557e6ddb1 Mon Sep 17 00:00:00 2001 From: paulj Date: Wed, 11 Feb 2026 17:42:02 -0500 Subject: [PATCH 11/14] udpates --- docs/concepts/otlp/sentry-exporter.mdx | 58 +++++++++++++------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/sentry-exporter.mdx index 1a07a29f3aeef..5d9d5839b529f 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/sentry-exporter.mdx @@ -13,10 +13,10 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry ## When to Use `sentry` vs `otlphttp` Exporter -| Scenario | Recommended Exporter | -|----------|---------------------| -| Single project, all services share one DSN | `otlphttp` | -| Multiple projects, need per-service routing | `sentry` | +| Scenario | Recommended Exporter | +| ------------------------------------------- | ------------------------------------ | +| Single project, all services share one DSN | `otlphttp` | +| Multiple projects, need per-service routing | `sentry` | | Dynamic environments with auto-provisioning | `sentry` with `auto_create_projects` | ## AI-Assisted Setup @@ -26,19 +26,17 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry If you use an AI coding assistant, the `sentry-otel-exporter-setup` skill can guide you through configuration interactively. The skill walks you through: + - Creating a Sentry Internal Integration with the required permissions - Choosing the right routing strategy (`service.name`, custom attributes, or auto-creation) - Generating a complete collector configuration for your use case - Configuring self-hosted Sentry with TLS if needed - Troubleshooting common issues -**Installation (Claude Code):** +**Installation:** ```bash -git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \ - mkdir -p ~/.claude/skills && \ - cp -r /tmp/sentry-skills/skills/* ~/.claude/skills/ && \ - rm -rf /tmp/sentry-skills +npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-otel-exporter-setup ``` See the [Sentry Agent Skills](https://github.com/getsentry/sentry-agent-skills) repo for other agents. @@ -74,6 +72,7 @@ In your Sentry account, create an Internal Integration with the required permiss 3. Choose **Internal Integration** (not Public) 4. Give it a name (e.g., "OTEL Collector") 5. Set permissions: + - **Organization: Read** — required - **Project: Read** — required - **Project: Write** — required for `auto_create_projects` 6. Click **Save Changes** @@ -92,22 +91,22 @@ In your Sentry account, go to **[General Settings](https://sentry.io/orgredirect ### Required -| Parameter | Type | Description | -|-----------|------|-------------| -| `url` | string | Base URL of your Sentry instance | -| `org_slug` | string | Your Sentry organization slug | -| `auth_token` | string | Internal Integration token | +| Parameter | Type | Description | +| ------------ | ------ | -------------------------------- | +| `url` | string | Base URL of your Sentry instance | +| `org_slug` | string | Your Sentry organization slug | +| `auth_token` | string | Internal Integration token | ### Optional -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `auto_create_projects` | bool | `false` | Create missing projects automatically | -| `routing.project_from_attribute` | string | `service.name` | Resource attribute for routing | -| `routing.attribute_to_project_mapping` | map | - | Map attribute values to project slugs | -| `timeout` | duration | `30s` | Exporter timeout | -| `http` | object | collector defaults | Standard [confighttp](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp) client settings (timeout, TLS, headers) | -| `sending_queue` | object | enabled | Queue settings from exporterhelper | +| Parameter | Type | Default | Description | +| -------------------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| `auto_create_projects` | bool | `false` | Create missing projects automatically - requires one existing team | +| `routing.project_from_attribute` | string | `service.name` | Resource attribute for routing | +| `routing.attribute_to_project_mapping` | map | - | Map attribute values to project slugs | +| `timeout` | duration | `30s` | Exporter timeout | +| `http` | object | collector defaults | Standard [confighttp](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp) client settings (timeout, TLS, headers) | +| `sending_queue` | object | enabled | Queue settings from exporterhelper | ## Basic Configuration @@ -157,7 +156,8 @@ exporters: ``` - Project creation is asynchronous. The first batch of data for a new project may be dropped while provisioning completes. + Project creation is asynchronous. The first batch of data for a new project + may be dropped while provisioning completes. ### Custom Project Mapping @@ -203,9 +203,9 @@ The exporter respects Sentry's rate limits automatically: ## Limitations -| Limitation | Mitigation | -|------------|------------| -| Missing routing attribute drops data | Ensure `service.name` is set on all resources | -| First batch for auto-created projects may drop | Subsequent data flows normally after provisioning | -| Deleted projects cause 403 until cache evicts | Avoid deleting projects while collector is running | -| Single organization per exporter | Deploy multiple exporters for multi-org setups | \ No newline at end of file +| Limitation | Mitigation | +| ---------------------------------------------- | -------------------------------------------------- | +| Missing routing attribute drops data | Ensure `service.name` is set on all resources | +| First batch for auto-created projects may drop | Subsequent data flows normally after provisioning | +| Deleted projects cause 403 until cache evicts | Avoid deleting projects while collector is running | +| Single organization per exporter | Deploy multiple exporters for multi-org setups | From e8575c5334b9660dd7186bc7b6236b7a5772a4f6 Mon Sep 17 00:00:00 2001 From: paulj Date: Wed, 11 Feb 2026 18:13:53 -0500 Subject: [PATCH 12/14] move sentry-exporter under forwarding/pipelines - Move sentry-exporter.mdx to forwarding/pipelines/ for better organization - Update links in all related pages - Add cross-reference in collector.mdx pointing to Sentry Exporter - Highlight auto-create projects feature in all mentions Co-Authored-By: Claude --- docs/concepts/otlp/forwarding/index.mdx | 2 +- docs/concepts/otlp/forwarding/pipelines/collector.mdx | 8 +++++++- docs/concepts/otlp/forwarding/pipelines/index.mdx | 1 + .../otlp/{ => forwarding/pipelines}/sentry-exporter.mdx | 3 ++- docs/concepts/otlp/index.mdx | 2 +- 5 files changed, 12 insertions(+), 4 deletions(-) rename docs/concepts/otlp/{ => forwarding/pipelines}/sentry-exporter.mdx (99%) diff --git a/docs/concepts/otlp/forwarding/index.mdx b/docs/concepts/otlp/forwarding/index.mdx index 6169aa4ebcf47..7e0bbc0ec93a7 100644 --- a/docs/concepts/otlp/forwarding/index.mdx +++ b/docs/concepts/otlp/forwarding/index.mdx @@ -5,7 +5,7 @@ sidebar_order: 30 description: Forward logs and traces to Sentry from various sources using the OpenTelemetry Collector, Vector, or Fluent Bit. --- -Forward logs and traces to Sentry from infrastructure sources using a pipeline tool like the [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/), [Vector](/concepts/otlp/forwarding/pipelines/vector/), or [Fluent Bit](/concepts/otlp/forwarding/pipelines/fluentbit/). This approach doesn't require modifying application code. +Forward logs and traces to Sentry from infrastructure sources using a pipeline tool like the [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/), [Vector](/concepts/otlp/forwarding/pipelines/vector/), or [Fluent Bit](/concepts/otlp/forwarding/pipelines/fluentbit/). For multi-project routing with automatic project creation, use the [Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/). This approach doesn't require modifying application code. Use forwarding when: - You need to collect logs from infrastructure (cloud services, web servers, message queues) diff --git a/docs/concepts/otlp/forwarding/pipelines/collector.mdx b/docs/concepts/otlp/forwarding/pipelines/collector.mdx index 43a2db4008dd0..4f58c5421575c 100644 --- a/docs/concepts/otlp/forwarding/pipelines/collector.mdx +++ b/docs/concepts/otlp/forwarding/pipelines/collector.mdx @@ -125,11 +125,17 @@ exporters: ## Routing to Multiple Projects + + +For simpler multi-project routing, consider the [Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/) which routes telemetry based on `service.name` without a routing connector, and can automatically create new Sentry projects on-demand. + + + -Sentry's OTLP endpoints are project-specific. To route telemetry from different services to different Sentry projects, use the [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector). +Sentry's OTLP endpoints are project-specific. To route telemetry from different services to different Sentry projects using `otlphttp`, use the [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector). This example routes logs to different Sentry projects based on the `service.name` attribute: diff --git a/docs/concepts/otlp/forwarding/pipelines/index.mdx b/docs/concepts/otlp/forwarding/pipelines/index.mdx index 1e4dba7eddc91..2aff884aa1329 100644 --- a/docs/concepts/otlp/forwarding/pipelines/index.mdx +++ b/docs/concepts/otlp/forwarding/pipelines/index.mdx @@ -10,6 +10,7 @@ Pipelines collect telemetry from infrastructure sources (like log files, message | Pipeline | Best For | |----------|----------| | [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/) | Supports logs and traces from many sources | +| [Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/) | Multi-project routing with automatic project creation | | [Vector](/concepts/otlp/forwarding/pipelines/vector/) | Log routing with powerful filtering and low resource usage | | [Fluent Bit](/concepts/otlp/forwarding/pipelines/fluentbit/) | Logs and traces with minimal resource footprint | diff --git a/docs/concepts/otlp/sentry-exporter.mdx b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx similarity index 99% rename from docs/concepts/otlp/sentry-exporter.mdx rename to docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx index 5d9d5839b529f..7f12c79fb11d4 100644 --- a/docs/concepts/otlp/sentry-exporter.mdx +++ b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx @@ -1,6 +1,7 @@ --- title: Sentry Exporter -sidebar_order: 10 +sidebar_title: Sentry Exporter +sidebar_order: 15 description: "Route OpenTelemetry traces and logs from multiple services to different Sentry projects through a single collector instance." keywords: ["otlp", "otel", "opentelemetry", "collector", "exporter", "routing"] --- diff --git a/docs/concepts/otlp/index.mdx b/docs/concepts/otlp/index.mdx index 97f5d08ac3cb3..8830f8323642f 100644 --- a/docs/concepts/otlp/index.mdx +++ b/docs/concepts/otlp/index.mdx @@ -23,6 +23,6 @@ If you're using a Sentry SDK alongside OTel instrumentation, you can connect the If you're using OTel without a Sentry SDK, or want to ingest telemetry from infrastructure sources: - **[Direct Export](/concepts/otlp/direct/)** - Configure your OTel SDK to send traces and logs directly to Sentry's OTLP endpoints -- **[Sentry Exporter](/concepts/otlp/sentry-exporter/)** - Route telemetry from multiple services to different Sentry projects through a single collector instance - **[Forwarding](/concepts/otlp/forwarding/)** - Use the OpenTelemetry Collector, Vector, or Fluent Bit to forward data from infrastructure sources (CloudWatch, Kafka, Nginx, syslog, etc.) + - **[Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/)** - Route telemetry to different Sentry projects automatically, with optional auto-creation of new projects - **[Log and Trace Drains](/product/drains/)** - Send telemetry from managed hosting platforms (Vercel, Cloudflare, Heroku, etc.) From 14ffc53526cb8632e7b40f389a5733a54c7b2c8f Mon Sep 17 00:00:00 2001 From: paulj Date: Thu, 12 Feb 2026 16:29:21 -0500 Subject: [PATCH 13/14] updates --- docs/concepts/otlp/forwarding/index.mdx | 2 +- .../forwarding/pipelines/sentry-exporter.mdx | 71 ++++++++++++++----- .../otlp/forwarding/sources/index.mdx | 2 +- docs/concepts/otlp/index.mdx | 11 +-- 4 files changed, 63 insertions(+), 23 deletions(-) diff --git a/docs/concepts/otlp/forwarding/index.mdx b/docs/concepts/otlp/forwarding/index.mdx index 7e0bbc0ec93a7..38a3d2101b11d 100644 --- a/docs/concepts/otlp/forwarding/index.mdx +++ b/docs/concepts/otlp/forwarding/index.mdx @@ -5,7 +5,7 @@ sidebar_order: 30 description: Forward logs and traces to Sentry from various sources using the OpenTelemetry Collector, Vector, or Fluent Bit. --- -Forward logs and traces to Sentry from infrastructure sources using a pipeline tool like the [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/), [Vector](/concepts/otlp/forwarding/pipelines/vector/), or [Fluent Bit](/concepts/otlp/forwarding/pipelines/fluentbit/). For multi-project routing with automatic project creation, use the [Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/). This approach doesn't require modifying application code. +Forward logs and traces to Sentry from infrastructure sources using a pipeline tool like the [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/), [Vector](/concepts/otlp/forwarding/pipelines/vector/), or [Fluent Bit](/concepts/otlp/forwarding/pipelines/fluentbit/). For multi-project routing with automatic project creation in Sentry, use the [Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/). This approach doesn't require modifying application code. Use forwarding when: - You need to collect logs from infrastructure (cloud services, web servers, message queues) diff --git a/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx index 7f12c79fb11d4..b9458f3747236 100644 --- a/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx +++ b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx @@ -24,23 +24,22 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry -If you use an AI coding assistant, the `sentry-otel-exporter-setup` skill can guide you through configuration interactively. +If you use an AI agent (like Claude Code or Cursor), the `sentry-otel-exporter-setup` skill can guide you through configuring the Sentry Exporter interactively. The skill walks you through: -- Creating a Sentry Internal Integration with the required permissions -- Choosing the right routing strategy (`service.name`, custom attributes, or auto-creation) -- Generating a complete collector configuration for your use case -- Configuring self-hosted Sentry with TLS if needed -- Troubleshooting common issues +- Choosing an installation method (binary or Docker) +- Configuring automatic project creation +- Generating a complete collector configuration +- Setting up environment variables for authentication **Installation:** ```bash -npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-otel-exporter-setup +npx skills add https://github.com/getsentry/agent-skills --skill sentry-otel-exporter-setup ``` -See the [Sentry Agent Skills](https://github.com/getsentry/sentry-agent-skills) repo for other agents. +See the [Sentry Agent Skills](https://github.com/getsentry/agent-skills) repo for other agents. **Usage:** @@ -111,8 +110,15 @@ In your Sentry account, go to **[General Settings](https://sentry.io/orgredirect ## Basic Configuration + + + + By default, the exporter routes telemetry based on `service.name`. A service with `service.name: payments-api` sends to a Sentry project with slug `payments-api`. + + + ```yaml {filename:otel-collector-config.yaml} receivers: otlp: @@ -143,11 +149,27 @@ service: exporters: [sentry] ``` + + + + ## Routing Options + + + + ### Automatic Project Creation -When services spin up dynamically (Kubernetes deployments, serverless functions), you may not have pre-created Sentry projects. Enable `auto_create_projects` to provision them on-demand: +When services spin up dynamically (Kubernetes deployments, serverless functions), you may not have pre-created Sentry projects. Enable `auto_create_projects` to provision them on-demand. + + + Project creation is asynchronous. The first batch of data for a new project + may be dropped while provisioning completes. + + + + ```yaml exporters: @@ -156,14 +178,20 @@ exporters: auto_create_projects: true ``` - - Project creation is asynchronous. The first batch of data for a new project - may be dropped while provisioning completes. - + + + + + ### Custom Project Mapping -When your service names don't match your Sentry project slugs (legacy naming, organizational conventions), map them explicitly: +When your service names don't match your Sentry project slugs (legacy naming, organizational conventions), map them explicitly. + +Services not in the mapping fall back to using `service.name` as the project slug. + + + ```yaml exporters: @@ -176,11 +204,18 @@ exporters: api-gateway: ecommerce-gateway ``` -Services not in the mapping fall back to using `service.name` as the project slug. + + + + + ### Routing by Different Attributes -Route by environment, team, or any other resource attribute instead of service name: +Route by environment, team, or any other resource attribute instead of service name. + + + ```yaml exporters: @@ -193,6 +228,10 @@ exporters: staging: staging-monitoring ``` + + + + ## Rate Limiting The exporter respects Sentry's rate limits automatically: diff --git a/docs/concepts/otlp/forwarding/sources/index.mdx b/docs/concepts/otlp/forwarding/sources/index.mdx index 92a9407c1d283..b0fbc571eecac 100644 --- a/docs/concepts/otlp/forwarding/sources/index.mdx +++ b/docs/concepts/otlp/forwarding/sources/index.mdx @@ -1,6 +1,6 @@ --- title: Source Guides -sidebar_title: Sources +sidebar_title: Source Guides sidebar_order: 20 description: Guides for forwarding data from specific sources to Sentry using the OpenTelemetry Collector. --- diff --git a/docs/concepts/otlp/index.mdx b/docs/concepts/otlp/index.mdx index 8830f8323642f..c74e2f1862d9e 100644 --- a/docs/concepts/otlp/index.mdx +++ b/docs/concepts/otlp/index.mdx @@ -9,7 +9,7 @@ keywords: ["otlp", "otel", "opentelemetry"] Sentry can ingest OpenTelemetry traces and logs via OTLP endpoints, either directly from an [OTel SDK](https://opentelemetry.io/docs/languages/) or through a pipeline tool like the [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/). Sentry does not support OTLP metrics at this time. -## Linking Traces with Sentry SDK +## Linking Traces with a Sentry SDK If you're using a Sentry SDK alongside OTel instrumentation, you can connect them to share trace context: @@ -22,7 +22,8 @@ If you're using a Sentry SDK alongside OTel instrumentation, you can connect the If you're using OTel without a Sentry SDK, or want to ingest telemetry from infrastructure sources: -- **[Direct Export](/concepts/otlp/direct/)** - Configure your OTel SDK to send traces and logs directly to Sentry's OTLP endpoints -- **[Forwarding](/concepts/otlp/forwarding/)** - Use the OpenTelemetry Collector, Vector, or Fluent Bit to forward data from infrastructure sources (CloudWatch, Kafka, Nginx, syslog, etc.) - - **[Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/)** - Route telemetry to different Sentry projects automatically, with optional auto-creation of new projects -- **[Log and Trace Drains](/product/drains/)** - Send telemetry from managed hosting platforms (Vercel, Cloudflare, Heroku, etc.) +| Method | When to Use | +|--------|-------------| +| **[Direct Export](/concepts/otlp/direct/)** | OTel SDK sending traces and logs straight to Sentry | +| **[Forwarding](/concepts/otlp/forwarding/)** | Infrastructure sources via OTel Collector, Vector, or Fluent Bit. Use the [Sentry Exporter](/concepts/otlp/forwarding/pipelines/sentry-exporter/) for multi-project routing. | +| **[Log and Trace Drains](/product/drains/)** | Managed platforms (Vercel, Cloudflare, Heroku) | From eb5430db3566031406358330d37aaf90514b37db Mon Sep 17 00:00:00 2001 From: paulj Date: Fri, 13 Feb 2026 14:22:02 -0500 Subject: [PATCH 14/14] docs(sentry-exporter): Clarify alpha stability and remove AI setup section Expand the alpha stability alert to set clearer expectations about potential configuration changes. Remove the AI-Assisted Setup section to streamline the documentation. Co-Authored-By: Claude --- .../forwarding/pipelines/sentry-exporter.mdx | 39 +------------------ 1 file changed, 1 insertion(+), 38 deletions(-) diff --git a/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx index b9458f3747236..6854b68ff8c84 100644 --- a/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx +++ b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx @@ -7,7 +7,7 @@ keywords: ["otlp", "otel", "opentelemetry", "collector", "exporter", "routing"] --- - The Sentry Exporter has **alpha** stability for traces and logs. + The Sentry Exporter has **alpha** stability for traces and logs. Configuration options and behavior may change. The Sentry Exporter routes telemetry from multiple services to different Sentry projects through a single collector instance. Without it, you'd need to configure separate DSNs for each project or set up additional routing connectors. @@ -20,43 +20,6 @@ The Sentry Exporter routes telemetry from multiple services to different Sentry | Multiple projects, need per-service routing | `sentry` | | Dynamic environments with auto-provisioning | `sentry` with `auto_create_projects` | -## AI-Assisted Setup - - - -If you use an AI agent (like Claude Code or Cursor), the `sentry-otel-exporter-setup` skill can guide you through configuring the Sentry Exporter interactively. - -The skill walks you through: - -- Choosing an installation method (binary or Docker) -- Configuring automatic project creation -- Generating a complete collector configuration -- Setting up environment variables for authentication - -**Installation:** - -```bash -npx skills add https://github.com/getsentry/agent-skills --skill sentry-otel-exporter-setup -``` - -See the [Sentry Agent Skills](https://github.com/getsentry/agent-skills) repo for other agents. - -**Usage:** - -Ask your AI assistant: - -``` -"Set up OTel Collector with Sentry" -``` - -Or: - -``` -"Configure OpenTelemetry for Sentry with multi-project routing" -``` - - - ## Prerequisites ### Collector Distribution