Add the dependencies#

Add these dependencies to pom.xml. The Spring Boot parent manages their versions.

1
<!-- Production monitoring and management endpoints -->
2
<dependency>
3
    <groupId>org.springframework.boot</groupId>
4
    <artifactId>spring-boot-starter-actuator</artifactId>
5
</dependency>
6

7
<!-- Prometheus registry for /actuator/prometheus -->
8
<dependency>
9
    <groupId>io.micrometer</groupId>
10
    <artifactId>micrometer-registry-prometheus</artifactId>
11
</dependency>

Configure the endpoints#

The following configuration exposes health, application information, and Prometheus metrics. It also enables the Tomcat MBean registry, which is needed for Tomcat thread metrics.

1
server:
2
  tomcat:
3
    mbeanregistry:
4
      enabled: true
5

6
management:
7
  endpoints:
8
    web:
9
      exposure:
10
        include: health,info,prometheus
11
  endpoint:
12
    health:
13
      show-details: when-authorized
14
      status:
15
        order: DOWN,OUT_OF_SERVICE,UNKNOWN,UP
16
        http-mapping:
17
          UP: 200
18
          DOWN: 503
19
          OUT_OF_SERVICE: 503
20
          UNKNOWN: 503
21
  info:
22
    env:
23
      enabled: true

The custom status order treats UNKNOWN as more severe than UP. This is useful if a custom health indicator reports UNKNOWN and you want the overall endpoint to return HTTP 503. Other indicators still take part in the aggregate status; this configuration does not give one indicator exclusive control.

The source document also exposes env and sets both health.show-details and env.show-values to always. Those settings can help during local debugging, but exposing environment values can reveal credentials. Enable them only in a controlled environment. In production, protect management endpoints with authentication and network access controls. Enabling management.info.env.enabled includes configured info.* properties in /actuator/info.

Export component health as a metric#

/actuator/health reports the health of dependencies such as databases and Redis. It does not automatically create the custom health_status metric used in this guide.

The following component registers one gauge for each top-level HealthIndicator. It reports 1 for UP and 0 for any other status, timeout, or failure.

1
import io.micrometer.core.instrument.Gauge;
2
import io.micrometer.core.instrument.MeterRegistry;
3
import jakarta.annotation.PreDestroy;
4
import org.springframework.boot.actuate.health.Health;
5
import org.springframework.boot.actuate.health.HealthContributorRegistry;
6
import org.springframework.boot.actuate.health.HealthIndicator;
7
import org.springframework.boot.actuate.health.Status;
8
import org.springframework.boot.context.event.ApplicationReadyEvent;
9
import org.springframework.context.event.EventListener;
10
import org.springframework.stereotype.Component;
11

12
import java.util.concurrent.ArrayBlockingQueue;
13
import java.util.concurrent.ExecutionException;
14
import java.util.concurrent.Future;
15
import java.util.concurrent.RejectedExecutionException;
16
import java.util.concurrent.ThreadPoolExecutor;
17
import java.util.concurrent.TimeUnit;
18
import java.util.concurrent.TimeoutException;
19

