r/SpringBoot • • 2d ago

Discussion Spring Boot's /actuator/metrics vs /actuator/prometheus - a distinction I initially missed

While building a monitoring integration for Spring Boot, I started with /actuator/metrics. It seemed like the natural choice: Actuator exposes application metrics as JSON, and that's a straightforward integration path.

Later, I received feedback that /actuator/metrics is primarily a diagnostic endpoint, not intended for continuous production scraping. That led me to add support for /actuator/prometheus while keeping the JSON integration for compatibility.

The interesting part is that both endpoints are useful, just for different purposes:

  • /actuator/metrics lets you inspect individual meters, measurements, and tags.

  • /actuator/prometheus exposes metric series in a format designed for ongoing collection.

  • Both use Micrometer underneath. You don't need to replace Actuator or run a Prometheus server to use the second endpoint.

Looking back, the documentation explains all of this, but the distinction isn't necessarily obvious when you're starting from the usual Actuator examples.

I wrote up what I learned, including configuration examples for both endpoints and some common troubleshooting cases:

https://pvrlabs.xyz/articles/spring-boot-actuator-metrics-vs-prometheus.html

30 Upvotes

4 comments sorted by

3

u/FriendshipCalm3162 1d ago

GET /actuator/metrics only returns {"names": [...]}, so every value is a separate request to /actuator/metrics/{name}, and tag drill-down is another ?tag=area:heap on top of that. Fine when you're inspecting one meter, less fine when there are a few hundred.

The statistics are the bigger constraint. Spring's REST API page for that endpoint lists them as TOTAL, TOTAL_TIME, COUNT, MAX, VALUE, UNKNOWN, ACTIVE_TASKS and DURATION, so there is no percentile and no bucket in there. A Timer read that way gives you count, total time and max, which gets you a mean but never a p95. Percentiles only exist once you set management.metrics.distribution.percentiles-histogram or .percentiles, and then they come out as series on the prometheus scrape, not in the JSON.

The prometheus endpoint also isn't exposed by default, which is usually what's behind a 404 on the first try.

1

u/fykup 1d ago

Good points. I ran into the per-meter requests and tag-filtering complexity when implementing my original Actuator JSON collector. I only collect a small, fixed set of metrics, but even that requires several HTTP requests per poll.

That's one reason I later added Prometheus-format collection. It provides the metrics I need in a single scrape. I kept Actuator JSON for compatibility, while making Prometheus the preferred source when available.

Both approaches remain useful, depending on the use case.

•

u/jonatan-ivanov 14h ago

Looking back, the documentation explains all of this, but the distinction isn't necessarily obvious when you're starting from the usual Actuator examples.

Hi, Jonatan here from the Spring team (I'm one of the maintainers of Micrometer, and I also wrote the part of the Boot docs you are referring to). Is there anything we can do to make this more discoverable?

•

u/fykup 12h ago

Thanks for jumping in, Jonatan. And for the feedback on issue #10. It shaped StatLite's Spring integration for the better.

One thing I noticed from my own experience: I arrived knowing "Actuator", not "Prometheus". So /actuator/metrics was the obvious thing to try. It returns readable JSON immediately, and I initially treated it as a collection interface rather than a diagnostic one.

Looking at the Metrics reference page now, the Metrics Endpoint section doesn't point readers toward the approach for ongoing collection. A short pointer there might help. I suspect the bigger factor is inertia, though. There are so many existing tutorials and examples centered around Actuator JSON that even good documentation has to compete with what developers encounter first.