docs: Add OTLP arch docs #3063
docs: Add OTLP arch docs #3063
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #3063 +/- ##
=======================================
+ Coverage 80.0% 80.1% +0.1%
=======================================
Files 126 126
Lines 21879 21949 +70
=======================================
+ Hits 17519 17603 +84
+ Misses 4360 4346 -14 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
scottgerring
force-pushed
the
chore/add-otlp-docs
branch
from
a195591 to
ab1458e
Compare
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a dedicated architecture document for the OTLP exporter subsystem and updates the high-level architecture overview to reference it.
- Adds
docs/design/otlp.mddetailing exporter structure, crate layout, runtime flow, configuration, and extension points. - Updates
docs/design/architecture.mdto include a link to the new OTLP design doc.
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/design/otlp.md | New OTLP architecture guide covering exporters and config. |
| docs/design/architecture.md | Added “OTLP” to the detailed design section. |
Comments suppressed due to low confidence (2)
docs/design/architecture.md:29
- To maintain consistent section numbering, consider changing this heading to
## 4 Detailed Design, aligning it with the preceding numbered sections.
## Detailed Design
docs/design/otlp.md:7
- The overview section above is unnumbered; for consistency either number it as
## 1 Overviewor remove numbering from this heading.
## Overview
ab1458e to
5964019
Compare
|
Review comments addressed; as I rewrote the one commit, the comments are a little de-synced from the change; i will add a separate "address changes" commit next time. |
scottgerring
force-pushed
the
chore/add-otlp-docs
branch
from
5964019 to
0a3cbba
Compare
Good idea! Added the date ✅ Can always get more granular with |
docs/design/otlp.md
Outdated
|
|
||
| ### 4.1 Transport-specific Client Options | ||
|
|
||
| Exporters must function both in binaries that start no async runtime and in services already running Tokio. Consequently the crate provides **blocking** and **non-blocking** HTTP clients behind mutually-exclusive feature-flags. The blocking variant is the default to ensure out-of-the-box operability; applications that already depend on Tokio can opt into an async client to avoid spawning extra threads. |
There was a problem hiding this comment.
nit: instead of stating "Tokio", could we say "async runtimes like Tokio".
docs/design/otlp.md
Outdated
| | Reqwest (blocking) **(default)** | `reqwest-blocking-client` | Yes | `reqwest::blocking` | HTTP/1.1 → auto-upgrades to HTTP/2 over TLS | CLI tools, synchronous binaries, or hybrid apps where introducing Tokio is undesirable. A helper thread is spawned once at builder time. | ||
| | Reqwest (async) | `reqwest-client` | No (Tokio) | `reqwest` | HTTP/1.1 → auto-upgrades to HTTP/2 over TLS | Services that already run a Tokio runtime and prefer fully non-blocking exports. | ||
| | Hyper | `hyper-client` | No (Tokio) | `hyper` | HTTP/1.1 → auto-upgrades to HTTP/2 over TLS | Lean dependency footprint when both Reqwest features are disabled. | ||
| | Tonic (gRPC) | `grpc-tonic` | No (Tokio) | `tonic` | HTTP/2 (gRPC) | Environments standardising on gRPC or collectors exposing only port 4317. |
There was a problem hiding this comment.
The "typical use case" header is not adding value IMHO. If a user want to use gRPC, then they use tonic/gRPC.
There was a problem hiding this comment.
Doesn't it? Aside from "I want to use gRPC so I should use the only gRPC option" I don't think choosing between the others is obvious. It might be something that belongs here alternatively/as-well even!
| ## 10. Key Architectural Decisions | ||
| | Decision | Rationale | | ||
| |----------|-----------| | ||
| | *Builder pattern with marker types* | Compile-time guarantee that exactly one transport is chosen. | |
There was a problem hiding this comment.
we do have issues about users accidentally enable multiple feature flags...
scottgerring
force-pushed
the
chore/add-otlp-docs
branch
3 times, most recently
from
b2ef5ac to
41f088d
Compare
scottgerring
force-pushed
the
chore/add-otlp-docs
branch
from
41f088d to
f83b803
Compare
| # OpenTelemetry Rust – Architecture Overview | ||
|
|
||
| > Status:Development | ||
| > Last Updated: 2025-07-16 |
There was a problem hiding this comment.
nit: We have git blame for this!
Fixes #3062 , documenting the architecture of the OTLP subsystem. I've written this as I dive into OTLP as part of reviewing it against the specification and figure it is helpful context for others working on opentelemetry-rust.
Changes
Please provide a brief description of the changes here.
Merge requirement checklist
CHANGELOG.mdfiles updated for non-trivial, user-facing changes