feat(docs): sentry exporter (otel)

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)

docs/concepts/otlp/forwarding/pipelines/collector.mdx

@@ -125,11 +125,17 @@ exporters:
 
 ## Routing to Multiple Projects
 
+<Alert level="info">
+
+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.
+
+</Alert>
+
 <SplitLayout>
 <SplitSection>
 <SplitSectionText>
 
-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:
 

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 |
 

docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx

@@ -0,0 +1,212 @@
+---
+title: Sentry Exporter
+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"]
+---
+
+<Alert level="info">
+  The Sentry Exporter has **alpha** stability for traces and logs.
+</Alert>
+
+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
+
+| 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
+
+<Expandable title="Interactive Setup with AI Agent Skills" level="success">
+
+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:**
+
+```bash
+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.
+
+**Usage:**
+
+Ask your AI assistant:
+
+```
+"Set up OTel Collector with Sentry"
+```
+
+Or:
+
+```
+"Configure OpenTelemetry for Sentry with multi-project routing"
+```
+
+</Expandable>
+
+## Prerequisites
+
+### 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
+
+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
+
+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
+
+### 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
+
+| 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
+
+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:
+    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
+
+### 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:
+
+```yaml
+exporters:
+  sentry:
+    # ... required fields
+    auto_create_projects: true
+```
+
+<Alert level="warning">
+  Project creation is asynchronous. The first batch of data for a new project
+  may be dropped while provisioning completes.
+</Alert>
+
+### Custom Project Mapping
+
+When your service names don't match your Sentry project slugs (legacy naming, organizational conventions), map them explicitly:
+
+```yaml
+exporters:
+  sentry:
+    # ... required fields
+    routing:
+      attribute_to_project_mapping:
+        orders-service: ecommerce-orders
+        products-service: ecommerce-products
+        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:
+
+```yaml
+exporters:
+  sentry:
+    # ... required fields
+    routing:
+      project_from_attribute: deployment.environment
+      attribute_to_project_mapping:
+        production: prod-monitoring
+        staging: staging-monitoring
+```
+
+## 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
+
+| 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     |

docs/concepts/otlp/index.mdx

@@ -24,4 +24,5 @@ If you're using OTel without a Sentry SDK, or want to ingest telemetry from infr
 
 - **[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.)