Skip to main content

Crate monocle_agent

Crate monocle_agent 

Source
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

FeatureAddsPulls
(default)init, MonocleConfig, TelemetryGuard, counter/histogram/gauge, spawn_blocking_in_span, re-exports—
axumrequest_span, track_http_metricsaxum

§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§

MonocleConfig
Configuration for the Monocle telemetry exporter.
TelemetryGuard
Holds the OTel providers so they can be flushed on shutdown.

Functions§

counter
Create a monotonic u64 counter (e.g. requests, jobs, errors).
gauge
Create an f64 gauge for a last-value measurement (e.g. queue depth, temperature, in-flight requests).
histogram
Create an f64 histogram (e.g. durations, sizes). unit follows 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.duration for every request.