diff --git a/docs/concepts/otlp/forwarding/index.mdx b/docs/concepts/otlp/forwarding/index.mdx index 6169aa4ebcf47..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/). 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/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/forwarding/pipelines/sentry-exporter.mdx b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx new file mode 100644 index 0000000000000..b9458f3747236 --- /dev/null +++ b/docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx @@ -0,0 +1,251 @@ +--- +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"] +--- + + + The Sentry Exporter has **alpha** stability for traces and logs. + + +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 + + + +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 + +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. + + + 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 + +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 + +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 | 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 5fde69f3f4272..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,6 +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.) -- **[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) |