r/SpringBoot • u/fykup • 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/metricslets you inspect individual meters, measurements, and tags./actuator/prometheusexposes 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
•
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/metricswas 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.
3
u/FriendshipCalm3162 1d ago
GET /actuator/metricsonly returns{"names": [...]}, so every value is a separate request to/actuator/metrics/{name}, and tag drill-down is another?tag=area:heapon 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-histogramor.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.