Micrometer Prometheus client v1.x breaking changes #2340

brunobat · 2025-06-18T16:05:19Z

This is a blog post to communicate the Micromenter Prometheus client v1.x changes.

github-actions · 2025-06-18T16:11:53Z

🎊 PR Preview 83f0c34 has been successfully built and deployed to https://quarkus-site-pr-2340-preview.surge.sh

Images of blog posts older than 3 months are not available.
Newsletters older than 3 months are not available.

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

Copilot

Pull Request Overview

This PR introduces a new documentation post detailing the migration paths and breaking changes resulting from the switch to Prometheus client v1 in the Micrometer registry.

Introduces a new post explaining upgrade options and dependency changes
Details specific changes to metrics naming and API usage

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

brunobat · 2025-06-20T09:43:37Z

There is a plan change:

Keep current extension as is until Quarkus 4.0 (whenever that happens)
Create a new extension called quarkus-micrometer-registry-prometheus-v1 now
Delete current quarkus-micrometer-registry-prometheus on Quarkus 4.0. Provide alternative on Quarkiverse.
Refactor: Stramline the main extension (quarkus-micrometer) and quarkus-micrometer-registry-prometheus-v1 to remove outdated code on Quarkus 4.0.
On the next LTS it would be good to mark for deprecation the old registry and support the new one.

Will re-write the blog to reflect that.

brunobat · 2025-06-20T16:39:53Z

Re-wrote the post according to the new plan and zulip coments.
I still need to come up with better examples for the changes.
Will finish when I know when we will release the new extension.

brunobat · 2025-07-02T08:31:01Z

This is on hold due to other ongoing work.

Micrometer prometheus client v1.0 breaking changes

brunobat · 2025-10-20T16:22:37Z

Updated the post. It's now ready to review.

cescoffier

I need to read it again on my machine (on my phone now).

We should also advertise the working group

cescoffier · 2025-10-20T16:28:19Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+
+[INFO]
+====
+Users should move to the new `quarkus-micrometer-registry-prometheus-v1` extension.


Hold on, does this change the metrics? If so, sure they should move but be aware that they dashboards and alerts and queries are now incorrect

Instead of info it should be inclined, in the flow of the required changes. We should invite the users to check the breaking change section before making a decision.

sure, I can tone down the message, but they should work one migration, regardless. Will update.

cescoffier · 2025-10-20T16:29:36Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+=== Migration plan
+
+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 https://docs.quarkiverse.io/quarkus-micrometer-registry/dev/micrometer-registry-prometheus-v1.html[`quarkus-micrometer-registry-prometheus-v1`].


What if you use both at the same time? What happens?

In theory they could work at the same time but they will clash for sure because they will both try to publish the /q/metrics endpoint.

Will test what happens.

cescoffier · 2025-10-20T16:31:18Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+* `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`


Do we have the list?

I don't have a list.
I would need to activate all metrics in a big nr of extensions to get that. It can be done... But I would prefer not to because this is a pattern change that can be extrapolated without an exhaustive list.

cescoffier · 2025-10-20T16:32:06Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+
+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.


I would separate these changes into 2 categories:

metric format changes (type, name..)

implementation changes

cescoffier · 2025-10-20T16:32:58Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+
+Micrometer has become the default metrics framework in Quarkus due to its stability, maturity, and widespread adoption on the Java ecosystem — not https://quarkus.io/guides/opentelemetry-metrics[OpenTelemetry Metrics].
+
+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.


Of not af :-)

brunobat · 2025-10-21T08:22:34Z

I need to read it again on my machine (on my phone now).

We should also advertise the working group

I can publicize this in that discussion but this is not part of the scope of that group.

cescoffier · 2025-10-21T08:52:42Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+
+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 https://docs.quarkiverse.io/quarkus-micrometer-registry/dev/micrometer-registry-prometheus-v1.html[`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.


That list looks like implementation tasks.

They are, we are explaining what we are going to do next.

