Metrics Support for Exemplars

Add Helidon MP support for OpenMetrics (Prometheus) exemplars to your application simply by adding dependencies to your project’s pom.xml.

Prerequisites

Declare the following dependency in your project:

<dependency>
    <groupId>io.helidon.metrics</groupId>
    <artifactId>helidon-metrics-trace-exemplar</artifactId>
    <scope>runtime</scope>
</dependency>
Copied

Also, include either Helidon Zipkin or Helidon Jaeger support:

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-zipkin</artifactId>
</dependency>
Copied

or

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-jaeger</artifactId>
</dependency>
Copied

Be sure Zipkin or Jaeger, whichever you chose, is running and accessible to your server.

Interpreting Exemplars

Note

exemplar - one that serves as a model or example

 — Merriam-Webster Dictionary

When you add the helidon-metrics-trace-exemplar dependency—​and one for either Zipkin or Jaeger—​to your application, Helidon automatically records a sample (label, value, and timestamp) with each update to a histogram, simple timer, or counter. Helidon adds the label, value, and timestamp to the OpenMetrics output returned from the Helidon metrics endpoint (/metrics unless you set it up otherwise).

By default, Helidon adds exemplars only to counters and the counter portion of simple timers. The OpenMetrics specification allows exemplars only on counters and buckets. (Helidon’s histogram output, consistent with the MicroProfile Metrics spec, includes the quantiles but not the buckets.)

Note

Earlier releases of Helidon included exemplars on other metric types as well. If you must keep the prior behavior for compatibility reasons, see the Controlling Exemplar Output section below.

# TYPE application_myCounter_total counter
application_myCounter_total 14 # {trace_id="067632454fe4e8d1"} 1.14701E-4 1617723032.570000
  • This exemplar is the most recent sample.
# TYPE application_globalRequestTracker_total counter
# HELP application_globalRequestTracker_total
application_globalRequestTracker_total 4 # {trace_id="daf26fe35fee9917"} 0.001183992 1617725180.234000
  • The exemplar for a SimpleTimer is the most recent sample which updated the SimpleTimer.

The exemplar information describes a single, actual sample that is representative of the statistical value. Helidon chooses the representative examplar for each value using information that is already recorded for each type of metric.

Controlling Exemplar Output

Once you add dependencies on helidon-metrics-trace-exemplar and one of the Helidon tracing integration libraries to your project, Helidon automatically adds exemplars to those metrics which the OpenMetrics specification permits to have exemplars.

Earlier releases of Helidon added exemplars to other, non-standard metric types. If you require the former behavior for compatibility reasons, you can enable exemplars on non-standard metric types. In this context, with strict exemplar behavior Helidon adds exemplars only to those metrics allowed by the OpenMetrics spec. With lax behavior Helidon also adds exemplars to simple timer and meter output.

Note

The lax exemplar behavior is non-standard. Some downstream consumers of the resulting OpenMetrics output might reject it because it contains non-standard content.

You control strict vs. lax exemplar support separately for each registry type.

Enabling non-standard exemplar behavior in META-INF/microprofile-config.properties
metrics.registries.0.type=application
metrics.registries.0.exemplars.strict = false
Copied

The exemplars.strict setting defaults to true for all registry types.