Micrometer : Métriques JVM multi-backend

Micrometer est la façade de métriques des applications JVM : comme SLF4J unifie le logging, Micrometer unifie les métriques. Vous instrumentez une seule fois et vous exportez vers Prometheus, Datadog, InfluxDB ou OTLP, sans changer votre code.

Ce guide s'adresse aux profils intermédiaires et avancés en écosystème Java/Spring. Vous irez de votre premier endpoint /actuator/prometheus jusqu'à une configuration prête pour la production : métriques métier, tags, cardinalité, histogrammes et export OTLP.

Ce que vous allez apprendre

• Exposer un endpoint /actuator/prometheus depuis Spring Boot.
• Créer des métriques métier : Counter, Gauge, Timer.
• Maîtriser les tags et éviter l'explosion de cardinalité.
• Configurer histogrammes et percentiles pour les SLO.
• Exporter en OTLP vers un OpenTelemetry Collector.

Choisissez votre parcours

Parcours A (10 min), Spring Boot + Prometheus : Quickstart → endpoint → scrape

Parcours B (30 min), Métriques métier : A + Counter/Timer → Tags → Cardinalité

Parcours C (Production), B + Histogrammes → Filtres → ServiceMonitor K8s

Parcours D (Plateforme), C + OTLP Registry → OTel Collector → multi-backends

Pourquoi Micrometer ?

Sans façade, chaque bibliothèque de métriques lie votre code à un backend précis. Passer de Prometheus à Datadog imposerait de réécrire l'instrumentation. Micrometer casse ce couplage : votre code appelle une API neutre, et le choix du backend se règle par une simple dépendance. C'est pourquoi Spring Boot l'a adopté nativement.

Question	Réponse
C'est quoi ?	Une façade de métriques "vendor-neutral" pour la JVM
Analogie	"SLF4J des métriques", une API, plusieurs backends
Intégration	Natif dans Spring Boot depuis 2.0 (via Actuator)
Backends	Prometheus, Datadog, CloudWatch, InfluxDB, OTLP...
Frameworks	Spring Boot, Quarkus, Micronaut

Glissez pour voir

Spring Boot Actuator

Avec Spring Boot, Actuator inclut déjà Micrometer. Vous ajoutez un "registry" (Prometheus, OTLP...) et vous exposez l'endpoint, c'est tout.

Mental model : comment Micrometer s'emboîte

Micrometer n'est pas un backend, c'est une API + un Registry.

Composant	Rôle
Micrometer API	Ce que votre code appelle (Counter, Timer, Gauge)
MeterRegistry	L'implémentation qui décide où envoyer (Prometheus, OTLP...)
Binders	Métriques automatiques : JVM, HTTP, pools, caches
Actuator	Exposition des endpoints (Spring Boot)
Observation API	Instrumentation unifiée métriques + traces (Spring Boot 3)

Glissez pour voir

Pull vs Push

• Prometheus = Pull : Prometheus scrape votre /actuator/prometheus
• Datadog, OTLP = Push : Micrometer envoie les métriques périodiquement

Quickstart : Spring Boot → Prometheus (10 min)

C'est le cas d'usage le plus courant. En 3 étapes, vous avez des métriques dans Prometheus.

1. Ajoutez les dépendances

   pom.xml

   <!-- Actuator (inclut Micrometer) -->
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-actuator</artifactId>
   </dependency>
   
   <!-- Registry Prometheus -->
   <dependency>
       <groupId>io.micrometer</groupId>
       <artifactId>micrometer-registry-prometheus</artifactId>
   </dependency>

   Pas de version à spécifier

   Avec Spring Boot, le BOM gère les versions. N'ajoutez pas de <version> explicite.

2. Exposez l'endpoint Prometheus

   Par défaut, /actuator/prometheus n'est pas exposé. Ajoutez :

   application.yml

   management:
     endpoints:
       web:
         exposure:
           include: health,info,prometheus,metrics
     prometheus:
       metrics:
         export:
           enabled: true

