1.13 Migration Guide

This guide helps users upgrading from Micrometer 1.12.x to Micrometer 1.13.x by explaining changes users should be aware of and potentially take action on. See also the release page for included changes.

Prometheus client 0.x to 1.x upgrade

The micrometer-registry-prometheus module has upgraded to the Prometheus Java client 1.x version, which required some breaking changes from the prior 0.x version. The breaking changes may not affect all users depending on whether you are directly interacting with the API in PrometheusMeterRegistry or a framework is handling that configuration for you. As a fallback to ease upgrading, the previous code based on the Prometheus Java client 0.x is available in a new module named micrometer-registry-prometheus-simpleclient (deprecated). The plan is to eventually remove support for the micrometer-registry-prometheus-simpleclient so it should only be used as an interim solution until you can adapt to the necessary changes in micrometer-registry-prometheus related to the upgrade to Prometheus Java client 1.x.

Package change

The micrometer-registry-prometheus module now uses the base package io.micrometer.prometheusmetrics rather than the previous io.micrometer.prometheus. If you are using any of the classes in the module in your code, you will need to update the import of the class.

For example

import io.micrometer.prometheus.PrometheusMeterRegistry;

should be replaced to

import io.micrometer.prometheusmetrics.PrometheusMeterRegistry;

and so on.

API changes

Some types exposed in the micrometer-registry-prometheus module's API were from the Prometheus Java client and they have changed. Accordingly, the API in PrometheusMeterRegistry has changed. Specifically, where a CollectorRegistry was used before, now a PrometheusRegistry is. The constructor that took an io.prometheus.client.exemplars.ExemplarSampler for exemplar support now takes a io.prometheus.metrics.tracer.common.SpanContext instead.

For example creating a PrometheusMeterRegistry using the Prometheus Java client 0.x can look like this:

import io.micrometer.prometheus.*;

PrometheusMeterRegistry prometheusMeterRegistry = new PrometheusMeterRegistry(
            PrometheusConfig.DEFAULT,
            new CollectorRegistry(),
            Clock.SYSTEM,
            new DefaultExemplarSampler(new DemoSpanContextSupplier())
);

the same with the Prometheus Java client 1.x can look like this:

import io.micrometer.prometheusmetrics.*;

PrometheusMeterRegistry prometheusMeterRegistry = new PrometheusMeterRegistry(
            PrometheusConfig.DEFAULT,
            new PrometheusRegistry(),
            Clock.SYSTEM,
            new DemoSpanContext()
);

LongTaskTimer scrape output

LongTaskTimer is now registered as a GaugeHistogram type metric with the Prometheus registry rather than a Histogram/Summary type. The _count and _sum time series are now _gcount and _gsum and they will no longer have _active and _duration respectively appended to the base metric name. See the following sample.

Old Client (0.x) (micrometer-registry-prometheus-simpleclient)

# HELP spring_security_authorizations_active_seconds
# TYPE spring_security_authorizations_active_seconds summary
spring_security_authorizations_active_seconds_active_count{application="my-app",spring_security_authentication_type="n/a",spring_security_authorization_decision="unknown",spring_security_object="request",} 0.0
spring_security_authorizations_active_seconds_duration_sum{application="my-app",spring_security_authentication_type="n/a",spring_security_authorization_decision="unknown",spring_security_object="request",} 0.0

New Client (1.x) (micrometer-registry-prometheus)

# HELP spring_security_authorizations_active_seconds
# TYPE spring_security_authorizations_active_seconds gaugehistogram
spring_security_authorizations_active_seconds_gcount{application="my-app",spring_security_authentication_type="n/a",spring_security_authorization_decision="unknown",spring_security_object="request"} 0
spring_security_authorizations_active_seconds_gsum{application="my-app",spring_security_authentication_type="n/a",spring_security_authorization_decision="unknown",spring_security_object="request"} 0.0