Skip to main content

Crate mensura

Crate mensura 

Source
Expand description

§mensura

Metrics instrumentation with InfluxDB semantics: every measurement is a set of tags (indexed dimensions) and fields (values), recorded through macros that never block the calling code.

use mensura::{count, measure, timer};

// The first argument names the measurement. Tags are bare after it;
// fields are marked with `?`.
measure!("http_latency", host = "web-1", region = "eu", ?ms = 12.5, ?ok = true);

// Values are arbitrary expressions…
let route = "/search";
measure!("http_request", endpoint = format!("GET {route}"), ?bytes = route.len());

// …and a bare name records the variable of that name.
let status = 200u16;
let ms = 8.0;
measure!("http_latency", route, status, ?ms);

// `count!` implies `count = 1`.
count!("http_request", route = "/search", status = 200);

// `timer!` records `time = <elapsed>` when the binding is dropped.
{
    let _timer = timer!("query_duration", operation = "query");
}

Every measurement is named, and the name is a compile-time constant stored as a &'static str — it is the InfluxDB measurement the point lands in.

A measure! also needs at least one field: a point of tags alone records nothing and InfluxDB rejects it, so it is a compile error. count! and timer! supply a field of their own and can be called with tags only.

§Registering a backend

Nothing is recorded until a backend is registered; before that, the macros do not even evaluate their arguments.

use mensura::backends::{Composite, InfluxDb, Stdout};

let backend = Composite::new()
    .with(Stdout::new())
    .with(
        InfluxDb::v2("https://influxdb.example.com")
            .with_auth_token(std::env::var("INFLUXDB_TOKEN").unwrap())
            .with_org("myorganization")
            .with_bucket("metrics"),
    );

mensura::register_global_backend(backend).expect("backend is already registered");

Points travel to the backend over a bounded queue. One dispatcher task reads that queue and groups points into batches; a pool of Config::writers tasks publishes them. Batching comes first by design — ten points arriving together become one request, not ten — and raising the writer count lets those requests overlap when one round trip is not enough to keep up.

Sends are try_sends: if the queue is full, points are dropped, counted in Stats::dropped and reported on stderr, rather than slowing down the code being measured.

If register_global_backend is called from inside a Tokio runtime the tasks are spawned onto it; otherwise mensura starts a dedicated thread with a small current-thread runtime, so synchronous programs work too. Either way, drain what is still queued before exiting: deregister_global_backend_async from async code, or deregister_global_backend from a plain main — nothing in mensura ever blocks a runtime thread unless you call the blocking form yourself.

§Testing

test_backend captures measurements in-process and hands back a queryable store:

use mensura::count;

let metrics = mensura::test_backend();

count!("http_request", route = "/search", status = 200);
count!("http_request", route = "/search", status = 500);

assert_eq!(metrics.query().measurement("http_request").sum("count"), 2.0);
assert_eq!(metrics.query().tag("status", 500).count(), 1);

Re-exports§

pub use backend::Backend;
pub use backend::BackendError;
pub use backend::MultiError;
pub use datapoint::DataPoint;
pub use datapoint::MAX_VALUES;
pub use datapoint::ValueVec;
pub use queue::AlreadyRegistered;
pub use queue::Config;
pub use queue::QueueHandle;
pub use queue::Stats;
pub use queue::deregister_global_backend;
pub use queue::deregister_global_backend_async;
pub use queue::flush;
pub use queue::flush_async;
pub use queue::flush_with_timeout;
pub use queue::is_registered;
pub use queue::queue_handle;
pub use queue::register_global_backend;
pub use queue::register_global_backend_with_config;
pub use queue::stats;
pub use testing::Query;
pub use testing::TestBackend;
pub use testing::test_backend;
pub use value::MeasurementField;
pub use value::MeasurementTag;
pub use value::Value;
pub use value::ValueType;

Modules§

backend
The backend trait every sink implements.
backends
The backends mensura ships with.
datapoint
The unit of data that travels from a macro invocation to a backend.
line_protocol
Serialization of DataPoints into the InfluxDB line protocol.
queue
The global, non-blocking queue that carries points from macro call sites to the registered backend.
testing
Capturing and asserting on measurements from tests.
value
The dynamic value model shared by the macros, the queue and the backends.

Macros§

count
Records a measurement with an implied count = 1 field.
measure
Records a measurement.
timer
Starts a Timer that records time = <elapsed> when it is dropped.

Structs§

Timer
Measures the time between its construction and its drop.

Constants§

TIMER_FIELD
Name of the field a Timer adds when it reports.