cescoffier · 2025-10-21T08:53:00Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+** Move the new https://docs.quarkiverse.io/quarkus-micrometer-registry/dev/micrometer-registry-prometheus-v1.html[`quarkus-micrometer-registry-prometheus-v1`] extension from Quarkiverse to Quarkus core repo and make it the default registry.
+** Refactor the https://quarkus.io/guides/telemetry-micrometer[`quarkus-micrometer`] extension tests to use the new client.
+
+=== Prometheus Client v1.x changes


Rename it to "breaking changes"

cescoffier · 2025-10-21T09:03:34Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+* 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"`


Why do we have the " ?

It was just to delimit the String and it can go away.

cescoffier · 2025-10-21T09:05:39Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+* 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].
+
+For more details on Observability in Quarkus please visit https://quarkus.io/guides/observability[this guide].


Question: do all these ways use the same metric conventions?

No, Micrometer and OpenTelemetry follow different semantic conventions, however, Micrometer metrics telemetry going out through the quarkus-micrometer-opentelemetry extension will keep the Micrometer semantic conventions alignment. It's not 1:1 but close and documented here: https://quarkus.io/guides/telemetry-micrometer-to-opentelemetry#semantic-convention-differences
Probably worth mentioning it... Will update.

cescoffier · 2025-10-21T09:07:36Z

_posts/2025-10-21-micrometer-prometheus-v1.adoc

+
+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


I would remove this sentence.

It's just because we mention a future version with no estimated date, at least, they can keep an eye here... You still think we should remove it?

nderwin reviewed Jun 18, 2025

View reviewed changes

_posts/2025-06-18-micrometer-prometheus-v1.adoc Outdated Show resolved Hide resolved

nderwin reviewed Jun 18, 2025

View reviewed changes

_posts/2025-06-18-micrometer-prometheus-v1.adoc Outdated Show resolved Hide resolved

gastaldi requested a review from Copilot June 18, 2025 17:26

Copilot AI reviewed Jun 18, 2025

View reviewed changes

_posts/2025-06-18-micrometer-prometheus-v1.adoc Outdated Show resolved Hide resolved

_posts/2025-06-18-micrometer-prometheus-v1.adoc Outdated Show resolved Hide resolved

brunobat marked this pull request as draft June 20, 2025 07:43

brunobat force-pushed the develop branch from e2c07f6 to 7fee08e Compare June 20, 2025 16:38

Get the traceId into the access logs

85e3608

Micrometer prometheus client v1.0 breaking changes

brunobat force-pushed the develop branch from 7fee08e to 85e3608 Compare October 20, 2025 16:21

brunobat marked this pull request as ready for review October 20, 2025 16:22

brunobat requested review from cescoffier and insectengine October 20, 2025 16:24

brunobat changed the title ~~Micrometer Prometheus client v1.0 breaking changes~~ Micrometer Prometheus client v1.x breaking changes Oct 20, 2025

cescoffier requested changes Oct 20, 2025

View reviewed changes

cescoffier requested changes Oct 21, 2025

View reviewed changes


		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.


		Micrometer has become the default metrics framework in Quarkus due to its stability, maturity, and widespread adoption on the Java ecosystem — not https://quarkus.io/guides/opentelemetry-metrics[OpenTelemetry Metrics].

		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.


		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

Uh oh!

Micrometer Prometheus client v1.x breaking changes #2340

Are you sure you want to change the base?

Micrometer Prometheus client v1.x breaking changes #2340

Uh oh!

Conversation

brunobat commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

brunobat commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brunobat commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brunobat commented Jul 2, 2025

Uh oh!

brunobat commented Oct 20, 2025

Uh oh!

cescoffier left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brunobat Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brunobat commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

brunobat commented Jun 18, 2025 •

edited

Loading

github-actions bot commented Jun 18, 2025 •

edited

Loading

brunobat commented Jun 20, 2025 •

edited

Loading

brunobat commented Jun 20, 2025 •

edited

Loading

brunobat Oct 21, 2025 •

edited

Loading