-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
feat(docs): sentry exporter (otel) #16165
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+230
−7
Merged
Changes from all commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
f683336
1st pass exporter content
jaffrepaul 9c343e7
fix build issue
jaffrepaul c2f7da4
add skill section for setup
jaffrepaul 00d92e6
post exporter official merge edits
jaffrepaul 9f2c6b2
reword
jaffrepaul 01147cb
skill section
jaffrepaul 51029b2
tweaks
jaffrepaul 988a068
update skill section
jaffrepaul f1d4f7b
tweaks
jaffrepaul 11c8eb6
revise skill section to use the correct repo
jaffrepaul 5722220
udpates
jaffrepaul e8575c5
move sentry-exporter under forwarding/pipelines
jaffrepaul 14ffc53
updates
jaffrepaul a5c8fa8
Merge branch 'master' into sentry-otel-exporter
jaffrepaul eb5430d
docs(sentry-exporter): Clarify alpha stability and remove AI setup se…
jaffrepaul eed39f3
Merge branch 'master' into sentry-otel-exporter
jaffrepaul File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
214 changes: 214 additions & 0 deletions
214
docs/concepts/otlp/forwarding/pipelines/sentry-exporter.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,214 @@ | ||
| --- | ||
| 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. Configuration options and behavior may change. | ||
| </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` | | ||
|
|
||
| ## 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 | ||
|
|
||
| <SplitLayout> | ||
| <SplitSection> | ||
| <SplitSectionText> | ||
|
|
||
| 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`. | ||
|
|
||
| </SplitSectionText> | ||
| <SplitSectionCode> | ||
|
|
||
| ```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] | ||
| ``` | ||
|
|
||
| </SplitSectionCode> | ||
| </SplitSection> | ||
| </SplitLayout> | ||
|
|
||
| ## Routing Options | ||
|
|
||
| <SplitLayout> | ||
| <SplitSection> | ||
| <SplitSectionText> | ||
|
|
||
| ### 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. | ||
|
|
||
| <Alert level="warning"> | ||
| Project creation is asynchronous. The first batch of data for a new project | ||
| may be dropped while provisioning completes. | ||
| </Alert> | ||
|
|
||
| </SplitSectionText> | ||
| <SplitSectionCode> | ||
|
|
||
| ```yaml | ||
| exporters: | ||
| sentry: | ||
| # ... required fields | ||
| auto_create_projects: true | ||
| ``` | ||
|
|
||
| </SplitSectionCode> | ||
| </SplitSection> | ||
|
|
||
| <SplitSection> | ||
| <SplitSectionText> | ||
|
|
||
| ### 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. | ||
|
|
||
| </SplitSectionText> | ||
| <SplitSectionCode> | ||
|
|
||
| ```yaml | ||
| exporters: | ||
| sentry: | ||
| # ... required fields | ||
| routing: | ||
| attribute_to_project_mapping: | ||
| orders-service: ecommerce-orders | ||
| products-service: ecommerce-products | ||
| api-gateway: ecommerce-gateway | ||
| ``` | ||
|
|
||
| </SplitSectionCode> | ||
| </SplitSection> | ||
|
|
||
| <SplitSection> | ||
| <SplitSectionText> | ||
|
|
||
| ### Routing by Different Attributes | ||
|
|
||
| Route by environment, team, or any other resource attribute instead of service name. | ||
|
|
||
| </SplitSectionText> | ||
| <SplitSectionCode> | ||
|
|
||
| ```yaml | ||
| exporters: | ||
| sentry: | ||
| # ... required fields | ||
| routing: | ||
| project_from_attribute: deployment.environment | ||
| attribute_to_project_mapping: | ||
| production: prod-monitoring | ||
| staging: staging-monitoring | ||
| ``` | ||
|
|
||
| </SplitSectionCode> | ||
| </SplitSection> | ||
| </SplitLayout> | ||
|
|
||
| ## 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 | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a difference in terms of what the experience will be using data through OTel vs Sentry SDK?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Depends on what you mean. Data comes into Sentry via the our SDK or Otel. Once in Sentry users can work with logs, traces and errors (if linked). The experience getting the data in may be different but once it's in, it's Sentry. The only thing I can think of is some nuance with the level of trace connected-ness to errors.