Chapter 3: Metrics with Micrometer
Introduction
Micrometer is the metrics library for Spring Boot. It provides a facade that adapts to different monitoring systems (Prometheus, Datadog, InfluxDB, etc.).
🎯 Chapter Objectives
By the end of this chapter, you will know how to:
- ✅ Understand the types of metrics
- ✅ Use native metrics
- ✅ Create custom metrics
- ✅ Add tags for filtering
- ✅ Configure export to Prometheus
1. Introduction to Micrometer
Architecture
Your Application
↓
Micrometer (Facade)
↓
┌─────┴─────┐
│ Registries │
├────────────┤
│ Prometheus │
│ Datadog │
│ InfluxDB │
│ CloudWatch │
└────────────┘
Prometheus Dependency
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
2. Types of Metrics
Counter
Value that only increases:
@Service
@RequiredArgsConstructor
public class OrderService {
private final Counter ordersCreated;
public OrderService(MeterRegistry registry) {
this.ordersCreated = Counter.builder("orders.created")
.description("Number of orders created")
.register(registry);
}
public Order createOrder(OrderRequest request) {
Order order = processOrder(request);
ordersCreated.increment(); // +1
return order;
}
}
Usages: Number of requests, errors, events.
Gauge
Instantaneous value that can go up or down:
@Component
public class QueueMetrics {
private final Queue<Task> taskQueue;
public QueueMetrics(MeterRegistry registry, Queue<Task> taskQueue) {
this.taskQueue = taskQueue;
Gauge.builder("tasks.queue.size", taskQueue, Queue::size)
.description("Current number of tasks in queue")
.register(registry);
}
}
Usages: Memory used, active connections, queue size.
Timer
Measures duration and number of calls:
@Service
public class PaymentService {
private final Timer paymentTimer;
public PaymentService(MeterRegistry registry) {
this.paymentTimer = Timer.builder("payment.process.time")
.description("Time to process payments")
.register(registry);
}
public Payment process(PaymentRequest request) {
return paymentTimer.record(() -> {
// Time is measured automatically
return executePayment(request);
});
}
}
With @Timed annotation:
@Service
public class ProductService {
@Timed(value = "product.search.time", description = "Time to search products")
public List<Product> search(String query) {
return productRepository.search(query);
}
}
Enable @Timed:
@Configuration
public class MetricsConfig {
@Bean
public TimedAspect timedAspect(MeterRegistry registry) {
return new TimedAspect(registry);
}
}
Summary
Distribution statistics (percentiles):
@Service
public class OrderService {
private final DistributionSummary orderAmount;
public OrderService(MeterRegistry registry) {
this.orderAmount = DistributionSummary.builder("order.amount")
.description("Order amounts")
.baseUnit("dollars")
.publishPercentiles(0.5, 0.95, 0.99) // Median, P95, P99
.register(registry);
}
public Order createOrder(Order order) {
orderAmount.record(order.getTotal().doubleValue());
return orderRepository.save(order);
}
}
3. Native Metrics
Spring Boot automatically exposes many metrics:
JVM Metrics
# Memory
curl http://localhost:8080/actuator/metrics/jvm.memory.used
curl http://localhost:8080/actuator/metrics/jvm.memory.max
# Threads
curl http://localhost:8080/actuator/metrics/jvm.threads.live
# Garbage Collection
curl http://localhost:8080/actuator/metrics/jvm.gc.pause
HTTP Metrics
# HTTP Requests
curl http://localhost:8080/actuator/metrics/http.server.requests
# With tag filtering
curl "http://localhost:8080/actuator/metrics/http.server.requests?tag=uri:/api/users"
curl "http://localhost:8080/actuator/metrics/http.server.requests?tag=status:200"
Database Metrics
# HikariCP
curl http://localhost:8080/actuator/metrics/hikaricp.connections.active
curl http://localhost:8080/actuator/metrics/hikaricp.connections.idle
curl http://localhost:8080/actuator/metrics/hikaricp.connections.pending
Complete List
curl http://localhost:8080/actuator/metrics
{
"names": [
"jvm.memory.used",
"jvm.memory.max",
"jvm.threads.live",
"jvm.gc.pause",
"http.server.requests",
"hikaricp.connections.active",
"logback.events",
"process.cpu.usage",
"system.cpu.usage"
]
}
4. Custom Metrics
With MeterRegistry
@Service
@RequiredArgsConstructor
public class UserService {
private final MeterRegistry meterRegistry;
private final UserRepository userRepository;
public User register(UserRequest request) {
User user = createUser(request);
// Increment a counter with tags
meterRegistry.counter("users.registered",
"type", request.getType(),
"country", request.getCountry()
).increment();
return user;
}
public void login(String username) {
// Inline timer
meterRegistry.timer("user.login.time").record(() -> {
performLogin(username);
});
meterRegistry.counter("user.logins").increment();
}
}
With @Counted and @Timed
@Service
public class NotificationService {
@Counted(value = "notifications.sent", description = "Number of notifications sent")
public void sendNotification(Notification notification) {
// Sending...
}
@Timed(value = "notifications.process.time", percentiles = {0.5, 0.95, 0.99})
public void processNotifications() {
// Processing...
}
}
Complete Example: Business Metrics
@Component
@RequiredArgsConstructor
public class BusinessMetrics {
private final MeterRegistry registry;
private final OrderRepository orderRepository;
private Counter ordersCreated;
private Counter ordersFailed;
private Timer orderProcessingTime;
private AtomicInteger activeOrders;
@PostConstruct
public void init() {
// Counters
ordersCreated = Counter.builder("business.orders.created")
.description("Total orders created")
.register(registry);
ordersFailed = Counter.builder("business.orders.failed")
.description("Total orders failed")
.register(registry);
// Timer
orderProcessingTime = Timer.builder("business.orders.processing.time")
.description("Order processing time")
.publishPercentiles(0.5, 0.95, 0.99)
.register(registry);
// Gauge (dynamic value)
activeOrders = new AtomicInteger(0);
Gauge.builder("business.orders.active", activeOrders, AtomicInteger::get)
.description("Currently active orders")
.register(registry);
// Gauge based on a DB query
Gauge.builder("business.orders.pending", orderRepository,
repo -> repo.countByStatus(OrderStatus.PENDING))
.description("Pending orders in database")
.register(registry);
}
public void recordOrderCreated(String type) {
ordersCreated.increment();
registry.counter("business.orders.created.by.type", "type", type).increment();
}
public void recordOrderFailed(String reason) {
ordersFailed.increment();
registry.counter("business.orders.failed.by.reason", "reason", reason).increment();
}
public void recordProcessingTime(Runnable operation) {
orderProcessingTime.record(operation);
}
public void incrementActiveOrders() {
activeOrders.incrementAndGet();
}
public void decrementActiveOrders() {
activeOrders.decrementAndGet();
}
}
5. Tags and Dimensions
Importance of Tags
Tags allow filtering and grouping of metrics:
// Without tags: a single global value
meterRegistry.counter("http.requests").increment();
// With tags: filterable by method, status, uri
meterRegistry.counter("http.requests",
"method", "GET",
"status", "200",
"uri", "/api/users"
).increment();
Common (global) Tags
@Configuration
public class MetricsConfig {
@Bean
public MeterRegistryCustomizer<MeterRegistry> commonTags() {
return registry -> registry.config()
.commonTags(
"application", "my-app",
"environment", "production",
"region", "us-east-1"
);
}
}
Best Practices for Tags
// ✅ GOOD: Low cardinality
meterRegistry.counter("orders", "status", "COMPLETED"); // ~5 possible values
meterRegistry.counter("orders", "type", "STANDARD"); // ~3 possible values
// ❌ BAD: High cardinality (series explosion)
meterRegistry.counter("orders", "orderId", order.getId()); // Millions of values!
meterRegistry.counter("users", "email", user.getEmail()); // Unique per user!
6. Export to Prometheus
Configuration
# application.properties
management.endpoints.web.exposure.include=prometheus,health,metrics
management.prometheus.metrics.export.enabled=true
Prometheus Format
curl http://localhost:8080/actuator/prometheus
# HELP jvm_memory_used_bytes The amount of used memory
# TYPE jvm_memory_used_bytes gauge
jvm_memory_used_bytes{area="heap",id="G1 Eden Space",} 1.048576E7
jvm_memory_used_bytes{area="heap",id="G1 Old Gen",} 2.097152E7
# HELP http_server_requests_seconds
# TYPE http_server_requests_seconds summary
http_server_requests_seconds_count{method="GET",status="200",uri="/api/users",} 150.0
http_server_requests_seconds_sum{method="GET",status="200",uri="/api/users",} 12.5
# HELP orders_created_total Number of orders created
# TYPE orders_created_total counter
orders_created_total{type="STANDARD",} 1523.0
orders_created_total{type="EXPRESS",} 342.0
7. Summary
Types of Metrics
| Type | Usage | Example |
|---|---|---|
| Counter | Counts events | Requests, errors |
| Gauge | Instantaneous value | Memory, active connections |
| Timer | Duration + count | Response time |
| Summary | Distribution | Percentiles |
Creating Metrics
// Counter
meterRegistry.counter("my.counter", "tag", "value").increment();
// Timer
meterRegistry.timer("my.timer").record(() -> operation());
// Gauge
Gauge.builder("my.gauge", obj, Object::getValue).register(registry);
Annotations
@Timed("method.time")
@Counted("method.calls")
public void myMethod() { }
🎯 Next Step
Metrics are for measuring. But how to know if the application is healthy? On to Health Checks!