io.pedestal.metrics.spi
added in 0.7.0
Service Provider Interface for metrics providers; protocols that providers should expose and implement.
A no-op implemention of MetricSource is extended onto nil, which may be suitable for testing.
metric-value-type
added in 0.8.0
The type of values that can be used with metrics; this defaults to :long, but can be overridden to :double.
Configured with property io.pedestal.telemetry.metric-value-type or environment variable ’PEDESTAL_METRICS_VALUE_TYPE`.
MetricSource
protocol
Provides methods to find or create counters, timers, and gauges.
Metrics are created using a metric-name (which can be a string, keyword, or symbol) and attributes (which may be nil). attributes are used to configure and qualify the metric (for example, a request counter may have attributes to identify the URL of the request).
Attributes keys are converted to string; for keywords, the leading : is stripped off.
Metric names are required, but attributes may be nil.
Some implementations may use specific attributes (typically, with namespace qualified keyword keys) to configure the metric in some additional way. Such configuration attributes are stripped out of the attributes that are reported to the underlying metric consumer.
The protocol is extended on nil with a no-op implementation of the methods.
members
counter
(counter source metric-name attributes)Finds or creates a counter metric with the given metric name.
Values are either longs or doubles, as per attribute io.pedestal.metrics/value-type (defaults to metric-value-type).
Counters should only ever increase.
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 source metric-name attributes value-fn)Creates, if necessary, a gauge with the given metric name.
The value-fn will be periodically invoked and should return a long or double value, as per attribute io.pedestal.metrics/value-type (defaults to metric-value-type).
If called when the gauge already exists, returns without doing anything.
Returns nil.
histogram
(histogram source metric-name attributes)Finds or creates a distribution summary, returning a function.
Values are either longs or doubles, as per attribute io.pedestal.metrics/value-type (defaults to metric-value-type).
The function is passed a value, to record that value as a new event that will be included in the distribution summary.
timer
(timer source metric-name attributes)Finds or creates a timer, returning the timer’s trigger function.
The timer value will be a long number of milliseconds, or a double value of milliseconds, as per attribute io.pedestal.metrics/value-type (defaults to metric-value-type).
When invoked, the trigger function starts a timer and returns a new function that stops the timer and adds the elapsed time to the underlying counter.