Micrometer prometheus client v1.0 breaking changes

Author: brunobat

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

@@ -3,27 +3,37 @@ 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.
+synopsis: Micrometer has moved to use the Prometheus client v1. This post explains the migration path and required changes for applications.
 author: brunobat
 ---
 
 == Quarkus Micrometer using Prometheus client v1
 
-Micrometer has moved to using the Prometheus Client v1.x.
+Micrometer adopted Prometheus Client v1.x starting with version 1.13. However, Quarkus still uses Prometheus Client v0.x by default through the `quarkus-micrometer-registry-prometheus` extension which has been using the legacy `io.prometheus:simpleclient`.
 
-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.
+This existing extension will remain available throughout the Quarkus 3.x series but is now declared *deprecated*. In parallel, we’ll be introducing a new extension: `quarkus-micrometer-registry-prometheus-v1`, which integrates the new client.
 
-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:
+[INFO]
+====
+Users should move to the new `quarkus-micrometer-registry-prometheus-v1` extension.
+====
 
-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.
+Since the new client introduces *breaking changes*, we’ve prepared a migration plan designed to reduce the impact on existing users.
 
-=== Upgrade Quarkus and use Prometheus Client v1.x
+=== Migration plan
 
-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.
+1. Keep current extension as is until Quarkus 4.0 (whenever that happens) so users can migrate at a time of their choice.
+2. Introduce a new extension called `quarkus-micrometer-registry-prometheus-v1`.
+3. Remove current `quarkus-micrometer-registry-prometheus` on Quarkus 4.0 (no timeline at this moment) while providing an alternative on Quarkiverse. Quarkus users will get an additional migration period by using an upcoming community supported Quarkiverse extension.
+4. Refactor code on Quarkus 4.0: Stramline https://quarkus.io/guides/telemetry-micrometer[`quarkus-micrometer`], the main extension and `quarkus-micrometer-registry-prometheus-v1` to remove legacy code from Quarkus 4.0. At some point after this, we might rename `quarkus-micrometer-registry-prometheus-v1` to `quarkus-micrometer-registry-prometheus` and provide automatic redirects for the artifacts. Users of the new client will not be impacted.
 
-These are the main points to consider in the new Quarkus 3.25.0:
+
+
+=== Prometheus Client v1.x changes
+
+The `quarkus-micrometer-registry-prometheus-v1` extension will be using the Prometheus Client v1.x and includes *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 when migrating to the new Quarkus extension:
 
 * Counters now use Longs instead of Doubles.
 ** Before: `"registry=\"prometheus\",status=\"200\",uri=\"/example/prime/{number}\"} 2.0`
@@ -40,34 +50,32 @@ 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.
+Quarkus automatic instrumentation will generate metrics reflecting these changes. If your application defines custom metrics, be sure to update their creation, associated tests, and any dashboard queries to align with the guidelines above.
 
-=== Continue using the legacy and deprecated Prometheus client v0.x
+=== About metrics in Quarkus
 
-This is a short term solution because the old v0.x client is deprecated and will be removed at some point.
+The https://quarkus.io/guides/telemetry-micrometer[Micrometer extension] is the recommended approach to generate metrics in Quarkus and this a rare occasions were breaking changes are being introduced.
 
-In this case, the core extension must be *removed*:
+Micrometer has become the default metrics framework in Quarkus due to its stability, maturity, and widespread adoption — not https://quarkus.io/guides/opentelemetry-metrics[OpenTelemetry Metrics].
 
-```xml
-<dependency>
-    <groupId>io.quarkus</groupId>
-    <artifactId>quarkus-micrometer-registry-prometheu</artifactId>
-</dependency>
-```
+Micrometer support in Quarkus is built on top af a main extension `quarkus-micrometer`, then specific registries extensions include it as a dependency and implement a registry sending out the telemetry. The Prometheus registry (`quarkus-micrometer-registry-prometheus`) is the default and most commonly used, and it is the focus of this announcement.
 
-And the legacy Quarkiverse extension must be *added*:
+However, there are alternative ways to export metrics using Micrometer:
 
-```xml
-<dependency>
-    <groupId>${project.groupId}</groupId>
-    <artifactId>quarkus-micrometer-registry-prometheus-simpleclient</artifactId>
-</dependency>
-```
+* Through the https://github.com/quarkiverse/quarkus-micrometer-registry/[Quarkiverse Micrometer registries]
+* Via OpenTelemetry, using a bridge provided by the https://quarkus.io/guides/telemetry-micrometer-to-opentelemetry[Micrometer and OpenTelemetry] extension. This setup allows Micrometer metrics to be sent as OpenTelemetry metrics, offering a unified output via the https://opentelemetry.io/docs/specs/otlp/[OpenTelemetry OTLP protocol].
 
-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.
+For more details on Observability in Quarkus please visit https://quarkus.io/guides/observability[this guide].
 
 === 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.
+While the existing Prometheus registry remains available for the Quarkus 3.x lifecycle, it is now deprecated, and users are encouraged to begin migrating to the new extension because the old client extension will be removed on Quarkus 4.0 (no timeline at this moment).
+
+This change introduces a number of breaking updates aligned with Micrometer 1.13 and Prometheus Client v1.x, affecting metric types, naming conventions, and APIs.
+
+To support users, a migration plan has been outlined to provide flexibility and minimize disruption.
+
+The prometheus client is not the only option to send out telemetry, there are alternative options such as the Quarkiverse registries or our OpenTelemetry bridge.
+
+You can follow Quarkus release dates here: https://github.com/quarkusio/quarkus/wiki/Release-Planning
 
-For more details on Observability in Quarkus please visit https://quarkus.io/guides/observability[this guide].