Monitor Spring Boot applications with Prometheus
Set up Actuator and Micrometer, expose a controlled Prometheus scrape endpoint, and measure checkout counts, in-flight work, and latency percentiles.
A checkout API starts rejecting more orders. The request counter climbs, but it includes both accepted and declined calls. To see what changed, scrape the Spring Boot HTTP metrics alongside a business counter that only increments on acceptance. Add a histogram to answer a separate question about latency.
Put the scrape endpoint on a controlled listener
This example uses Java 21, Spring Boot 3.5.16 and the Micrometer 1.15.12 version managed by Spring Boot. Save this Maven project definition as pom.xml.
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>example</groupId>
<artifactId>checkout-metrics</artifactId>
<version>1.0.0</version>
<properties><java.version>21</java.version></properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
Save the following as src/main/resources/application.properties. The example binds both listeners to loopback. The management listener exposes health and Prometheus over HTTP.
server.address=127.0.0.1
server.port=8080
management.server.address=127.0.0.1
management.server.port=9091
management.endpoints.web.exposure.include=health,prometheus
With the application code below in place, run mvn spring-boot:run. Open http://127.0.0.1:9091/actuator/prometheus from the same network namespace. The Prometheus registry gives Actuator the scrape format, and the exposure list determines which endpoints are available over HTTP. A separate management port alone gives you no authorization boundary. For a remote scraper, provide a reachable management address and restrict access to the scraper. If you define a Spring Security filter chain, apply your own Actuator access rules. Spring Boot Actuator endpoints · Management listener configuration
Read the JVM and HTTP series first
Look for jvm_memory_used_bytes by memory pool and jvm_threads_live_threads. Depending on the runtime and observed GC events, you may also see jvm_gc_pause_seconds_count and _sum. A growing heap or rising thread count is a reason to investigate. Compare similar load periods and look at retained objects or thread stacks before diagnosing a leak. Embedded Tomcat thread-pool metrics depend on enabling the Tomcat MBean registry with server.tomcat.mbeanregistry.enabled=true in Spring Boot 3.5.
Spring MVC instruments HTTP requests as http.server.requests. After a call to the route, Prometheus can see series such as http_server_requests_seconds_count and _sum. Use the matched uri template and the status tag to distinguish the two outcomes for /checkout/{orderId}. The default Timer does not automatically provide latency buckets. Check for _bucket before wiring up a percentile panel. Spring Boot metric binders and HTTP instrumentation
Measure accepted orders and checkout duration
Save this example as src/main/java/example/checkout/CheckoutApplication.java. The handler deliberately declines one order ID. It keeps a business counter, tracks work in flight, and records the time spent in the handler.
package example.checkout;
import java.time.Duration;
import java.util.concurrent.atomic.AtomicInteger;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class CheckoutApplication {
public static void main(String[] args) {
SpringApplication.run(CheckoutApplication.class, args);
}
}
@RestController
class CheckoutController {
private final MeterRegistry registry;
private final AtomicInteger inFlight = new AtomicInteger();
private final Counter accepted;
private final Timer duration;
CheckoutController(MeterRegistry registry) {
this.registry = registry;
accepted = registry.counter("checkout.accepted", "channel", "web");
Gauge.builder("checkout.in.flight", inFlight, AtomicInteger::get)
.register(registry);
duration = Timer.builder("checkout.duration")
.publishPercentileHistogram()
.serviceLevelObjectives(Duration.ofMillis(250))
.register(registry);
}
@PostMapping("/checkout/{orderId}")
ResponseEntity<Void> checkout(@PathVariable("orderId") String orderId) {
Timer.Sample sample = Timer.start(registry);
inFlight.incrementAndGet();
try {
if ("declined".equals(orderId)) {
return ResponseEntity.unprocessableEntity().build();
}
accepted.increment();
return ResponseEntity.noContent().build();
} finally {
inFlight.decrementAndGet();
sample.stop(duration);
}
}
}
Run curl -X POST http://127.0.0.1:8080/checkout/42 and curl -X POST http://127.0.0.1:8080/checkout/declined once each on a fresh instance. Then scrape the endpoint.
| Series | Change to look for | Meaning |
|---|---|---|
checkout_accepted_total |
Increases by 1 | The business accepted one order |
checkout_duration_seconds_count |
Increases by 2 | The Timer recorded both outcomes |
checkout_in_flight |
Returns to 0 once both calls finish | Work active at scrape time |
The controller holds a strong reference to the AtomicInteger because a Gauge holds a weak reference by default. A scrape can miss a short-lived spike between two samples. For counts accumulated over the interval, use the Counter or the Timer count for the corresponding question. Keep order IDs out of meter tags. The example uses a fixed channel value and the standard HTTP route template. Micrometer Gauge semantics
Scrape the histogram before querying P95
For a Prometheus process in the same network namespace, use the following job.
scrape_configs:
- job_name: spring-app
metrics_path: /actuator/prometheus
static_configs:
- targets: ["127.0.0.1:9091"]
The custom Timer enables a percentile histogram and adds a 250 ms objective bucket. Confirm that checkout_duration_seconds_bucket appears on the wire. Count and sum can give you a mean, but percentile estimation requires a distribution. Apply rate before aggregating cumulative buckets, retain le, and keep bucket boundaries consistent across instances. This query estimates P95 for the checkout handler in seconds.
histogram_quantile(
0.95,
sum by (le) (rate(checkout_duration_seconds_bucket{job="spring-app"}[5m]))
)
For an existing dashboard based on http.server.requests, enable and verify a histogram for that meter separately if you need HTTP percentiles. A client-side percentile value cannot be aggregated into a fleet-wide percentile. Micrometer histograms and percentiles · Prometheus histogram quantiles
If you collect these metrics in Guance, configure the DataKit Prom collector with the endpoint it can actually reach. Compare the raw scrape with the names, tags and units after ingestion. Then use the accepted-order count, HTTP status distribution and handler P95 together. Those signals distinguish a business rejection from a broader request-path slowdown. RED and USE methods
Contact us
Join the community
to join the community
Try Guance
Start online and pay only for what you use.
Get startedChoose a Guance plan
