Micrometer prometheus client v1.0 breaking changes

Author: brunobat

_posts/2025-06-18-micrometer-prometheus-v1.adoc

@@ -0,0 +1,73 @@
+---
+layout: post
+title: 'Quarkus Micrometer using Prometheus client v1'
+date: 2025-06-12
+tags: micrometer prometheus
+synopsis: Micrometer has moved to use the Prometheus client v1. This post explains the migration paths and required changes for applications.
+author: brunobat
+---
+
+== Quarkus Micrometer using Prometheus client v1
+
+Micrometer has moved to using the Prometheus Client v1.x.
+
+This change has happened on Micrometer v1.13 but since then, in quarkus we have been using the legacy `io.prometheus:simpleclient`
+to not interfere with the release of the previous LTS and to provide a clear migration path to all Quarkus applications.
+
+The time to upgrade comes with the upcoming Quarkus 3.25.0, and you might not need to take action, but if your application is affected there will be two choices:
+
+1. Upgrade Quarkus, deal with the breaking changes and use the new client version. This is the recommended path.
+2. Continue using the legacy and deprecated Prometheus client v0.x by using a newly created extension on Quarkiverse.
+
+=== Upgrade Quarkus and use Prometheus Client v1.x
+
+The `quarkus-micrometer-registry-prometheus` extension is now using the Prometheus Client v1.x including breaking changes expressed in detail on the https://github.com/micrometer-metrics/micrometer/wiki/1.13-Migration-Guide[Micrometer 1.13 Migration Guide], featuring package, API and semantic convention changes.
+
+These are the main points to consider in the new Quarkus 3.25.0:
+
+* Counters now use Longs instead of Doubles.
+** Before: `"registry=\"prometheus\",status=\"200\",uri=\"/example/prime/{number}\"} 2.0`
+** Now: `"registry=\"prometheus\",status=\"200\",uri=\"/example/prime/{number}\"} 2`
+* `io.micrometer.prometheusmetrics.PrometheusMeterRegistry` must be used instead of the old `io.micrometer.prometheus.PrometheusMeterRegistry`.
+* `io.prometheus.metrics.tracer.common.SpanContext` must be used instead of the old `io.prometheus.client.exemplars.ExemplarSampler`
+* The new Prometheus client uses some reserved words that must not be used to name metrics, therefore some metrics were renamed. Some examples of reserved words and renamed metrics:
+** `info`. Before: `jvm_info_total`. Now: `jvm_total`
+** `duration`. Before: `http_server_requests_duration_seconds`. Now: `http_server_requests_seconds`
+* Some metrics would display Tags ending in a comma (`,`). This tailing comma has now been removed. Example: `"hibernate_flushes_total{entityManagerFactory=\"<default>\",env=\"test\",env2=\"test\",registry=\"prometheus\",} 1.0"`
+* It is no longer possible to create a metric generating Service Level Objectives and Percentiles at the same time.
+
+Other changes:
+
+* Metrics must be registered always with the same tags. Micrometer will now send a warning if we register the same metric more than once with different Tag names.
+
+Quarkus automatic instrumentation is now producing metrics according to these changes. If your application generates their custom metrics, please update metrics creation, tests and dashboard queries according to the above guidelines.
+
+=== Continue using the legacy and deprecated Prometheus client v0.x
+
+This is a short term solution because the old v0.x client is deprecated and will be removed at some point.
+
+In this case, the core extension must be *removed*:
+
+```xml
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-micrometer-registry-prometheu</artifactId>
+</dependency>
+```
+
+And the legacy Quarkiverse extension must be *added*:
+
+```xml
+<dependency>
+    <groupId>${project.groupId}</groupId>
+    <artifactId>quarkus-micrometer-registry-prometheus-simpleclient</artifactId>
+</dependency>
+```
+
+from this repository: https://github.com/quarkiverse/quarkus-micrometer-registry/tree/main/micrometer-registry-prometheus-simpleclient[micrometer-registry-prometheus-simpleclient] after version 3.4.0.
+
+=== Conclusion
+
+The Micrometer extension is the recommended way to generate metrics in Quarkus and this a rare moment were breaking changes were introduced. Now is the moment to evaluate if you application requires Micrometer related changes, in face of Quarkus 3.25.0.
+
+For more details on Observability in Quarkus please visit https://quarkus.io/guides/observability[this guide].