Vidocq Documentation

Dirac est en 0.1.0-SNAPSHOT. La spec MicroProfile Metrics 5.1.1 est l’objectif (M8 — TCK 100 % PASS, statut à confirmer dans dirac-tck/target/tck-report.txt). La SPI publique peut encore évoluer avant la 1.0.0. Cette page documente les correspondances pour préparer une migration progressive.

Côté code applicatif, la migration vers Dirac est triviale : Dirac consomme strictement les annotations standard org.eclipse.microprofile.metrics.annotation.*. Aucun import propriétaire à remplacer. Les écarts portent sur la configuration, le packaging et le format d’exposition par défaut.

Depuis SmallRye Metrics

SmallRye Metrics est l’implémentation de référence chez Quarkus et certains serveurs Jakarta EE. Migration directe — Dirac vise la stricte conformance à la même spec.

SmallRye Metrics Dirac Note

Annotations org.eclipse.microprofile.metrics.annotation.*

Mêmes annotations

Aucun changement de code applicatif.

Endpoint /metrics

Endpoint /metrics

Identique. Négociation de contenu OpenMetrics/JSON identique.

mp.metrics.* (clés MP Config)

mp.metrics.* (mêmes clés)

Tags globaux, percentiles, buckets : identiques.

Dépendances : Micrometer, HdrHistogram, Jackson…

Aucune (formatters maison)

Empreinte classpath réduite. Compatibilité jlink immédiate (M9).

Format JSON via Jackson

Format JSON via StringBuilder maison

Pas de moteur JSON externe — vérifier les clients très permissifs sur l’ordre des clés.

Depuis Micrometer

Micrometer est l’API d’instrumentation par défaut de Spring Boot. La migration vers MP Metrics suppose un remplacement d’API côté application.

Micrometer Dirac (MP Metrics) Note

@Counted("metric") (io.micrometer.core.annotation)

@Counted(name = "metric") (org.eclipse.microprofile.metrics.annotation)

Changement d’import. Sémantique identique.

Counter.builder("name").tags(…​).register(registry)

registry.counter(Metadata.builder().withName("name").build(), tags)

API programmatique différente, comportement équivalent.

MeterRegistry (io.micrometer.core.instrument)

MetricRegistry (org.eclipse.microprofile.metrics)

Injection par @Inject + qualifier @RegistryScope.

Exporters par backend (Prometheus, Datadog, StatsD…)

OpenMetrics text + JSON natifs

Pour d’autres backends, brancher un scraper Prometheus → exporter de destination.

Depuis Dropwizard Metrics

Dropwizard est l’ancêtre d’une grande partie de la spec MP Metrics. Migration en deux temps : changer l’API, puis exposer.

Dropwizard Dirac (MP Metrics) Note

MetricRegistry.counter("name")

registry.counter(metadata, tags)

Notion de tags absente en Dropwizard — basculer vers les tags MP.

Timer.time(Runnable)

@Timed ou Timer.time(Runnable)

API runtime équivalente ; préférer l’annotation pour le code intercepté CDI.

Histogram.update(value)

Histogram.update(value)

Identique. Percentiles configurés via mp.metrics.distribution.percentiles.

Exposition via MetricsServlet + prometheus-dropwizard adapter

Exposition native OpenMetrics + JSON sur /metrics

Suppression de l’adapter et du servlet — l’endpoint MP Metrics suffit.

Points d’attention

  • Pas de Meter, pas de ConcurrentGauge, pas de SimpleTimer — retirés de la spec MP Metrics 5.0. Remplacer par Counter + Timer selon le cas.

  • @Histogram (annotation) — absente du JAR microprofile-metrics-api:5.1.1 utilisé par Dirac. Déclarer les histogrammes programmatiquement via MetricRegistry.histogram(…​).

  • Pas de setAccessible(true) — si du code applicatif utilisait des classes non-publiques avec un ancien scanner permissif, Dirac n’y accédera pas. Rendre les types public ou ajouter opens dans le module-info applicatif.

  • Endpoint fixé — /metrics est imposé par la spec. Pour publier sur un autre chemin, ajouter un alias JAX-RS côté application.

  • Tags globaux — mp.metrics.tags=app=orders,env=prod est appliqué à l’union des trois scopes ; pas besoin de patcher chaque appel d’enregistrement.

Checklist de portage

  1. Déclarer dirac-core + dirac-cdi-vauban + dirac-rest au lieu de SmallRye / Micrometer / Dropwizard.

  2. Remplacer les imports propriétaires (io.micrometer., com.codahale., io.smallrye.metrics.) par org.eclipse.microprofile.metrics..

  3. Migrer les propriétés propres vers les clés mp.metrics.* (Référence).

  4. Lancer ./mvnw test puis ./run-official-tck-mp-metrics-5.1.sh all.

  5. Comparer la sortie OpenMetrics avant/après — vérifier les noms canoniques, les tags globaux, les unités.

Pour aller plus loin