Metrics

Pedestal metrics are a wrapper around Open Telemetry, which provides cross-platform solutions for metrics, tracing, and logging ^[1].

Metrics and tracing are provided in the io.pedestal/pedestal.telemetry library.

The io.pedestal.metrics namespace contains the API that applications can use to emit metrics.

Supported Metrics Types

Pedestal supports:

counter: A numeric value that increases over time, such as the number of requests processed.
gauge: Measures value that varies over time, such as the depth of a queue.
timer: Measures a duration and a count, used for things like request processing time.
histogram: Tracks a range of values, exposing them in different bucket ranges; useful for identifying broad trends, and used for metrics such as size of incoming requests.

Setup

The metrics API is built around the default-metric-source, which is created at startup from a function identified by runtime configuration.

Open Telemetry defines a wide range of JVM system properties and environment variables to configure metrics (and tracing); those are outside the scope of this document.

Rather than rely on outside configuration, an application can provide its own initialization function to setup Open Telemetry as needed.

Value Types

The Open Telemetry framework supports long or double as the value types inside metrics; Pedestal expects any underlying metrics framework to do the same, even if it means converting provided value types.

By default, metric values are of type long. This can be overridden using configuration.

In addition, the attribute :io.pedestal.metrics/value-type can be applied to any metric; the value for the attribute should be either :long or :double.

Pedestal will convert supplied longs or doubles to the correct type for the particular metric.

Built-in Metrics

Pedestal has a small amount of built-in metrics.

:io.pedestal.http/request: A counter of the number of incoming requests, produced by the log-request interceptor.
:io.pedestal.http.cors/origin-real: A counter for the number of requests that are allowed, produced by the allow-origin interceptor.
:io.pedestal.http.impl.servlet-interceptor/base-servlet-error: A counter for number of uncaught exceptions thrown during interceptor execution.
:io.pedestal/active-servlet-calls: A gauge measuring the number of active requests in progress at any one time.
:io.pedestal.http.sse/payload-size: A histogram measuring the size of server-sent messages sent to the client.
:io.pedestal.http.sse/active-streams: A gauge of the number of active streams sending server-sent messages.
:io.pedestal.http.impl.servlet-interceptor/async-write-errors: A counter of the number of times that the asynchrounous pipe to a client closed during delivery of a streaming response.

1. In fact, there’s an extra layer of abstraction: namespace io.pedestal.metrics.spi which defines the protocol that can be implemented to capture metrics without using Open Telemetry.