3. Configurez le scrape Prometheus

   prometheus.yml

   scrape_configs:
     - job_name: 'spring-app'
       metrics_path: '/actuator/prometheus'
       static_configs:
         - targets: ['localhost:8080']

Vérification :

# L'endpoint doit répondre
curl http://localhost:8080/actuator/prometheus

# Vous verrez des métriques comme :
# jvm_memory_used_bytes{...}
# http_server_requests_seconds_count{...}

Créer des métriques métier

Les Binders fournissent des métriques "infra" (JVM, HTTP). Pour la logique métier, créez vos propres métriques.

Counter : événements qui s'accumulent

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;

@Service
public class OrderService {
    private final Counter orderCounter;
    private final Counter errorCounter;

    public OrderService(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.created.total")
            .description("Total orders created")
            .tag("channel", "web")
            .register(registry);

        this.errorCounter = Counter.builder("orders.errors.total")
            .description("Total order errors")
            .tag("type", "validation")
            .register(registry);
    }

    public void createOrder(Order order) {
        try {
            // ... création
            orderCounter.increment();
        } catch (ValidationException e) {
            errorCounter.increment();
            throw e;
        }
    }
}

Gauge : valeur instantanée

import io.micrometer.core.instrument.Gauge;

@Service
public class QueueService {
    private final Queue<Task> taskQueue = new ConcurrentLinkedQueue<>();

    public QueueService(MeterRegistry registry) {
        Gauge.builder("queue.size", taskQueue, Queue::size)
            .description("Current queue size")
            .tag("queue", "orders")
            .register(registry);
    }
}

Timer : durée + count

import io.micrometer.core.instrument.Timer;

@Service
public class PaymentService {
    private final Timer paymentTimer;

    public PaymentService(MeterRegistry registry) {
        this.paymentTimer = Timer.builder("payment.duration")
            .description("Payment processing time")
            .publishPercentiles(0.5, 0.95, 0.99)  // p50, p95, p99
            .register(registry);
    }

    public PaymentResult processPayment(Payment payment) {
        return paymentTimer.record(() -> {
            // ... traitement
            return new PaymentResult();
        });
    }
}

Annotation @Timed

import io.micrometer.core.annotation.Timed;

@Service
public class UserService {

    @Timed(value = "user.create.duration",
           description = "Time to create a user",
           percentiles = {0.5, 0.95, 0.99})
    public User createUser(CreateUserRequest request) {
        // ...
    }
}

Configuration requise pour @Timed

@Timed nécessite un bean TimedAspect :

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

Tags : les dimensions de vos métriques

Les tags permettent de filtrer et grouper. Mais attention à la cardinalité.

Tags statiques vs dynamiques

// Tags statiques (à la création)
Counter.builder("http.requests.total")
    .tag("application", "order-service")
    .tag("environment", "production")
    .register(registry);

// Tags dynamiques (à l'appel)
public void recordRequest(String method, String route, int status) {
    registry.counter("http.requests.total",
        "method", method,           // GET, POST, PUT...
        "route", route,             // /api/orders/{id}
        "status", String.valueOf(status / 100) + "xx"  // 2xx, 4xx, 5xx
    ).increment();
}

Tags communs (global)

@Bean
public MeterRegistryCustomizer<MeterRegistry> commonTags() {
    return registry -> registry.config()
        .commonTags("application", "order-service")
        .commonTags("environment", "production");
}

Anti-pattern : haute cardinalité

❌ Mauvais	✅ Correct	Pourquoi
tag("user_id", userId)	tag("user_tier", "premium")	user_id = millions de valeurs
tag("request_id", reqId)	(pas de tag)	Chaque requête = nouvelle série
tag("path", "/api/orders/123")	tag("route", "/api/orders/{id}")	Path avec ID = cardinalité infinie

Glissez pour voir

Cardinalité = coût