20
@Component
21
public class HealthMetricsExportBinder {
22
    private static final int CHECK_TIMEOUT_MS = 200;
23

24
    private final ThreadPoolExecutor healthCheckPool = new ThreadPoolExecutor(
25
            6, 6, 0L, TimeUnit.MILLISECONDS,
26
            new ArrayBlockingQueue<>(32),
27
            new ThreadPoolExecutor.AbortPolicy());
28

29
    private final HealthContributorRegistry contributors;
30
    private final MeterRegistry meterRegistry;
31

32
    public HealthMetricsExportBinder(
33
            HealthContributorRegistry contributors,
34
            MeterRegistry meterRegistry) {
35
        this.contributors = contributors;
36
        this.meterRegistry = meterRegistry;
37
    }
38

39
    @EventListener(ApplicationReadyEvent.class)
40
    public void registerHealthGauges() {
41
        contributors.stream().forEach(named -> {
42
            if (named.getContributor() instanceof HealthIndicator indicator) {
43
                Gauge.builder("health_status", indicator, this::healthValue)
44
                        .description("Component health: 1 for UP, 0 otherwise")
45
                        .tag("component", named.getName())
46
                        .register(meterRegistry);
47
            }
48
        });
49
    }
50

51
    private double healthValue(HealthIndicator indicator) {
52
        Future<Health> future = null;
53
        try {
54
            future = healthCheckPool.submit(indicator::health);
55
            Health health = future.get(CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS);
56
            return Status.UP.equals(health.getStatus()) ? 1.0 : 0.0;
57
        } catch (InterruptedException ex) {
58
            Thread.currentThread().interrupt();
59
            return 0.0;
60
        } catch (TimeoutException | ExecutionException
61
                 | RejectedExecutionException ex) {
62
            return 0.0;
63
        } finally {
64
            if (future != null && !future.isDone()) {
65
                future.cancel(true);
66
            }
67
        }
68
    }
69

70
    @PreDestroy
71
    public void destroy() {
72
        healthCheckPool.shutdownNow();
73
    }
74
}

The health checks run in a separate pool, but the scrape still waits for each result. The 200 ms timeout applies to each check, not to the entire scrape. Choose a timeout that suits your dependencies.

This example adds a bounded queue and cancellation to the source’s approach. Cancellation cannot guarantee that a blocked database or network call stops, so configure timeouts in the underlying clients too. For larger systems, refresh health in the background and expose cached values. Composite contributors require traversal of their child indicators; the example above deliberately handles only top-level indicators.

The gauge is independent of management.endpoint.health.show-details.

Verify the output#

Start the application and request:

1
curl http://localhost:8080/actuator/prometheus

With the custom binder installed, the response may include:

1
# HELP health_status Component health: 1 for UP, 0 otherwise
2
# TYPE health_status gauge
3
health_status{component="ping"} 1.0
4
health_status{component="diskSpace"} 1.0

Database and other component series appear when their indicators are registered and supported by the binder.

Request volume and requests per second#

http_server_requests_seconds_count is a counter of recorded HTTP requests. Use rate() to calculate requests per second over a time window.

1
# Requests per second by service
2
sum by (job, svc) (rate(http_server_requests_seconds_count[5m]))
3

4
# Requests per second by route and method
5
sum by (job, svc, uri, method) (rate(http_server_requests_seconds_count[5m]))
6

7
# The ten busiest routes
8
topk(10, sum by (job, svc, uri) (rate(http_server_requests_seconds_count[5m])))

Error rates#

These queries return percentages for error rates and requests per second for the status-code breakdown.

1
# Server error rate: HTTP 5xx
2
sum by (job) (rate(http_server_requests_seconds_count{status=~"5.."}[5m]))
3
/
4
sum by (job) (rate(http_server_requests_seconds_count[5m])) * 100
5

6
# Server error rate by route
7
sum by (job, svc, uri) (rate(http_server_requests_seconds_count{status=~"5.."}[5m]))
8
/
9
sum by (job, svc, uri) (rate(http_server_requests_seconds_count[5m])) * 100
10

11
# Client error rate: HTTP 4xx
12
sum by (job) (rate(http_server_requests_seconds_count{status=~"4.."}[5m]))
13
/
14
sum by (job) (rate(http_server_requests_seconds_count[5m])) * 100
15

16
# Request rate by status code
17
sum by (job, status) (rate(http_server_requests_seconds_count[5m]))

If no matching error series exists, the error-rate query may return no result. If there is no traffic, division by zero can produce NaN. Account for these cases in dashboards and use a minimum traffic condition for percentage-based alerts.

Response time#

Count and total duration are available without histogram buckets. To calculate P50, P95, or P99 with histogram_quantile(), enable a histogram:

1
management:
2
  metrics:
