--- title: "Sentry Exporter" description: "Route OpenTelemetry traces and logs from multiple services to different Sentry projects through a single collector instance." url: https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter/ --- # Sentry Exporter 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. ## [When to Use `sentry` vs `otlphttp` Exporter](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#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` | | Dynamic environments with auto-provisioning | `sentry` with `auto_create_projects` | ## [Prerequisites](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#prerequisites) ### [Collector Distribution](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#collector-distribution) 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](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#auth-token) In your Sentry account, create an Internal Integration with the required permissions: 1. Navigate to **[Custom Integrations](https://sentry.io/orgredirect/organizations/:orgslug/settings/developer-settings/)** 2. Click **Create New Integration** 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** 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="abc123..." ``` ### [Organization Slug](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#organization-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](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#configuration-reference) ### [Required](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#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 | ### [Optional](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#optional) | 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](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#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`. `otel-collector-config.yaml` ```yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: sentry: url: https://sentry.io org_slug: ${env:SENTRY_ORG_SLUG} auth_token: ${env:SENTRY_AUTH_TOKEN} processors: batch: service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [sentry] logs: receivers: [otlp] processors: [batch] exporters: [sentry] ``` ## [Routing Options](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#routing-options) ### [Automatic Project Creation](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#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. Project creation is asynchronous. The first batch of data for a new project may be dropped while provisioning completes. ```yaml exporters: sentry: # ... required fields auto_create_projects: true ``` ### [Custom Project Mapping](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#custom-project-mapping) 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: sentry: # ... required fields routing: attribute_to_project_mapping: orders-service: ecommerce-orders products-service: ecommerce-products api-gateway: ecommerce-gateway ``` ### [Routing by Different Attributes](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#routing-by-different-attributes) Route by environment, team, or any other resource attribute instead of service name. ```yaml exporters: sentry: # ... required fields routing: project_from_attribute: deployment.environment attribute_to_project_mapping: production: prod-monitoring staging: staging-monitoring ``` ## [Rate Limiting](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#rate-limiting) The exporter respects Sentry's rate limits automatically: * 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 ## [Limitations](https://docs.sentry.io/concepts/otlp/forwarding/pipelines/sentry-exporter.md#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 |