metrics: Metrics

Description

A metric is a measure which can be aggregated into a time series, and comes in one of three types: counters, gauges, and histograms.

Metrics must have a unique name.

Usage

counter_metric(
  name,
  help,
  labels = character(),
  ...,
  unit = NULL,
  registry = global_registry()
)
gauge_metric(
  name,
  help,
  labels = character(),
  ...,
  unit = NULL,
  registry = global_registry()
)
histogram_metric(
  name,
  help,
  buckets = c(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10),
  labels = character(),
  ...,
  unit = NULL,
  registry = global_registry()
)

Arguments

name

The name of the metric.

help

A brief, one-sentence explanation of the metric's meaning.

labels

A vector of label names for the metric.

...

For backward compatibility, otherwise ignored.

unit

An optional unit for the metric, e.g. "seconds". Must match the metric name.

registry

Where to register the metric for later retrieval.

buckets

A sequence of buckets to bin observations into. Defaults to Prometheus's suggested buckets, which are a good fit for measuring user-visible latency in seconds (e.g. for web services).

Value

An object with methods to manipulate the metric. See details.

Details

All metric objects have a reset() method that reverts the underlying value (or values) to zero, an unregister() method that removes them from the registry they were created in, and a render() method that writes a representation of the metric in the text-based OpenMetrics format. Normally, render_metrics() is used instead.

In addition, various metrics have their own methods:

inc(by = 1, ...): Increments the metric by some positive number, defaulting to 1. Further parameters are interpreted as labels. Available for counters and gauges.
dec(by = 1, ...): Decrements the metric by some number, defaulting to 1. Further parameters are interpreted as labels. Available for gauges.
set(value, ...): Sets the metric to some number. Further parameters are interpreted as labels. Available for gauges.
set_to_current_time(...): Sets the metric to the current time, in seconds from the Unix epoch. Further parameters are interpreted as labels. Available for gauges.
observe(value, ...): Records an observation of some number. Further parameters are interpreted as labels. Available for histograms.
time(expr, ...): Records an observation for the time elapsed evaluating expr, in seconds. Further parameters are interpreted as labels. Available for histograms.

Examples

Run this code

# NOT RUN {
meows <- counter_metric("meows", "Heard around the house.", labels = "cat")
meows$inc(cat = "Shamus") # Count one meow from Shamus.
meows$inc(3, cat = "Unknown") # Count three meows of unknown origin.
meows$render()

thermostat <- gauge_metric("thermostat", "Thermostat display.")
thermostat$set(21.3) # Read from the display...
thermostat$dec(2) # ... and then turn it down 2 degrees.
thermostat$render()

temperature <- histogram_metric(
  "temperature", "Ambient room temperature measurements.",
  buckets = c(10, 15, 20, 22, 25), labels = "room"
)
set.seed(9090)
# Simulate taking ambient temperature samples.
for (measure in rnorm(20, mean = 21.5)) {
  temperature$observe(measure, room = sample(c("kitchen", "bathroom"), 1))
}
temperature$render()

# }