Capítulo 3: Métricas con Micrometer

Introducción

Micrometer es la biblioteca de métricas de Spring Boot. Proporciona una fachada que se adapta a diferentes sistemas de monitoreo (Prometheus, Datadog, InfluxDB, etc.).

---

🎯 Objetivos del Capítulo

Al final de este capítulo, usted sabrá:

1. ✅ Comprender los tipos de métricas
2. ✅ Utilizar las métricas nativas
3. ✅ Crear métricas personalizadas
4. ✅ Añadir tags para el filtrado
5. ✅ Configurar la exportación a Prometheus

---

1. Introducción a Micrometer

Arquitectura

Su Aplicación
      ↓
  Micrometer (Fachada)
      ↓
┌─────┴─────┐
│  Registros │
├────────────┤
│ Prometheus │
│ Datadog    │
│ InfluxDB   │
│ CloudWatch │
└────────────┘

Dependencia Prometheus

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

---

2. Tipos de Métricas

Counter (Contador)

Valor que solo puede aumentar:

@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;
    }
}

Usos: Número de solicitudes, errores, eventos.

---

Gauge (Indicador)

Valor instantáneo que puede subir o bajar:

@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);
    }
}

Usos: Memoria utilizada, conexiones activas, tamaño de la cola.

---

Timer (Cronómetro)

Mide la duración y el número de llamadas:

@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(() -> {
            // El tiempo se mide automáticamente
            return executePayment(request);
        });
    }
}

Con anotación @Timed:

@Service
public class ProductService {

    @Timed(value = "product.search.time", description = "Time to search products")
    public List<Product> search(String query) {
        return productRepository.search(query);
    }
}

Activar @Timed:

@Configuration
public class MetricsConfig {

    @Bean
    public TimedAspect timedAspect(MeterRegistry registry) {
        return new TimedAspect(registry);
    }
}

---

Summary (Distribución)

Estadísticas de distribución (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)  // Mediana, P95, P99
            .register(registry);
    }

    public Order createOrder(Order order) {
        orderAmount.record(order.getTotal().doubleValue());
        return orderRepository.save(order);
    }
}

---

3. Métricas Nativas

Spring Boot expone automáticamente numerosas métricas:

Métricas JVM

# Memoria
curl http://localhost:8080/actuator/metrics/jvm.memory.used
curl http://localhost:8080/actuator/metrics/jvm.memory.max

# Hilos
curl http://localhost:8080/actuator/metrics/jvm.threads.live

# Garbage Collection
curl http://localhost:8080/actuator/metrics/jvm.gc.pause

Métricas HTTP

# Solicitudes HTTP
curl http://localhost:8080/actuator/metrics/http.server.requests

# Con filtrado por tag
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"

Métricas de Base de Datos

# 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

Lista Completa

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. Métricas Personalizadas

Con MeterRegistry

@Service
@RequiredArgsConstructor
public class UserService {

    private final MeterRegistry meterRegistry;
    private final UserRepository userRepository;

    public User register(UserRequest request) {
        User user = createUser(request);
        
        // Incrementar un counter con tags
        meterRegistry.counter("users.registered", 
            "type", request.getType(),
            "country", request.getCountry()
        ).increment();
        
        return user;
    }

    public void login(String username) {
        // Timer inline
        meterRegistry.timer("user.login.time").record(() -> {
            performLogin(username);
        });
        
        meterRegistry.counter("user.logins").increment();
    }
}

Con @Counted y @Timed

@Service
public class NotificationService {

    @Counted(value = "notifications.sent", description = "Number of notifications sent")
    public void sendNotification(Notification notification) {
        // Envío...
    }

    @Timed(value = "notifications.process.time", percentiles = {0.5, 0.95, 0.99})
    public void processNotifications() {
        // Procesamiento...
    }
}

Ejemplo Completo: Métricas de Negocio

@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 (valor dinámico)
        activeOrders = new AtomicInteger(0);
        Gauge.builder("business.orders.active", activeOrders, AtomicInteger::get)
            .description("Currently active orders")
            .register(registry);
        
        // Gauge basado en una consulta a la BD
        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 y Dimensiones

Importancia de los Tags

Los tags permiten filtrar y agrupar las métricas:

// Sin tags: un solo valor global
meterRegistry.counter("http.requests").increment();

// Con tags: filtrable por método, status, uri
meterRegistry.counter("http.requests",
    "method", "GET",
    "status", "200",
    "uri", "/api/users"
).increment();

Tags Comunes (globales)

@Configuration
public class MetricsConfig {

    @Bean
    public MeterRegistryCustomizer<MeterRegistry> commonTags() {
        return registry -> registry.config()
            .commonTags(
                "application", "my-app",
                "environment", "production",
                "region", "us-east-1"
            );
    }
}

Buenas Prácticas de Tags

// ✅ BUENO: Baja cardinalidad
meterRegistry.counter("orders", "status", "COMPLETED");  // ~5 valores posibles
meterRegistry.counter("orders", "type", "STANDARD");     // ~3 valores posibles

// ❌ MALO: Alta cardinalidad (explosión de series)
meterRegistry.counter("orders", "orderId", order.getId());  // ¡Millones de valores!
meterRegistry.counter("users", "email", user.getEmail());   // ¡Único por usuario!

---

6. Exportar a Prometheus

Configuración

# application.properties
management.endpoints.web.exposure.include=prometheus,health,metrics
management.prometheus.metrics.export.enabled=true

Formato Prometheus

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. Resumen

Tipos de Métricas

Tipo	Uso	Ejemplo
Counter	Cuenta de eventos	Solicitudes, errores
Gauge	Valor instantáneo	Memoria, conexiones activas
Timer	Duración + conteo	Tiempo de respuesta
Summary	Distribución	Percentiles

Creación de Métricas

// 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);

Anotaciones

@Timed("method.time")
@Counted("method.calls")
public void myMethod() { }

---

🎯 Próximo Paso

Las métricas son para medir. Pero ¿cómo saber si la aplicación está sana? ¡Llegó el turno de los Health Checks!

➡️ Capítulo 4: Health Checks

---

⬅️ Volver al Módulo 11