Use /actuator/metrics to inspect individual measurements; use /actuator/prometheus when setting up ongoing collection with a compatible monitoring system.

Spring Boot exposes these two endpoints for different jobs. Both rely on Micrometer instrumentation and can report JVM and HTTP measurements, but one is optimized for diagnostics while the other publishes metric series for collectors. Here's how to configure them and decide which to use.

How Actuator, Micrometer, and Prometheus fit together

The names are easy to mix up:

  • Spring Boot Actuator adds production-oriented management features, including health and metrics endpoints.
  • Micrometer is the metrics instrumentation facade used by Spring Boot. It records measurements such as JVM memory use, HTTP requests, and request durations.
  • A Micrometer registry exports those measurements to a particular monitoring system or format. The Prometheus registry makes them available in Prometheus-compatible exposition format.
  • Prometheus is also the name of a separate monitoring server that can scrape, store, and query those metrics. Exporting in its format does not require running that server.

Spring Boot's official metrics documentation covers the available registry integrations in detail.

/actuator/metrics: inspect a meter

The JSON metrics endpoint is useful when you want to answer a specific diagnostic question:

curl -s http://127.0.0.1:8080/actuator/metrics
curl -s http://127.0.0.1:8080/actuator/metrics/jvm.memory.used

The first request lists available meter names. The second returns measurements and available tags for jvm.memory.used. You can narrow the result by tag:

curl -s 'http://127.0.0.1:8080/actuator/metrics/jvm.memory.used?tag=area:heap'

This query narrows the result to heap memory pools. The JSON endpoint aggregates matching meter values, so add an id tag to inspect a specific pool.

The endpoint does not provide a time-series database or historical graphs. A monitoring tool that uses its JSON interface must select meters, query them, and maintain its own history. That's possible, but it is a different workflow from scraping a metrics exposition endpoint.

/actuator/prometheus: expose metrics for collection

The Prometheus endpoint returns multiple metric series in a standard text exposition format. A collector can retrieve a snapshot with one HTTP request and retain observations over time.

For example:

curl -s http://127.0.0.1:8080/actuator/prometheus | grep '^jvm_memory_used_bytes'

Depending on your runtime, the output contains series for JVM memory pools with labels such as area and id. The exact meters present depend on your application, dependencies, configuration, and traffic.

A monitoring system can periodically collect these samples, calculate changes in counters, and build charts or alerts. The endpoint does not itself store history or render dashboards.

One naming detail can be surprising: a meter named jvm.memory.used in Actuator JSON typically appears as jvm_memory_used_bytes in Prometheus format. Micrometer applies Prometheus naming conventions and adds the base unit to the metric name.

Enable both endpoints in Spring Boot

For an existing Spring Boot application, add Actuator if it isn't already present, plus the Prometheus Micrometer registry. With Spring Boot's dependency management, you ordinarily don't need to specify versions for these dependencies.

Maven (pom.xml):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Gradle (Groovy DSL):

implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'io.micrometer:micrometer-registry-prometheus'

For a local comparison, expose both endpoints in application.properties:

management.endpoints.web.exposure.include=health,metrics,prometheus

Or use the equivalent application.yml:

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus

Restart the application, then try:

curl -s http://127.0.0.1:8080/actuator/metrics/jvm.memory.used
curl -s http://127.0.0.1:8080/actuator/prometheus

These examples assume Actuator runs on the application port with the default /actuator base path and that you're accessing it locally. Use your configured management host, port, and path if they differ.

For production, expose only the endpoints your monitoring or operations actually need. If you collect Prometheus-format metrics and have no reason to expose the JSON metrics endpoint, you can use:

management.endpoints.web.exposure.include=health,prometheus

Configure access control separately from endpoint exposure. Protect management endpoints with appropriate authentication and/or private network access; don't expose metrics publicly by accident. If your application defines its own Spring Security filter chains, check the rules for Actuator explicitly rather than assuming Spring Boot will secure them for you. See the Actuator endpoint security documentation.

Which endpoint should you choose?

Use /actuator/metrics when:

  • You're debugging a specific metric or checking which meters exist.
  • You want to inspect measurements filtered by a particular tag.
  • An existing diagnostic tool or integration explicitly relies on Actuator JSON.

Prefer /actuator/prometheus when:

  • You're configuring ongoing metrics collection from a Spring Boot service.
  • Your monitoring tool consumes Prometheus/OpenMetrics exposition.
  • You want a conventional scrape interface that other compatible monitoring systems can use later.

Actuator JSON can still be collected periodically, and Prometheus exposition can be inspected manually. Choose the interface that fits your collector or diagnostic workflow.

Common problems

/actuator/prometheus returns 404. Check that micrometer-registry-prometheus is on the runtime classpath, that prometheus is included in HTTP endpoint exposure, and that the application was restarted after the change. Confirm the management port and base path. An unavailable or disabled endpoint may also be absent because of access configuration.

/actuator/metrics returns 404. The JSON metrics endpoint must be exposed separately. Enabling prometheus does not automatically expose metrics.

A specific HTTP request meter is missing. Metrics such as http.server.requests may not appear until the application has actually handled requests. Make a few requests to an application route and check again. Instrumentation and naming can differ across application stacks.

The endpoint returns 401 or 403. Check whether the client is authenticated and allowed to reach the endpoint. Configure the scraper credentials or network access as appropriate for your setup.

From metrics endpoints to a dashboard

Once an endpoint is configured, you still need something to collect and visualize its measurements. For a few Spring Boot applications, that doesn't have to mean deploying both Prometheus and Grafana.

I built StatLite for exactly this job: a self-hosted monitoring tool using about 15 MiB of idle RAM. It stores history in SQLite, charts request rates, errors, latency, and JVM memory, and supports both Actuator JSON and Micrometer's Prometheus format. For PromQL or arbitrary custom metrics, use a general-purpose backend like Prometheus.

For a step-by-step setup, see Lightweight Spring Boot Monitoring Without Prometheus and Grafana.

Further reading: Spring Boot Metrics · Spring Boot Actuator Endpoints · Micrometer Prometheus Registry.