io.pedestal.metrics

Metrics functionality, built on the metrics SPI (service provider interface).

*default-metric-source*

dynamic

The default metric source, used when a specific metric source is not specified.

This may itself be nil, in which case default no-op behavior will occur.

advance-counter

(advance-counter metric-name attributes amount)(advance-counter metric-source metric-name attributes amount)

Increments a counter metric by a numeric amount (which should be positive).

Returns nil.

counter

(counter metric-name attributes)(counter metric-source metric-name attributes)

Finds or creates a counter metric with the given metric name.

Returns a function used to increment the counter. Invoked with no arguments, increments the counter by 1, or with a single numeric argument, increments the counter by that amount.

gauge

(gauge metric-name attributes value-fn)(gauge metric-source metric-name attributes value-fn)

Creates a gauge that obtains its metric values from value-fn, which must return a number. Does nothing if a gauge with that name already exists.

Returns nil.

histogram

(histogram metric-name attributes)(histogram metric-source metric-name attributes)

Creates a histogram (sometimes called a distribution summary), which tracks the number of events and a dimension for each event; internally, distributes different events to various bucket ranges, yielding a histogram of sizes of the event; a comment example is to use a histogram to track the size of incoming requests or outgoing responses.

Returns a function that records the dimension of an event.

increment-counter

(increment-counter metric-name attributes)(increment-counter metric-source metric-name attributes)

Increments a counter metric by 1.

Returns nil.

timed

macro

(timed metric-name attributes & body)

Obtains and starts a timer, then executes the body adding a (try … finally) block to stop the timer, using the *default-metric-source*.

timed*

macro

(timed* metric-source metric-name attributes & body)

Variant of timed when using a specific metric source.

timer

(timer metric-name attributes)(timer metric-source metric-name attributes)

Creates a timer and return the timer’s trigger function. Invoking the trigger starts tracking execution duration, and returns another function that stops the timer and records the elapsed duration.

The stop timer function is idempotent; only the first call records a duration.

Internally, timers measure elapsed nanosecond time.