Metrics

You can think of metrics as a stream of tiny, time-stamped events, that flow into a special kind of database, organized to efficiently query such a stream, and aggregate the results in multiple useful ways. A full explanation of metrics is beyond the scope of this document, however.

Metrics are a key part of observability, the ability to see how your application, running as tens or hundreds (or thousands) of servers, is operating as a whole. Where logging can give you information about a specific request, and can somewhat grudgingly aggregate data together - metrics services such as Prometheus exist to aggregate vast amounts of data points together, and give you the ability to see what’s happening to your application now, or over time, broken up by any number of dimensions. Dimensions are used to select events by application-supplied values, that can include such things as the server’s hostname, a request’s URI, the environment (staging vs. production), or the AWS region.

At the core, your application will include extra code to emit metrics; depending on the underlying metrics service you are using, these are either stored in-memory until scraped by another collecting service, or pushed to the collecting service at intervals.

Pedestal’s default metrics library is DropWizard, and the default configuration stores the results internally in JMX.

The metrics functions are defined in the api:*[] namespace, along with supporting protocols and utility functions.

Generally, there is no need to define a metric before using it; it will be registered or created, from its name, automatically when first used.

All of these metrics-producing functions have two forms: the canonical form accepts a recorder, the metric name, and additional arguments; the common form omits the recorder, and uses the api:default-recorder[].

A metric name can be any object that can be converted to a string; usually a fully qualified symbol or keyword. For a keyword, the leading : stripped off.