Xo is experimental. The source is now public on GitHub, or try Xo in your browser.
Menu · metrics

Docs

Tour

Book

Reference

std/metrics

On this page

Index

Types

Series

struct Series {
  values: List[Str]
  cells: List[Atomic[Int]]
  q: List[Mutex[QState]]
}

One series of an instrument: its label values and its cells (atomic integers in one list, so reading a series out of the registry shares one object, not one per field): cell 0 a counter’s or gauge’s float (its bits), 1 the observation count, 2 the sum (bits), 3 and on a histogram’s bucket counts, one bucket each. Internal: use the instruments.

Source: std/metrics.xo:14

QSample

struct QSample {
  v: Float
  w: Float
  d: Float
}

A CKMS targeted quantile stream (beorn7/perks, which Prometheus' client uses): samples (value, width, delta), the unsorted buffer, and the count. Internal.

Source: std/metrics.xo:24

QStream

struct QStream {
  l: List[QSample]
  b: List[Float]
  n: Float
}

Source: std/metrics.xo:29

QState

struct QState {
  streams: List[QStream]
  head: Int
  exp_ms: Int
  hot: List[Atomic[Int]]
  hot_n: Atomic[Int]
}

A summary series’ age buckets (client_golang’s streams): every observation goes into each; the head one answers; at a scrape with a time, the head is reset and the next becomes head once its time ran out. Internal.

Source: std/metrics.xo:38

Sample

struct Sample {
  values: List[Str]
  value: Float
}

A value read at scrape time from a collector: its label values and value (decision 0411).

Source: std/metrics.xo:51

Kind

enum Kind { Counter, Gauge }

The kind of a collector’s series.

Source: std/metrics.xo:57

Family

struct Family {
  name: Str
  help: Str
  kind: Int
  labels: List[Str]
  bounds: List[Float]
  series: Mutex[Map[Str, Series]]
  dropped: Atomic[Int]
  reads: List[fn() -> List[Sample]]
  objectives: List[(Float, Float)]
  max_age_ms: Int
  age_buckets: Int
}

One instrument: kind 0 counter, 1 gauge, 2 histogram, 3 summary; reads: a scrape time reader (gauge_func, counter_func, collector); objectives, max_age_ms and age_buckets: a summary’s. Internal.

Source: std/metrics.xo:62

Registry

struct Registry {
  families: Mutex[List[Family]]
  dropped: Atomic[Int]
}

A set of instruments. Cloning shares it. Its fields are internal.

Source: std/metrics.xo:77

Registry.counter

fn (r: Registry) counter(name: Str, help: Str, labels: List[Str] = []) -> Counter

Makes a counter named name (a Prometheus name: letters, digits, _ and :, not starting with a digit) with the label names labels. A second instrument with the same name, an invalid name or label, or buckets that do not increase is a fault: they are programmer errors, found at start.

Source: std/metrics.xo:133

Registry.gauge

fn (r: Registry) gauge(name: Str, help: Str, labels: List[Str] = []) -> Gauge

Source: std/metrics.xo:134

Registry.histogram

fn (r: Registry) histogram(name: Str, help: Str, labels: List[Str] = [], buckets: List[Float] = latency_buckets()) -> Histogram

Source: std/metrics.xo:135

Registry.summary

fn (r: Registry) summary(name: Str, help: Str, labels: List[Str] = [], objectives: List[(Float, Float)] = [], max_age: Duration = 10m, age_buckets: Int = 5) -> Summary

A summary (Prometheus client_golang’s Summary, decision 0411): each objective (quantile, allowed error) is reported as a quantile series (CKMS targeted quantiles, beorn7/perks), with _sum and _count. The quantiles cover the last max_age in age_buckets steps, aged when a scrape passes the time (text(now), handler_at(clock)): a summary never scraped with a time keeps every observation.

Source: std/metrics.xo:170

Registry.gauge_func

fn (r: Registry) gauge_func(name: Str, help: Str, f: fn() -> Float)

A gauge (counter) whose value f returns at each scrape (GaugeFunc, CounterFunc).

Source: std/metrics.xo:175

Registry.counter_func

fn (r: Registry) counter_func(name: Str, help: Str, f: fn() -> Float)

Source: std/metrics.xo:176

Registry.collector

fn (r: Registry) collector(name: Str, help: Str, kind: Kind, labels: List[Str], f: fn() -> List[Sample])

An instrument whose series f returns at each scrape (a Collector): one Sample per series, its values one per label.

Source: std/metrics.xo:179

Registry.text

fn (r: Registry) text(now: Time? = None) -> Str

The text exposition: # HELP and # TYPE lines and the series, instruments in the order they were made, series sorted by label values, histograms as cumulative _bucket{le=...}, _sum and _count, and xo_metrics_dropped_total.

Source: std/metrics.xo:197

Registry.handler

fn (r: Registry) handler() -> fn(http.Request) -> http.Response

A handler answering text() as text/plain; version=0.0.4: router.handle("GET /metrics", reg.handler()).

Source: std/metrics.xo:200

Registry.handler_at

fn (r: Registry) handler_at(clock: Clock) -> fn(http.Request) -> http.Response uses clock

handler, each scrape passing the clock’s time to text (summaries age).

Source: std/metrics.xo:202

Registry.middleware

fn (r: Registry) middleware(clock: Clock, label: fn(http.Request) -> Str) -> fn(http.Request, http.Next) -> http.Response uses clock

A middleware (router.wrap(reg.middleware(clock, label))) that counts every request in http_requests_total{method,route,status}, times it in http_request_seconds{route} (the default buckets) and tracks http_in_flight. label names the route of a request for the route label: pass a function that returns a bounded set (the matched pattern, or the path with ids cut), never the raw path of an API with ids.

Source: std/metrics.xo:210

Counter

struct Counter {
  f: Family
}

A value that only goes up.

Source: std/metrics.xo:87

Counter.inc

fn (c: Counter) inc(values: List[Str] = [])

Adds 1 to (or n >= 0 to) the series of the label values (one per label name, in order; a wrong count is a fault). Safe from any task. A registry holds at most max_series (10,000) series per instrument: a new series past it is dropped and counted in xo_metrics_dropped_total.

Source: std/metrics.xo:142

Counter.add

fn (c: Counter) add(n: Float, values: List[Str] = [])

Source: std/metrics.xo:143

Counter.child

fn (c: Counter) child(values: List[Str] = []) -> CounterChild

The child of the series of the label values (one per label name; a wrong count is a fault): the series is made if it is new. Past max_series the child counts into a series nothing exposes, and the drop is counted in xo_metrics_dropped_total as inc counts it.

Source: std/metrics.xo:152

Counter.remove

fn (c: Counter) remove(values: List[Str]) -> Bool

Removes the series of the label values (DeleteLabelValues): whether there was one.

Source: std/metrics.xo:183

Counter.reset

fn (c: Counter) reset()

Removes every series (Reset).

Source: std/metrics.xo:188

Gauge

struct Gauge {
  f: Family
}

A value that goes up and down.

Source: std/metrics.xo:91

Gauge.set

fn (g: Gauge) set(v: Float, values: List[Str] = [])

Source: std/metrics.xo:144

Gauge.add

fn (g: Gauge) add(v: Float, values: List[Str] = [])

Source: std/metrics.xo:145

Gauge.child

fn (g: Gauge) child(values: List[Str] = []) -> GaugeChild

Source: std/metrics.xo:153

Gauge.remove

fn (g: Gauge) remove(values: List[Str]) -> Bool

Source: std/metrics.xo:184

Gauge.reset

fn (g: Gauge) reset()

Source: std/metrics.xo:189

Histogram

struct Histogram {
  f: Family
}

Observations counted in buckets, with their count and sum.

Source: std/metrics.xo:95

Histogram.observe

fn (h: Histogram) observe(v: Float, values: List[Str] = [])

Source: std/metrics.xo:146

Histogram.child

fn (h: Histogram) child(values: List[Str] = []) -> HistogramChild

Source: std/metrics.xo:154

Histogram.remove

fn (h: Histogram) remove(values: List[Str]) -> Bool

Source: std/metrics.xo:185

Histogram.reset

fn (h: Histogram) reset()

Source: std/metrics.xo:190

Summary

struct Summary {
  f: Family
}

Observations summarized as quantiles (within each objective’s error), with their count and sum.

Source: std/metrics.xo:100

Summary.child

fn (s: Summary) child(values: List[Str] = []) -> SummaryChild

Source: std/metrics.xo:155

Summary.observe

fn (s: Summary) observe(v: Float, values: List[Str] = [])

Source: std/metrics.xo:171

Summary.remove

fn (s: Summary) remove(values: List[Str]) -> Bool

Source: std/metrics.xo:186

Summary.reset

fn (s: Summary) reset()

Source: std/metrics.xo:191

CounterChild

struct CounterChild {
  s: Series
}

A held series (decision 0501, client_golang’s WithLabelValues): made once with child(values) and used in a hot loop with no label list, key or lookup. A child shares the series’ cells; cloning one shares them again; it is safe from any task. remove and reset detach the series from the exposition: a child made before keeps counting into the detached series (take a new one after a remove), as in client_golang.

Source: std/metrics.xo:110

CounterChild.inc

fn (c: CounterChild) inc()

Adds 1 to (or n >= 0 to) the child’s series.

Source: std/metrics.xo:157

CounterChild.add

fn (c: CounterChild) add(n: Float)

Source: std/metrics.xo:158

GaugeChild

struct GaugeChild {
  s: Series
}

Source: std/metrics.xo:113

GaugeChild.set

fn (g: GaugeChild) set(v: Float)

Source: std/metrics.xo:159

GaugeChild.add

fn (g: GaugeChild) add(v: Float)

Source: std/metrics.xo:160

HistogramChild

struct HistogramChild {
  s: Series
  bounds: List[Float]
}

Source: std/metrics.xo:116

HistogramChild.observe

fn (h: HistogramChild) observe(v: Float)

Source: std/metrics.xo:161

SummaryChild

struct SummaryChild {
  s: Series
  objectives: List[(Float, Float)]
}

Source: std/metrics.xo:120

SummaryChild.observe

fn (s: SummaryChild) observe(v: Float)

Source: std/metrics.xo:162

Functions

registry

fn registry() -> Registry

A new empty registry. Xo has no program wide state: main makes one and passes it to what registers or reads instruments.

Source: std/metrics.xo:84

latency_buckets

fn latency_buckets() -> List[Float]

The buckets of request latencies in seconds: 0.005 to 10.

Source: std/metrics.xo:126

↑ index