Chaque combinaison unique de tags crée une série temporelle. Si user_id a 1M de valeurs et method en a 4 → 4M de séries → OOM côté Prometheus.

Histogrammes et percentiles

Quand les activer ?

Besoin	Configuration
Distribution de latence (p50, p95, p99)	publishPercentiles(0.5, 0.95, 0.99)
SLO buckets (< 100ms, < 500ms, < 1s)	serviceLevelObjectives(100, 500, 1000)
Agrégation serveur-side (Prometheus)	publishPercentileHistogram()

Glissez pour voir

Timer.builder("http.server.requests")
    .publishPercentiles(0.5, 0.95, 0.99)       // Client-side percentiles
    .publishPercentileHistogram()              // Histogram pour agrégation
    .serviceLevelObjectives(                   // SLO buckets
        Duration.ofMillis(100),
        Duration.ofMillis(500),
        Duration.ofSeconds(1)
    )
    .register(registry);

Client-side vs Server-side percentiles

• publishPercentiles() : calculés côté app, précis mais non agrégeables entre instances
• publishPercentileHistogram() : buckets exportés, Prometheus agrège (moins précis mais valide pour un cluster)

Recommandation : activez les deux pour avoir le choix.

Impact sur le nombre de séries

Configuration	Séries générées
Counter simple	1
Timer avec 3 percentiles	~4 (count, sum, p50, p95, p99)
Timer avec histogram (14 buckets)	~17
Tout × 5 tags × 4 valeurs chacun	× 1024

Glissez pour voir

Filtrage des métriques

Activer/désactiver par préfixe

application.yml

management:
  metrics:
    enable:
      jvm: true
      process: true
      http: true
      logback: false   # Désactiver
      tomcat: false    # Désactiver

MeterFilter (programmatique)

@Bean
public MeterFilter customFilter() {
    return new MeterFilter() {
        @Override
        public MeterFilterReply accept(Meter.Id id) {
            // Exclure les métriques internes
            if (id.getName().startsWith("jvm.gc.")) {
                return MeterFilterReply.DENY;
            }
            return MeterFilterReply.NEUTRAL;
        }
    };
}

Kubernetes : ServiceMonitor

Pour que Prometheus Operator scrape automatiquement vos pods :

servicemonitor.yaml

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: order-service
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: order-service
  namespaceSelector:
    matchNames:
      - production
  endpoints:
    - port: http
      path: /actuator/prometheus
      interval: 30s

OTLP Registry : Micrometer → OTel Collector

Si vous standardisez sur OTLP (plateforme OTel), Micrometer peut exporter directement vers le Collector.

pom.xml

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

application.yml

management:
  otlp:
    metrics:
      export:
        enabled: true
        url: http://otel-collector:4318/v1/metrics
        step: 1m

Architecture résultante :

App (Micrometer) → OTLP → OTel Collector → Prometheus/Mimir/Datadog...

Pourquoi OTLP ?

• Découplage : votre app ne connaît qu'un endpoint
• Flexibilité : changez de backend dans le Collector, pas dans l'app
• Unification : métriques, traces et logs passent par le même Collector

Spring Boot 3 : Observation API + Tracing

Spring Boot 3 introduit l'Observation API : vous instrumentez une fois, vous obtenez métriques + traces.

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

@Service
public class OrderService {
    private final ObservationRegistry observationRegistry;

    public Order processOrder(OrderRequest request) {
        return Observation.createNotStarted("order.process", observationRegistry)
            .lowCardinalityKeyValue("channel", "web")
            .observe(() -> {
                // Ce code est tracé ET mesuré
                return doProcessOrder(request);
            });
    }
}

Activer le tracing

pom.xml

<!-- Bridge vers OpenTelemetry -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

application.yml

management:
  tracing:
    sampling:
      probability: 0.1   # 10% en prod
  otlp:
    tracing:
      endpoint: http://otel-collector:4318/v1/traces

Micrometer Tracing = façade de tracing

Comme Micrometer Metrics unifie les backends métriques, Micrometer Tracing unifie les backends tracing (OpenTelemetry, Brave/Zipkin).

Anti-patterns

Anti-pattern	Conséquence	Solution
Tags à haute cardinalité	OOM, coûts explosifs	Utiliser des catégories (tier, status_class)
Pas de tags communs	Répétition, inconsistance	MeterRegistryCustomizer
Histogrammes partout	Explosion de séries	Activer uniquement sur les métriques RED
Percentiles sans histogram	Non agrégeables en cluster	Activer publishPercentileHistogram()
Versions explicites avec Spring	Conflits de versions	Laisser le BOM gérer

Glissez pour voir

Dépannage

Checklist "je ne vois pas mes métriques"

1. L'endpoint répond-il ?

   curl http://localhost:8080/actuator/prometheus
   # 404 → endpoint non exposé

2. L'endpoint est-il exposé ?

   management.endpoints.web.exposure.include: prometheus

3. Le registry est-il présent ?

   Vérifiez la dépendance micrometer-registry-prometheus.

4. Les métriques sont-elles créées ?

   curl http://localhost:8080/actuator/metrics
   # Liste toutes les métriques disponibles

5. Prometheus scrape-t-il ?

   Vérifiez http://prometheus:9090/targets.

Erreurs courantes

Symptôme	Cause probable	Solution
/actuator/prometheus 404	Endpoint non exposé	Ajouter à exposure.include
Métrique absente	Counter jamais incrémenté	Vérifier que le code est appelé
OOM côté Prometheus	Haute cardinalité	Auditer les tags
@Timed sans effet	TimedAspect absent	Ajouter le bean
Versions incompatibles	Version explicite	Utiliser le BOM Spring Boot

Glissez pour voir

FAQ : questions fréquentes

Qu'est-ce que Micrometer ?

Micrometer est une façade de métriques pour les applications JVM. Comme SLF4J unifie le logging, il unifie les métriques : on instrumente une fois et on exporte vers Prometheus, Datadog, InfluxDB ou OTLP sans changer le code.

Micrometer ou Prometheus, quelle différence ?

Micrometer produit les métriques dans l'application ; Prometheus les stocke et les interroge. Micrometer expose un endpoint /actuator/prometheus que Prometheus vient scraper. Ils sont complémentaires, pas concurrents.

Comment exposer les métriques Micrometer à Prometheus ?

Ajoutez la dépendance micrometer-registry-prometheus et Spring Boot Actuator, puis exposez l'endpoint via management.endpoints.web.exposure.include=prometheus. Prometheus scrape alors /actuator/prometheus.

Micrometer gère-t-il le tracing ?

Oui, via Micrometer Tracing, une façade de tracing distincte des métriques. Couplée à l'Observation API de Spring Boot 3, une seule instrumentation produit à la fois des métriques et des traces, exportées en OTLP.

À retenir

• Micrometer = SLF4J des métriques, une API, plusieurs backends
• Spring Boot Actuator inclut Micrometer, ajoutez juste le registry (Prometheus, OTLP...)
• Exposez l'endpoint, par défaut /actuator/prometheus n'est pas accessible
• Cardinalité = coût, jamais d'IDs uniques en tags
• OTLP Registry pour unifier avec OTel Collector
• Observation API (Spring Boot 3) = métriques + traces en une instrumentation

Prochaines étapes

OpenTelemetry Standard d'instrumentation multi-langage : traces, métriques, logs.

OpenTelemetry Collector Recevoir, transformer et router la télémétrie vers vos backends.

Prometheus Backend de métriques : stockage, requêtes PromQL, alerting.

Ressources

• Documentation officielle Micrometer
• Spring Boot Actuator Metrics
• Spring Boot Tracing
• Micrometer OTLP Registry
• GitHub Releases

×

📖 Voir la documentation →