HewStandard Library

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 = metrics.counter("app.requests");
    requests.inc();
    requests.add(4);

    let active = metrics.gauge("app.active_connections");
    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 fail-fast constructors (counter/gauge/histogram) panic on rejection; the try_* variants return a [MetricsError] so the caller can recover.

Contents

Functions

Function counter

pub fn counter(name: string) -> Counter

Register (or get) a counter named name.

Panics if the name is rejected by the registry. Use [try_counter] for a recoverable result.

Examples

let hits = metrics.counter("app.cache_hits");
hits.inc();

Function try_counter

pub fn try_counter(name: string) -> Result<Counter, MetricsError>

Register (or get) a counter named name, returning a structured error if the registry rejects the name.

Function gauge

pub fn gauge(name: string) -> Gauge

Register (or get) a gauge named name.

Panics if the name is rejected by the registry. Use [try_gauge] for a recoverable result.

Function try_gauge

pub fn try_gauge(name: string) -> Result<Gauge, MetricsError>

Register (or get) a gauge named name, returning a structured error if the registry rejects the name.

Function histogram

pub fn histogram(name: string) -> Histogram

Register (or get) a histogram named name.

Panics if the name is rejected by the registry. Use [try_histogram] for a recoverable result.

The histogram records observations; the scrape exposes the running count and sum as name_count / name_sum. Custom bucket upper bounds (the name_bucket lines) arrive in a later release.

Function try_histogram

pub fn try_histogram(name: string) -> Result<Histogram, MetricsError>

Register (or get) a histogram named name, returning a structured error if the registry rejects the name.

Types

Enum MetricsError

Why a metric registration was rejected.

Variants

Rejected(string)

The name was malformed, exceeded a registry cap, or collided with a runtime built-in metric. The registry counts the rejection in its hew_metrics_*_dropped_total self-metrics, visible in the scrape.

Struct Counter

A monotonic counter handle.

Created by metrics.counter(name). Copy: the handle is the registry slot index, not an owning pointer.

Fields

id: i64

Struct Gauge

A bidirectional gauge handle.

Created by metrics.gauge(name). Copy: the handle is the registry slot index, not an owning pointer.

Fields

id: i64

Struct Histogram

A histogram handle.

Created by metrics.histogram(name). Copy: the handle is the registry slot index, not an owning pointer.

This handle records observations; the scrape exposes the running observation count and sum as valid name_count / name_sum lines. Bucketed histograms (custom le upper bounds, the name_bucket lines) are not yet expressible from the stdlib surface and arrive in a later release.

Fields

id: i64

Traits

Trait CounterMethods

Methods on a Counter.

Methods

fn inc(self: Self)

Increment the counter by one.

fn add(self: Self, n: i64)

Add n to the counter. A negative n is rejected by the runtime and counted in the registry self-metrics (counters are monotonic).

Trait GaugeMethods

Methods on a Gauge.

Methods

fn inc(self: Self)

Increment the gauge by one.

fn dec(self: Self)

Decrement the gauge by one.

fn set(self: Self, n: i64)

Set the gauge to n.

fn add(self: Self, n: i64)

Add n (any sign) to the gauge.

Trait HistogramMethods

Methods on a Histogram.

Methods

fn observe(self: Self, v: f64)

Record one observation of value v; fractional values are preserved in the rendered histogram _sum sample.