Metrics

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.

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.

See also

The OpenMetrics specification on Metric Types as well as the original Prometheus documenation.

Examples

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()
#> [1] "# HELP meows Heard around the house.\n# TYPE meows counter\nmeows_total{cat=\"Shamus\"} 1\nmeows_created{cat=\"Shamus\"} 1625501542.56245\nmeows_total{cat=\"Unknown\"} 3\nmeows_created{cat=\"Unknown\"} 1625501542.56332\n"

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()
#> [1] "# HELP thermostat Thermostat display.\n# TYPE thermostat gauge\nthermostat 19.3\n"

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()
#> [1] "# HELP temperature Ambient room temperature measurements.\n# TYPE temperature histogram\ntemperature_bucket{room=\"bathroom\",le=\"10.0\"} 0\ntemperature_bucket{room=\"bathroom\",le=\"15.0\"} 0\ntemperature_bucket{room=\"bathroom\",le=\"20.0\"} 0\ntemperature_bucket{room=\"bathroom\",le=\"22.0\"} 9\ntemperature_bucket{room=\"bathroom\",le=\"25.0\"} 11\ntemperature_bucket{room=\"bathroom\",le=\"+Inf\"} 11\ntemperature_sum{room=\"bathroom\"} 234.387663039796\ntemperature_count{room=\"bathroom\"} 11\ntemperature_created{room=\"bathroom\"} 1625501542.57906\ntemperature_bucket{room=\"kitchen\",le=\"10.0\"} 0\ntemperature_bucket{room=\"kitchen\",le=\"15.0\"} 0\ntemperature_bucket{room=\"kitchen\",le=\"20.0\"} 1\ntemperature_bucket{room=\"kitchen\",le=\"22.0\"} 4\ntemperature_bucket{room=\"kitchen\",le=\"25.0\"} 9\ntemperature_bucket{room=\"kitchen\",le=\"+Inf\"} 9\ntemperature_sum{room=\"kitchen\"} 198.854388891071\ntemperature_count{room=\"kitchen\"} 9\ntemperature_created{room=\"kitchen\"} 1625501542.5789\n"