3
    distribution:
4
      percentiles-histogram:
5
        http.server.requests: true

Merge this into the existing management section. Histograms increase the number of time series, especially when a metric has many label combinations.

1
# Average response time in seconds
2
sum by (job) (rate(http_server_requests_seconds_sum[5m]))
3
/
4
sum by (job) (rate(http_server_requests_seconds_count[5m]))
5

6
# Average response time by route, in milliseconds
7
sum by (job, svc, uri) (rate(http_server_requests_seconds_sum[5m]))
8
/
9
sum by (job, svc, uri) (rate(http_server_requests_seconds_count[5m])) * 1000
10

11
# Recent maximum response time for each recorded label combination
12
http_server_requests_seconds_max
13

14
# P95 response time in seconds; requires histogram buckets
15
histogram_quantile(
16
  0.95,
17
  sum by (le, job) (rate(http_server_requests_seconds_bucket[5m]))
18
)

The source also discusses http_server_requests_active_seconds_duration_sum and http_server_requests_active_seconds_active_count. Do not assume these exist in a standard Spring MVC application. They require suitable active-request instrumentation. If available, their ratio gives the mean elapsed time of requests still in progress:

1
http_server_requests_active_seconds_duration_sum
2
/
3
http_server_requests_active_seconds_active_count

The total elapsed duration of currently active requests is a gauge: it can fall when requests finish. It is not a counter of completed request duration.

As initial thresholds, consider a warning above 500 ms average latency and a critical alert above one second. Adjust these values to the service’s requirements. Compare latency with request volume to find busy, slow routes, and use percentiles to reveal delays hidden by averages.

Memory#

JVM memory metrics distinguish two areas:

• area="heap": memory for ordinary objects and arrays, managed by garbage collection and influenced by -Xms and -Xmx.
• area="nonheap": memory used for JVM facilities such as class metadata and compiled code; it is not governed by the heap’s -Xmx limit.

Pool names depend on the collector and JDK. ZGC and Shenandoah may expose different layouts, so inspect the actual id labels before writing pool-specific queries.

The source also lists jvm_memory_init_bytes. Verify its availability before using it; it is not part of every standard Micrometer export. Direct buffer memory is reported separately through metrics such as jvm_buffer_memory_used_bytes.

1
# Heap usage by pool
2
jvm_memory_used_bytes{area="heap"}
3

4
# Usage percentage for pools with a defined positive limit
5
jvm_memory_used_bytes{area="heap"}
6
/
7
(jvm_memory_max_bytes{area="heap"} > 0) * 100
8

9
# Committed heap memory and reported limits
10
jvm_memory_committed_bytes{area="heap"}
11
jvm_memory_max_bytes{area="heap"}
12

13
# Metaspace usage
14
jvm_memory_used_bytes{area="nonheap", id="Metaspace"}
15

16
# Code cache usage; adapt the pool pattern to your JVM
17
jvm_memory_used_bytes{area="nonheap", id=~"Code.*"}
18

19
# Old-generation growth in bytes per second over one hour
20
deriv(jvm_memory_used_bytes{area="heap", id=~".*Old.*|Tenured Gen"}[1h])

The percentage query is per pool, not a universal whole-heap calculation. Some collectors report undefined limits for individual pools. Validate any whole-heap ratio against the collector’s memory layout.

Sustained usage above 90% deserves attention. An old generation that keeps growing after collection may indicate a leak, while growing Metaspace may point to repeated class generation or retained class loaders. Compare used, committed, and maximum memory before changing JVM settings. A rising trend alone does not prove a leak.

Garbage collection#

The pause timer can support percentile queries when histogram buckets are enabled. The meaning and availability of GC measurements depend on the collector.

1
# Pause events per second, retaining collector and cause labels
2
rate(jvm_gc_pause_seconds_count[5m])
3

4
# Average pause duration in seconds
5
rate(jvm_gc_pause_seconds_sum[5m])
6
/
7
rate(jvm_gc_pause_seconds_count[5m])
8

