Module std.metrics

Developer-defined application metrics.

Declare your own counters, gauges, and histograms; their live values flow into the same scrape surface as the runtime built-ins, readable through std.observe.

Examples

import std.metrics;
import std.observe;

fn main() {
    let requests = match metrics.counter("app.requests") {
        .Ok(counter) => counter,
        .Err(error) => panic(to_string(error)),
    };
    requests.inc();
    requests.add(4);

    let active = match metrics.gauge("app.active_connections") {
        .Ok(gauge) => gauge,
        .Err(error) => panic(to_string(error)),
    };
    active.set(3);
    active.dec();

    print(observe.scrape());
}

Handles

Counter, Gauge, and Histogram are Copy handles — each wraps the i64 slot index the runtime registry hands back. They own no heap memory, so there is no free() or close(): copying a handle is just copying the index, and the registry value lives for the session.

A name is registered once. Calling metrics.counter("x") a second time with the same name returns a handle to the same slot, so the same metric can be reached from anywhere in a program without threading the handle through.

Names

Metric names follow the Prometheus charset [a-zA-Z_:][a-zA-Z0-9_:.]*. The scrape renders a name to its Prometheus series by mapping . to _. A name that is malformed, that exceeds the registry's caps, or whose rendered series name collides with a runtime built-in or an already-registered user metric (heap_live_bytes vs the built-in heap.live_bytes; foo.bar vs foo_bar) is rejected, so a user metric cannot shadow or alias another's scrape output. The constructors return a MetricsError when registration is rejected.