monocle_agent/lib.rs
1//! # monocle-agent
2//!
3//! Plug-and-play [OpenTelemetry] export to [Monocle] over OTLP/HTTP for Rust
4//! services — **traces, metrics and logs** in one call.
5//!
6//! Works in **any** program — a web server, a worker, a CLI, a batch job. The
7//! default install pulls no web framework; you never have to write async code.
8//!
9//! ## Getting started (any application)
10//!
11//! ```no_run
12//! use std::sync::LazyLock;
13//! use monocle_agent::opentelemetry::metrics::Counter;
14//!
15//! // Build custom instruments once and reuse them.
16//! static JOBS: LazyLock<Counter<u64>> =
17//! LazyLock::new(|| monocle_agent::counter("jobs.processed", "Jobs processed"));
18//!
19//! fn main() {
20//! // Telemetry first. Pass your crate's name/version so `env!` resolves in
21//! // *your* crate, not this library. Off unless MONOCLE_API_KEY is set.
22//! let telemetry = monocle_agent::init(monocle_agent::MonocleConfig::from_env(
23//! env!("CARGO_PKG_NAME"),
24//! env!("CARGO_PKG_VERSION"),
25//! ));
26//!
27//! // Spans nest into a trace; metrics record against the global meter.
28//! monocle_agent::tracing::info_span!("process_batch").in_scope(|| {
29//! // ... do work ...
30//! JOBS.add(1, &[]);
31//! });
32//!
33//! telemetry.shutdown(); // flush buffered telemetry before exit
34//! }
35//! ```
36//!
37//! Export is **off by default**: nothing is sent until `MONOCLE_API_KEY` is set
38//! (or [`MonocleConfig::with_api_key`] is called); when disabled the crate still
39//! installs a stdout `fmt` subscriber and makes no network calls. Instrument with
40//! the re-exported [`tracing`] (spans/events) and [`counter`]/[`histogram`]/
41//! [`gauge`] (or [`opentelemetry`] directly) — no separately-versioned dependency.
42//!
43//! ## Web services (feature `axum`)
44//!
45//! Enable `features = ["axum"]` for HTTP helpers:
46//!
47//! ```no_run
48//! # #[cfg(feature = "axum")] {
49//! use axum::{routing::get, Router};
50//! use tower_http::trace::TraceLayer;
51//!
52//! # async fn build() {
53//! let telemetry = monocle_agent::init(monocle_agent::MonocleConfig::from_env(
54//! env!("CARGO_PKG_NAME"),
55//! env!("CARGO_PKG_VERSION"),
56//! ));
57//!
58//! let app = Router::new()
59//! .route("/hello", get(|| async { "hello" }))
60//! // Names request spans "GET /hello" instead of "request".
61//! .layer(TraceLayer::new_for_http().make_span_with(monocle_agent::request_span))
62//! // Records http.server.request.duration for every request.
63//! .layer(axum::middleware::from_fn(monocle_agent::track_http_metrics));
64//!
65//! let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
66//! axum::serve(listener, app).await.unwrap();
67//! telemetry.shutdown();
68//! # }
69//! # }
70//! ```
71//!
72//! [`request_span`] is a plain function passed to tower-http's `make_span_with`,
73//! so this crate depends on no tower-http version — it works with whatever
74//! tower-http (0.5, 0.6, 0.7, …) your service already uses.
75//!
76//! ## Features
77//!
78//! | Feature | Adds | Pulls |
79//! |---------|------|-------|
80//! | _(default)_ | `init`, [`MonocleConfig`], [`TelemetryGuard`], [`counter`]/[`histogram`]/[`gauge`], [`spawn_blocking_in_span`], re-exports | — |
81//! | `axum` | [`request_span`], [`track_http_metrics`] | `axum` |
82//!
83//! ## Configuration
84//!
85//! See [`MonocleConfig::from_env`] for the environment variables. The transport
86//! is OTLP/HTTP protobuf; the per-signal paths (`/v1/traces`, `/v1/metrics`,
87//! `/v1/logs`) are appended to the base endpoint internally.
88//!
89//! ## Runtime requirements
90//!
91//! The OTLP exporter uses native-tls (OpenSSL on Linux). Ensure `libssl` and
92//! `ca-certificates` are available in your runtime image.
93//!
94//! [OpenTelemetry]: https://opentelemetry.io/
95//! [Monocle]: https://monocle.sh/
96
97#![warn(missing_docs)]
98
99mod blocking;
100mod config;
101mod metrics;
102mod providers;
103
104#[cfg(feature = "axum")]
105mod http;
106
107pub use blocking::spawn_blocking_in_span;
108pub use config::MonocleConfig;
109pub use metrics::{counter, gauge, histogram};
110
111#[cfg(feature = "axum")]
112pub use http::{record_http, request_span, track_http_metrics};
113
114/// Re-export of the exact `opentelemetry` version this crate builds against.
115///
116/// Use it to record custom metrics or build `KeyValue` attributes without adding
117/// a separately-versioned `opentelemetry` dependency of your own (which would
118/// have to be kept in lockstep with this crate).
119pub use opentelemetry;
120
121/// Re-export of `tracing` — create spans/events with `tracing::info_span!` /
122/// `#[tracing::instrument]` and they flow to the exporter installed by [`init`].
123pub use tracing;
124
125use opentelemetry::trace::TracerProvider as _;
126use opentelemetry_appender_tracing::layer::OpenTelemetryTracingBridge;
127use opentelemetry_otlp::{Protocol, WithExportConfig, WithHttpConfig};
128use opentelemetry_sdk::logs::SdkLoggerProvider;
129use opentelemetry_sdk::metrics::SdkMeterProvider;
130use opentelemetry_sdk::trace::SdkTracerProvider;
131use tracing_subscriber::filter::filter_fn;
132use tracing_subscriber::prelude::*;
133use tracing_subscriber::EnvFilter;
134
135use providers::{
136 build_headers, build_resource, build_tls_http_client, is_self_referential, EXPORT_TIMEOUT,
137};
138
139/// Holds the OTel providers so they can be flushed on shutdown.
140///
141/// Keep it alive for the whole process lifetime and call
142/// [`TelemetryGuard::shutdown`] before exit. When telemetry is disabled all
143/// fields are `None` and `shutdown` is a no-op.
144#[must_use = "hold the guard for the process lifetime and call shutdown() before exit to flush telemetry"]
145pub struct TelemetryGuard {
146 tracer_provider: Option<SdkTracerProvider>,
147 meter_provider: Option<SdkMeterProvider>,
148 logger_provider: Option<SdkLoggerProvider>,
149}
150
151impl TelemetryGuard {
152 /// Flush and shut down all providers, ensuring buffered spans/metrics/logs
153 /// are exported before the process exits. Safe to call when disabled.
154 pub fn shutdown(&self) {
155 if let Some(p) = &self.tracer_provider {
156 if let Err(e) = p.shutdown() {
157 tracing::warn!("otel tracer shutdown: {e}");
158 }
159 }
160 if let Some(p) = &self.meter_provider {
161 if let Err(e) = p.shutdown() {
162 tracing::warn!("otel meter shutdown: {e}");
163 }
164 }
165 if let Some(p) = &self.logger_provider {
166 if let Err(e) = p.shutdown() {
167 tracing::warn!("otel logger shutdown: {e}");
168 }
169 }
170 }
171}
172
173/// Initialise tracing and (when enabled) OpenTelemetry export to Monocle.
174///
175/// Installs the global `tracing` subscriber. Always installs a stdout `fmt`
176/// layer; when `cfg.api_key` is present it additionally exports traces, metrics
177/// and logs over OTLP/HTTP. Returns a [`TelemetryGuard`] that must be kept alive
178/// for the process lifetime and flushed via [`TelemetryGuard::shutdown`].
179///
180/// # Panics
181///
182/// Panics if the global subscriber is already set, or if an OTLP exporter fails
183/// to build (misconfigured endpoint/TLS). Call this once, early in `main`.
184pub fn init(cfg: MonocleConfig) -> TelemetryGuard {
185 let env_filter =
186 EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(&cfg.log_filter));
187 let fmt_layer = tracing_subscriber::fmt::layer();
188
189 let Some(api_key) = cfg.api_key.clone() else {
190 // Telemetry disabled: stdout-only, no network traffic.
191 tracing_subscriber::registry()
192 .with(env_filter)
193 .with(fmt_layer)
194 .init();
195 tracing::info!("monocle-agent disabled (no MONOCLE_API_KEY) — telemetry export off");
196 return TelemetryGuard {
197 tracer_provider: None,
198 meter_provider: None,
199 logger_provider: None,
200 };
201 };
202
203 let resource = build_resource(&cfg);
204 let headers = build_headers(&cfg, api_key);
205 let base = cfg.endpoint.trim_end_matches('/');
206 // Shared blocking client with an explicit TLS backend — reused by all three
207 // exporters (reqwest::blocking::Client is cheap to clone and Send+Sync).
208 let http_client = build_tls_http_client();
209
210 // ── Traces ──────────────────────────────────────────────────────────────
211 let span_exporter = opentelemetry_otlp::SpanExporter::builder()
212 .with_http()
213 .with_http_client(http_client.clone())
214 .with_protocol(Protocol::HttpBinary)
215 .with_endpoint(format!("{base}/v1/traces"))
216 .with_headers(headers.clone())
217 .with_timeout(EXPORT_TIMEOUT)
218 .build()
219 .expect("build OTLP span exporter");
220 let tracer_provider = SdkTracerProvider::builder()
221 .with_batch_exporter(span_exporter)
222 .with_resource(resource.clone())
223 .build();
224
225 // ── Metrics ─────────────────────────────────────────────────────────────
226 let metric_exporter = opentelemetry_otlp::MetricExporter::builder()
227 .with_http()
228 .with_http_client(http_client.clone())
229 .with_protocol(Protocol::HttpBinary)
230 .with_endpoint(format!("{base}/v1/metrics"))
231 .with_headers(headers.clone())
232 .with_timeout(EXPORT_TIMEOUT)
233 .build()
234 .expect("build OTLP metric exporter");
235 let meter_provider = SdkMeterProvider::builder()
236 .with_periodic_exporter(metric_exporter)
237 .with_resource(resource.clone())
238 .build();
239
240 // ── Logs ────────────────────────────────────────────────────────────────
241 let log_exporter = opentelemetry_otlp::LogExporter::builder()
242 .with_http()
243 .with_http_client(http_client)
244 .with_protocol(Protocol::HttpBinary)
245 .with_endpoint(format!("{base}/v1/logs"))
246 .with_headers(headers.clone())
247 .with_timeout(EXPORT_TIMEOUT)
248 .build()
249 .expect("build OTLP log exporter");
250 let logger_provider = SdkLoggerProvider::builder()
251 .with_batch_exporter(log_exporter)
252 .with_resource(resource)
253 .build();
254
255 // Register globals so `global::tracer` / `global::meter` resolve to these.
256 opentelemetry::global::set_tracer_provider(tracer_provider.clone());
257 opentelemetry::global::set_meter_provider(meter_provider.clone());
258
259 let tracer = tracer_provider.tracer(cfg.service_name.clone());
260 let otel_trace_layer = tracing_opentelemetry::layer()
261 .with_tracer(tracer)
262 .with_filter(filter_fn(|m| !is_self_referential(m.target())));
263 let otel_logs_layer = OpenTelemetryTracingBridge::new(&logger_provider)
264 .with_filter(filter_fn(|m| !is_self_referential(m.target())));
265
266 tracing_subscriber::registry()
267 .with(env_filter)
268 .with(fmt_layer)
269 .with(otel_trace_layer)
270 .with(otel_logs_layer)
271 .init();
272
273 tracing::info!(
274 endpoint = %base,
275 environment = %cfg.environment,
276 service.name = %cfg.service_name,
277 service.version = %cfg.service_version,
278 "monocle-agent enabled → exporting traces/metrics/logs to Monocle"
279 );
280
281 TelemetryGuard {
282 tracer_provider: Some(tracer_provider),
283 meter_provider: Some(meter_provider),
284 logger_provider: Some(logger_provider),
285 }
286}