9
# Major collection events over the last hour, where this label is used
10
increase(jvm_gc_pause_seconds_count{action="end of major GC"}[1h])
11

12
# Total major collection pause time over the last hour
13
increase(jvm_gc_pause_seconds_sum{action="end of major GC"}[1h])
14

15
# Minor collection events over the last hour
16
increase(jvm_gc_pause_seconds_count{action="end of minor GC"}[1h])
17

18
# Recorded GC pause time as a percentage of elapsed time, per instance
19
sum by (job, instance) (rate(jvm_gc_pause_seconds_sum[5m])) * 100
20

21
# Allocation and promotion rates, in bytes per second
22
rate(jvm_gc_memory_allocated_bytes_total[5m])
23
rate(jvm_gc_memory_promoted_bytes_total[5m])

Subtracting cumulative promoted bytes from cumulative allocated bytes does not measure memory reclaimed by a collection. Use before-and-after heap observations or GC logs for that analysis.

GC labels add context:

These are examples across JVM generations, not labels guaranteed in Spring Boot 3.5. CMS belongs to older JDKs.

The source proposes investigating more than one Full GC per hour, a Full GC pause above three seconds, or recorded pause time above 5% of elapsed time. Treat these as starting points. Frequent young collections may reflect allocation pressure; poor old-generation recovery after major collections may indicate retained objects. Tune alerts to the collector and the service’s latency requirements.

Threads#

1
# Current, peak, and daemon thread counts
2
jvm_threads_live_threads
3
jvm_threads_peak_threads
4
jvm_threads_daemon_threads
5

6
# Distribution by thread state
7
jvm_threads_states_threads
8

9
# Growth in live threads over one hour
10
deriv(jvm_threads_live_threads[1h])
11

12
# Deadlocked threads, if a binder exports this metric
13
jvm_threads_deadlocked_threads

Look for sustained thread growth and unexpected changes in state distribution. Many runnable threads can indicate CPU pressure or busy loops. Blocked threads may indicate lock contention, but waiting threads are often normal in idle pools. Use a thread dump to investigate suspected deadlocks. Thread-state label values may be lowercase with hyphens, so copy them from the exported metrics.

Class loading#

jvm_classes_loaded_classes measures the number of classes currently loaded. jvm_classes_unloaded_classes_total counts classes unloaded since startup.

1
# Currently loaded classes
2
jvm_classes_loaded_classes
3

4
# Classes unloaded per second
5
rate(jvm_classes_unloaded_classes_total[5m])

The source also uses jvm_classes_loaded_classes_total as a cumulative load counter. Do not assume that metric is exported by the standard binder. If your instrumentation provides it, query its rate:

1
rate(jvm_classes_loaded_classes_total[5m])

A sudden rise in loaded classes can accompany generated proxies, dynamic bytecode, or reloads. Compare it with Metaspace growth. A stable unload counter is normal for many applications; it suggests a class-loader leak only when classes should be unloaded but remain retained.

JIT compilation#

Just-in-time compilation converts bytecode into machine code while the application runs. It lets the JVM optimize frequently executed code using runtime information.

jvm_compilation_time_seconds_total measures cumulative compilation time when the JVM supports compilation monitoring. Spring Boot’s JVM metrics include JIT compilation instrumentation; an extra library is not inherently required. See the Spring Boot JVM metrics documentation.

Compilation metrics are especially useful when investigating warmup, dynamic code generation, or changing class-loading behavior.

CPU#

1
# Recent process CPU utilization as a percentage
2
process_cpu_usage * 100
3

4
# Recent system CPU utilization as a percentage
5
system_cpu_usage * 100
6

7
# Processor count visible to the JVM
8
system_cpu_count

Do not divide process_cpu_usage by system_cpu_count as a general normalization step. The process gauge already comes from the JVM’s CPU-load calculation. Container limits and JDK behavior affect its interpretation.

