replikativ.metrics — org.replikativ/metrics 0.1.3

Counters, gauges and histograms for the replikativ stack, with nothing underneath them.

One process-wide registry — metrics are process-level by nature; scoping is by label — of named instruments, each a family of series keyed by its labels:

(inc! :konserve_bytes_written_total {:backend :file} 4096) (gauge! :datahike_connections {:database "…"} 3) (observe! :datahike_commit_seconds {:database "…"} 0.042)

snapshot returns the registry as plain data; replikativ.metrics.prometheus renders it in the exposition format, replikativ.metrics.konserve/sink folds konserve's events into it, and replikativ.metrics.jvm samples the JVM at scrape time. Recording is one swap! on an atom: safe from any thread, cheap, and never throws for a well-formed call.

Names are keywords in Prometheus style (snake_case, unit last: _seconds, _bytes, _total for counters); labels a map of keyword to keyword, string, number or uuid. describe! adds the help text and histogram buckets a scrape shows; an instrument first seen by a recording call gets its type from that call and no help.

default-buckets clj/s

Histogram buckets for durations in seconds: 1 ms to 10 s.

describe! clj/s

(describe! name {:keys [type help buckets]})

Declare name: :type, :help, and for a histogram :buckets (upper bounds, ascending; default-buckets otherwise). Idempotent; a series recorded before the description keeps its data.

gauge! clj/s

(gauge! name labels v)

Set the gauge name for labels to v.

inc! clj/s

(inc! name labels)

(inc! name labels n)

Count n (1) on the counter name for labels.

observe! clj/s

(observe! name labels v)

Record the value v on the histogram name for labels.

observe-since! clj/s

(observe-since! name labels t0)

Record on the histogram name the seconds elapsed since t0 (a timer).

registry clj/s

name -> {:type :counter|:gauge|:histogram :help str :buckets [..] :series {labels state}}

reset! clj/s

(reset!)

Forget every instrument and series — for tests.

snapshot clj/s

(snapshot)

The registry as data: {name {:type :help :buckets :series {labels state}}}, where a counter's or gauge's state is its value and a histogram's is {:count :sum :buckets [per-bucket counts …, +Inf]}.

timer clj/s

(timer)

The start of a duration measurement; pair with observe-since!.