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 = 1field. - measure
- Records a measurement.
- timer
- Starts a
Timerthat recordstime = <elapsed>when it is dropped.
Structs§
- Timer
- Measures the time between its construction and its drop.
Constants§
- TIMER_
FIELD - Name of the field a
Timeradds when it reports.