For cumulative process CPU time, inspect the exported name and unit. The source uses process_cpu_time_seconds_total, but Micrometer’s binder registers process.cpu.time with a nanosecond base unit, so an export may instead use process_cpu_time_ns_total. Apply rate() or increase() to the counter actually present and convert its units as needed. See the Micrometer processor binder.

File descriptors#

process_files_open reports open file descriptors, including sockets. process_files_max reports the allowed limit on supported platforms.

1
# File descriptor utilization
2
process_files_open / process_files_max

A rising ratio may indicate leaked files or connections. Investigate before the process reaches its limit.

Uptime and restarts#

1
# Process age in seconds
2
time() - process_start_time_seconds
3

4
# Select processes started within the last five minutes
5
time() - process_start_time_seconds < 300

The start timestamp normally lies in the past. A small process age indicates a recent start, which may be a restart, deployment, or newly added instance.

Add Druid#

The source uses this dependency version:

1
<dependency>
2
    <groupId>com.alibaba</groupId>
3
    <artifactId>druid-spring-boot-3-starter</artifactId>
4
    <version>1.2.23</version>
5
</dependency>

Register the gauges#

This version uses Spring bean names as labels so multiple unnamed data sources do not share the same metric identity.

1
import com.alibaba.druid.pool.DruidDataSource;
2
import io.micrometer.core.instrument.Gauge;
3
import io.micrometer.core.instrument.MeterRegistry;
4
import io.micrometer.core.instrument.binder.MeterBinder;
5
import org.springframework.stereotype.Component;
6

7
import javax.sql.DataSource;
8
import java.util.Map;
9

10
@Component
11
public class DruidDataSourceMeterBinder implements MeterBinder {
12
    private final Map<String, DataSource> dataSources;
13

14
    public DruidDataSourceMeterBinder(Map<String, DataSource> dataSources) {
15
        this.dataSources = dataSources;
16
    }
17

18
    @Override
19
    public void bindTo(MeterRegistry registry) {
20
        dataSources.forEach((name, dataSource) -> {
21
            if (dataSource instanceof DruidDataSource druid) {
22
                Gauge.builder("druid.connections.active", druid,
23
                                DruidDataSource::getActiveCount)
24
                        .description("Active Druid connections")
25
                        .tag("datasource", name)
26
                        .register(registry);
27

28
                Gauge.builder("druid.connections.idle", druid,
29
                                DruidDataSource::getPoolingCount)
30
                        .description("Idle Druid connections")
31
                        .tag("datasource", name)
32
                        .register(registry);
33

34
                Gauge.builder("druid.connections.pending", druid,
35
                                DruidDataSource::getWaitThreadCount)
36
                        .description("Threads waiting for a Druid connection")
37
                        .tag("datasource", name)
38
                        .register(registry);
39

40
                Gauge.builder("druid.connections.max", druid,
41
                                DruidDataSource::getMaxActive)
42
                        .description("Maximum Druid connections")
43
                        .tag("datasource", name)
44
                        .register(registry);
45

46
                Gauge.builder("druid.connections.min", druid,
47
                                DruidDataSource::getMinIdle)
48
                        .description("Minimum idle Druid connections")
49
                        .tag("datasource", name)
50
                        .register(registry);
51
            }
52
        });
53
    }
54
}

The example handles direct DruidDataSource beans. Routing data sources and wrappers may need additional handling.

All five are gauges, with a datasource label to distinguish pools.

1
# Pool utilization
2
druid_connections_active / druid_connections_max
3

4
# Ten most heavily used pools, as percentages
5
topk(10, druid_connections_active / druid_connections_max * 100)
6

7
# Threads waiting for connections
8
druid_connections_pending

Consider warning above 80% utilization and escalating above 90%, especially when pending requests also rise. Persistent saturation can result from slow queries, long transactions, leaked connections, or insufficient capacity. Increasing the pool is useful only if the database can handle the extra concurrency.