Metrics

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

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

The io.pedestal.http 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 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.

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.

Compatibility

Where Pedestal emits metrics, it emits them both using the deprecated 0.6 metrics support, and the new pedestal.telemetry implementation.

In addition, there is support for the Drop Wizard metrics library as an alternative to Open Telemetry, via default-registry; this is to provide a migration path from Pedestal 0.6 to Pedestal 0.7 when your application is making use of the deprecated metrics support.

In a future Pedestal release, the deprecated metrics support in the io.pedestal.log namespace will be removed entirely from Pedestal.