rustlavel_otel/lib.rs
1//! rustlavel-otel: OpenTelemetry traces and metrics, over OTLP.
2//!
3//! ```ignore
4//! App::new()?
5//! .routes(routes::web::routes)
6//! .plugin(OpenTelemetry::default())
7//! .serve()
8//! .await
9//! ```
10//!
11//! Nothing is instrumented twice. Every package in the framework already
12//! reports what it does on `rustlavel_core::events`; this listens, the way
13//! Telescope and the Prometheus exporter do, and turns what it hears into OTLP.
14//! Adding a span to a new package therefore means dispatching an event, not
15//! reaching for this crate.
16//!
17//! # What it produces
18//!
19//! * A **server span** per request, named for the route pattern, carrying the
20//! method, path, status and route. Everything the request awaits — a query, a
21//! model call, an MCP tool, an outbound request — becomes a **child span**.
22//! * **Logs**, when asked for, with the trace and span they were written inside
23//! ([`logs`]).
24//! * **Metrics** for the same work: request, query, model and job durations as
25//! histograms, token usage and job outcomes as counters, and the exporter's
26//! own queue depth and drop count so a broken telemetry pipeline is visible
27//! from inside the telemetry.
28//!
29//! # Propagation
30//!
31//! W3C `traceparent` is read from the request and written to the response, so a
32//! trace that began upstream continues here instead of starting again. For an
33//! outbound call, attach [`trace::traceparent`] to carry it onwards.
34//!
35//! # Encoding
36//!
37//! Protobuf by default, because every collector must accept
38//! `application/x-protobuf` while JSON is optional. The encoder is written here
39//! rather than generated ([`protobuf`]), which rule one asks for and which the
40//! narrow, fixed schema makes reasonable. `application/json` is a
41//! configuration switch away when a payload needs to be readable in a proxy log.
42//!
43//! # Failure
44//!
45//! Telemetry must not be able to take down what it observes. Recording a span
46//! is a mutex and a push; the queue is bounded and drops with a counter and a
47//! log line; an unreachable collector costs spans and never a request. See
48//! [`exporter`] for the drop and retry policy in full.
49
50pub mod exporter;
51pub mod logs;
52pub mod metrics;
53pub mod plugin;
54pub mod protobuf;
55pub mod resource;
56pub mod trace;
57
58pub use exporter::{Exporter, Protocol, Settings};
59pub use logs::{LogRecord, LogSettings};
60pub use metrics::{Instrument, Meter};
61pub use plugin::OpenTelemetry;
62pub use protobuf::Encoder;
63pub use resource::{Resource, Value};
64pub use trace::{Span, SpanContext, SpanId, SpanKind, SpanStatus, TraceId, in_span, traceparent};