docs(otlp): Consolidate OTLP content and restructure navigation #16297
Conversation
Move OTLP-related content from product/drains to concepts/otlp for clearer information architecture: - Move OTel Collector docs to concepts/otlp/collector/ - Move collector guides (AWS CloudWatch, Kafka, Nginx, syslog, Windows) to concepts/otlp/collector/ - Move Vector and Fluent Bit docs to concepts/otlp/forwarders/ - Update product/drains to focus on platform drains only (Vercel, Cloudflare, Heroku, etc.) - Update all cross-references This creates clearer separation: - concepts/otlp = OTLP protocols and tools (Collector, Vector, Fluent Bit) - product/drains = Platform-specific managed integrations Co-Authored-By: Claude <noreply@anthropic.com>
Reorganize OTLP documentation for clearer information architecture:
- Create direct/ section for SDK-to-Sentry export (traces, logs)
- Create forwarding/ section with pipelines/ (Collector, Vector, Fluent Bit)
and sources/ (AWS CloudWatch, Kafka, Nginx, Syslog, Windows Events)
- Update index page to clarify Sentry SDK linking vs OTel data ingestion
- Simplify page titles and sidebar navigation
- Update all cross-references
Structure:
otlp/
├── sentry-with-otel.mdx
├── direct/
│ ├── traces.mdx
│ └── logs.mdx
└── forwarding/
├── tools/ (sidebar: Pipelines)
│ ├── collector.mdx
│ ├── vector.mdx
│ └── fluentbit.mdx
└── sources/
├── aws-cloudwatch.mdx
├── kafka.mdx
├── nginx.mdx
├── syslog.mdx
└── windows-events.mdx
Co-Authored-By: Claude <noreply@anthropic.com>
Add dedicated subpages for each platform drain to provide focused navigation in the sidebar. Each platform now appears as a child of Platform Drains with its own page. - Add sidebar_title for cleaner nav names - Update internal links to new paths Co-Authored-By: Claude <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Add embedded video for setting up Vercel drains. Clarify that Vercel Pro or higher plan is required in the prerequisites section. Co-Authored-By: Claude <noreply@anthropic.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
This file is no longer referenced after the collector.mdx file was removed in the OTLP docs restructuring. Co-Authored-By: Claude <noreply@anthropic.com>
- Rename "Platform Drains" to "Log and Trace Drains" throughout - Add callouts explaining difference between drains and OTLP forwarding to help users choose the right approach - Consolidate limitation alerts into dedicated Limitations section - Simplify callout text to use OpenTelemetry Collector as example Co-Authored-By: Claude <noreply@anthropic.com>
Rename the forwarding tools directory to pipelines for clearer naming. Update all internal links to reflect the new path structure. Co-Authored-By: Claude <noreply@anthropic.com>
| 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, Vector, or Fluent Bit. This approach doesn't require modifying application code. |
There was a problem hiding this comment.
I see we have docs talking about each of these. Let's link to each approach here. (Collector, Vector, Fluent Bit)
There was a problem hiding this comment.
Looks like we could link to the pages nested here: /concepts/otlp/forwarding/pipelines/
| title: Direct OTLP Traces | ||
| sidebar_title: Traces | ||
| sidebar_order: 10 | ||
| description: "Send OpenTelemetry traces directly to Sentry without a Sentry SDK." |
There was a problem hiding this comment.
You still need to have integrated with the Sentry SDK to use Sentry though, yeah?
| description: "Send OpenTelemetry traces directly to Sentry without a Sentry SDK." | |
| description: "Send OpenTelemetry traces directly to Sentry without using the Sentry SDK." |
There was a problem hiding this comment.
Not necessarily. The use case is for those with Otel instrumented backends and no Sentry SDK. So they can send that Otel data into Sentry through the endpoint and use the trace & logs explorers in a project but their app doesn't have a Sentry SDK.
docs/concepts/otlp/direct/logs.mdx
Outdated
|
|
||
| <Include name="feature-available-open-beta-logs.mdx" /> | ||
|
|
||
| Send logs directly from your OpenTelemetry SDK to Sentry's OTLP endpoint. You can find your endpoint URL and auth key in [Project settings > Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/). |
There was a problem hiding this comment.
| Send logs directly from your OpenTelemetry SDK to Sentry's OTLP endpoint. You can find your endpoint URL and auth key in [Project settings > Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/). | |
| Send logs directly from your OpenTelemetry SDK to Sentry's OTLP endpoint. You can find your endpoint URL and auth key in [Project settings > Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/keys/). |
| @@ -0,0 +1,52 @@ | |||
| --- | |||
| title: Direct OTLP Logs | |||
There was a problem hiding this comment.
Meta comment on this doc - I don't understand the value I am getting from this integration because this is a thin doc about how to set it up, with the main detail about logs ingestion being that there are limitations.
There was a problem hiding this comment.
Its quite literally docs that covers where to get a URL and where to put it for a specific demographic/use case. We mention the use case in the parent page. Could also put it on these pages to be clear?
docs/concepts/otlp/direct/index.mdx
Outdated
| description: Send OpenTelemetry traces and logs directly to Sentry from your OTel SDK. | ||
| --- | ||
|
|
||
| Configure your OpenTelemetry SDK to send traces and logs directly to Sentry's OTLP endpoints. This approach doesn't require an intermediary like the OpenTelemetry Collector. |
There was a problem hiding this comment.
| Configure your OpenTelemetry SDK to send traces and logs directly to Sentry's OTLP endpoints. This approach doesn't require an intermediary like the OpenTelemetry Collector. | |
| Configure your OpenTelemetry SDK to send traces and logs directly to Sentry's OTLP endpoints without an intermediary. |
Do we need to mention Collector? If not, let's keep this concise.
| @@ -0,0 +1,50 @@ | |||
| --- | |||
| title: Direct OTLP Traces | |||
There was a problem hiding this comment.
Meta comment here - it's hard to understand the value of this integration when the most descriptive part of its functionality is about all its limitations
There was a problem hiding this comment.
Fair. Not much to discuss here. Will think on it.
| --- | ||
| title: OpenTelemetry Collector | ||
| sidebar_order: 20 | ||
| title: OpenTelemetry Collector Setup |
There was a problem hiding this comment.
I'd consider restructuring this page to the two column layout, since it has many steps and a lot of snippets
| | [Vector](/concepts/otlp/forwarding/pipelines/vector/) | Lightweight log routing with VRL transformations | ✅ | ❌ | | ||
| | [Fluent Bit](/concepts/otlp/forwarding/pipelines/fluentbit/) | Lightweight forwarding with minimal resource usage | ✅ | ✅ | | ||
|
|
||
| **Not sure which to use?** Start with the [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/) - it has the broadest source support and all [source guides](/concepts/otlp/forwarding/sources/) use it. No newline at end of file |
There was a problem hiding this comment.
Do I need to use a source to use a pipeline? Are we source agnostic?
There was a problem hiding this comment.
Agnostic. You don't need a source to use a pipeline. The sources are just guides for common infra setups that could be used. I'll update the wording here so this is more clear.
|
|
||
| | Pipeline | Best For | Logs | Traces | | ||
| |----------|----------|:----:|:------:| | ||
| | [OpenTelemetry Collector](/concepts/otlp/forwarding/pipelines/collector/) | Full telemetry pipeline with receivers, processors, and exporters | ✅ | ✅ | |
There was a problem hiding this comment.
The two green checks seems slightly disingenuous, since only Kafka as the source allows for traces. Perhaps we should have an asterisk noting that?
There was a problem hiding this comment.
Fair. I'll revise this page for clarity.
There was a problem hiding this comment.
Lots of snippet-heavy guides in /concepts/otlp/forwarding/that could use a look-over to see if a two-column layout would benefit them. I think it would be worth a pass to check some of those out. The sources especially seem ripe for that.
Left a few suggestions, and a link upgrade in a couple of places. I think it could use an update in those places, and then should be ready to go.
Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
jaffrepaul
force-pushed
the
docs/consolidate-otlp-content
branch
from
2a950a6 to
dc2084b
Compare
jaffrepaul
force-pushed
the
docs/consolidate-otlp-content
branch
from
dc2084b to
a14f2a1
Compare
3 participants
DESCRIBE YOUR PR
Reorganize OTLP documentation for clearer information architecture and improved navigation:
OTLP Documentation Structure:
direct/section for SDK-to-Sentry export (traces, logs)forwarding/section withpipelines/(Collector, Vector, Fluent Bit) andsources/(AWS CloudWatch, Kafka, Nginx, Syslog, Windows Events)Platform Drains:
Migration:
product/drainstoconcepts/otlpIS YOUR CHANGE URGENT?
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes: