metrics #

metrics.new_registry() owns named counters, gauges, and histograms. Create instruments with counter(name), gauge(name), or histogram(name, bounds). Counter.add accepts nonnegative increments; gauges support set and signed inc. Invalid names, negative or NaN counter increments, conflicting instrument types or histogram sample names, and invalid histogram bounds panic. Names use ASCII letters, underscores, and noninitial digits; metric names may also contain colons.

Every operation, including registration and to_prometheus, synchronizes access. A scrape locks each instrument while rendering it; values from different instruments are not a global snapshot. Caller-owned label maps must not be modified concurrently with an operation that reads them. Label order is irrelevant, and labels containing commas, equals signs, quotes, backslashes, or newlines remain distinct and are escaped for Prometheus exposition.

Histograms use finite, strictly increasing bounds. Reusing a name requires identical bounds. record maintains cumulative buckets, count, and sum. The exporter appends an implicit +Inf bucket; the le label is reserved and cannot be supplied to record. to_prometheus() renders HELP/TYPE lines and samples in Prometheus text format, including NaN, +Inf, and -Inf gauge values. Construct instruments through the registry so they are exported.

fn new_registry() &Registry

new_registry creates an empty Registry.

struct Counter {
mut:
	mutex &sync.Mutex = sync.new_mutex()
	vals  map[string]f64
}

Counter is a monotonically increasing cumulative counter.

fn (mut c Counter) add(v f64, labels map[string]string)

add increments the labeled series by v. Negative or NaN increments panic; use a gauge for values that decrease.

fn (c &Counter) get(labels map[string]string) f64

get returns the current value of the labeled series (0 if absent).

struct Gauge {
mut:
	mutex &sync.Mutex = sync.new_mutex()
	vals  map[string]f64
}

Gauge is a point-in-time value that goes up and down.

fn (mut g Gauge) set(v f64, labels map[string]string)

set assigns the labeled series.

fn (mut g Gauge) inc(v f64, labels map[string]string)

inc adds v to the labeled series.

fn (g &Gauge) get(labels map[string]string) f64

get returns the current value of the labeled series (0 if absent).

struct Histogram {
mut:
	mutex   &sync.Mutex = sync.new_mutex()
	bounds  []f64
	buckets map[string][]u64
	sums    map[string]f64
	counts  map[string]u64
}

Histogram accumulates observations into fixed buckets plus sum and count, in the Prometheus exposition model.

fn (mut h Histogram) record(v f64, labels map[string]string)

record adds one observation to the labeled series' buckets, sum and count.

fn (h &Histogram) bucket_counts(labels map[string]string) []u64

bucket_counts returns the cumulative per-bucket counts of the labeled series, plus one trailing +Inf entry.

fn (h &Histogram) sum(labels map[string]string) f64

sum returns the sum of observations of the labeled series.

fn (h &Histogram) count(labels map[string]string) u64

count returns the number of observations of the labeled series.

struct Registry {
mut:
	mutex      &sync.Mutex = sync.new_mutex()
	counters   map[string]&Counter
	gauges     map[string]&Gauge
	histograms map[string]&Histogram
}

Registry owns the instruments; create instruments through it so names stay namespaced in one place.

fn (mut r Registry) counter(name string) &Counter

counter returns the named counter, creating it on first use.

fn (mut r Registry) gauge(name string) &Gauge

gauge returns the named gauge, creating it on first use.

fn (mut r Registry) histogram(name string, bounds []f64) &Histogram

histogram returns the named histogram with the given bucket upper bounds (must be finite and strictly ascending), creating it on first use. Reusing a name requires the same bounds. Invalid configuration panics.

fn (mut r Registry) to_prometheus() string

to_prometheus renders all series in Prometheus text exposition format: one HELP/TYPE header pair per instrument plus one line per labeled series.