Expand description
§monocle-agent
Plug-and-play OpenTelemetry export to Monocle over OTLP/HTTP for Rust services — traces, metrics and logs in one call.
Works in any program — a web server, a worker, a CLI, a batch job. The default install pulls no web framework; you never have to write async code.
§Getting started (any application)
use std::sync::LazyLock;
use monocle_agent::opentelemetry::metrics::Counter;
// Build custom instruments once and reuse them.
static JOBS: LazyLock<Counter<u64>> =
LazyLock::new(|| monocle_agent::counter("jobs.processed", "Jobs processed"));
fn main() {
// Telemetry first. Pass your crate's name/version so `env!` resolves in
// *your* crate, not this library. Off unless MONOCLE_API_KEY is set.
let telemetry = monocle_agent::init(monocle_agent::MonocleConfig::from_env(
env!("CARGO_PKG_NAME"),
env!("CARGO_PKG_VERSION"),
));
// Spans nest into a trace; metrics record against the global meter.
monocle_agent::tracing::info_span!("process_batch").in_scope(|| {
// ... do work ...
JOBS.add(1, &[]);
});
telemetry.shutdown(); // flush buffered telemetry before exit
}Export is off by default: nothing is sent until MONOCLE_API_KEY is set
(or MonocleConfig::with_api_key is called); when disabled the crate still
installs a stdout fmt subscriber and makes no network calls. Instrument with
the re-exported [tracing] (spans/events) and counter/histogram/
gauge (or [opentelemetry] directly) — no separately-versioned dependency.
§Web services (feature axum)
Enable features = ["axum"] for HTTP helpers:
use axum::{routing::get, Router};
use tower_http::trace::TraceLayer;
let telemetry = monocle_agent::init(monocle_agent::MonocleConfig::from_env(
env!("CARGO_PKG_NAME"),
env!("CARGO_PKG_VERSION"),
));
let app = Router::new()
.route("/hello", get(|| async { "hello" }))
// Names request spans "GET /hello" instead of "request".
.layer(TraceLayer::new_for_http().make_span_with(monocle_agent::request_span))
// Records http.server.request.duration for every request.
.layer(axum::middleware::from_fn(monocle_agent::track_http_metrics));
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, app).await.unwrap();
telemetry.shutdown();request_span is a plain function passed to tower-http’s make_span_with,
so this crate depends on no tower-http version — it works with whatever
tower-http (0.5, 0.6, 0.7, …) your service already uses.
§Features
| Feature | Adds | Pulls |
|---|---|---|
| (default) | init, MonocleConfig, TelemetryGuard, counter/histogram/gauge, spawn_blocking_in_span, re-exports | — |
axum | request_span, track_http_metrics | axum |
§Configuration
See MonocleConfig::from_env for the environment variables. The transport
is OTLP/HTTP protobuf; the per-signal paths (/v1/traces, /v1/metrics,
/v1/logs) are appended to the base endpoint internally.
§Runtime requirements
The OTLP exporter uses native-tls (OpenSSL on Linux). Ensure libssl and
ca-certificates are available in your runtime image.
Re-exports§
pub use opentelemetry;pub use tracing;
Structs§
- Monocle
Config - Configuration for the Monocle telemetry exporter.
- Telemetry
Guard - Holds the OTel providers so they can be flushed on shutdown.
Functions§
- counter
- Create a monotonic
u64counter (e.g. requests, jobs, errors). - gauge
- Create an
f64gauge for a last-value measurement (e.g. queue depth, temperature, in-flight requests). - histogram
- Create an
f64histogram (e.g. durations, sizes).unitfollows UCUM ("s"for seconds,"By"for bytes,""for dimensionless). - init
- Initialise tracing and (when enabled) OpenTelemetry export to Monocle.
- record_
http - Record one HTTP request against
http.server.request.duration. - request_
span - Build the per-request span, named
"<METHOD> <route>"(e.g.GET /render) instead of tower-http’s static"request", so traces read clearly in Monocle. - spawn_
blocking_ in_ span - Spawn a blocking task that inherits the caller’s current tracing span.
- track_
http_ metrics - Axum middleware recording
http.server.request.durationfor every request.