Vidocq Documentation

Cette page consolide la surface publique de Dirac : artefacts à déclarer, modules JPMS exportés, annotations MicroProfile Metrics 5.1.1 supportées, et clés mp.metrics.* reconnues par l’implémentation.

Artefacts Maven

groupId artifactId Rôle

io.vidocq.dirac

dirac-mp-metrics-api

Repackage local de microprofile-metrics-api:5.1.1 avec un module-info.class explicite. Levée du blocker jlink (M9).

io.vidocq.dirac

dirac-api

Re-exposition de la spec MP Metrics et SPI publique Dirac (DiracException, HistogramSnapshot, TimerSnapshot).

io.vidocq.dirac

dirac-core

Implémentations Java pures : CounterImpl, GaugeImpl, HistogramImpl, TimerImpl, MetricRegistryImpl, BaseMetricsRegistrar, OpenMetricsFormatter, JsonMetricsFormatter. Aucune dépendance CDI.

io.vidocq.dirac

dirac-cdi-vauban

Intercepteurs CDI (CountedInterceptor, TimedInterceptor), BCE DiracExtension, producer MetricRegistryProducerBean.

io.vidocq.dirac

dirac-rest

Ressource JAX-RS MetricsEndpoint exposant GET /metrics. Optionnel — activé seulement si Cassini est sur le classpath.

io.vidocq.dirac

dirac-bench

Benchmarks JMH vs Micrometer / SmallRye Metrics. Hors production.

io.vidocq.dirac

dirac-examples

Exemples standalone et intégrés vidocq-mps. Hors production.

io.vidocq.dirac

dirac-tck

Runner officiel TCK MP Metrics 5.1.1 — hors reactor (Model 4.0.0). Ne pas déclarer en dépendance applicative.

Toutes les versions à 0.1.0-SNAPSHOT au moment de la rédaction.

Modules JPMS

Module Contenu

microprofile.metrics.api

Repackage MP Metrics 5.1.1 avec module-info.class explicite. Exporte org.eclipse.microprofile.metrics et org.eclipse.microprofile.metrics.annotation.

io.vidocq.dirac.api

io.vidocq.dirac.api.* — SPI publique stable. requires transitive microprofile.metrics.api.

io.vidocq.dirac.core

io.vidocq.dirac.internal.* — implémentations privées, exportées uniquement vers io.vidocq.dirac.cdi.vauban et io.vidocq.dirac.rest.

io.vidocq.dirac.cdi.vauban

io.vidocq.dirac.cdi.internal.* — intercepteurs et BCE. provides BuildCompatibleExtension with DiracExtension.

io.vidocq.dirac.rest

io.vidocq.dirac.rest.* — ressource JAX-RS. opens vers jakarta.cdi et jakarta.ws.rs pour introspection runtime.

io.vidocq.dirac.internal.* n’est jamais exporté à du code applicatif : toute dépendance directe signale une régression.

Annotations MicroProfile Metrics supportées

Annotation Effet Statut

@Counted

Intercepteur incrémente un Counter (LongAdder) à chaque invocation. Supporte name, absolute, description, unit, tags, scope.

✅

@Timed

Intercepteur mesure la durée via System.nanoTime() et alimente un Timer (HistogramImpl interne). Supporte les mêmes attributs que @Counted.

✅

@Gauge

Résolu une fois par DiracExtension au démarrage via MethodHandle. Méthode obligatoire à retour numérique (int, long, double, Number).

✅

@RegistryScope

Qualifier d’injection pour distinguer les trois MetricRegistry (APPLICATION, BASE, VENDOR). Sans qualifier → registre APPLICATION.

✅

@Metric

Métadonnées additionnelles sur un point d’injection (nom, description, unité, tags).

✅

@Histogram

Annotation absente du JAR microprofile-metrics-api:5.1.1 utilisé — les histogrammes se déclarent programmatiquement.

⚠️ Non exposé par l’API

Clés MicroProfile Config

Toutes les clés sont lues via ConfigProvider.getConfig() (Ravel). Voir DistributionConfig et MetricRegistryImpl.

Clé Effet

mp.metrics.appName

Nom logique de l’application — émis comme tag _app global.

mp.metrics.tags

Tags globaux, format cle=val,cle=val. Appliqués à toutes les métriques de l’application.

mp.metrics.distribution.percentiles

Liste de percentiles globaux (0.5,0.95,0.99) ou par métrique (nom=0.5,0.99). Une valeur vide désactive les percentiles.

mp.metrics.distribution.histogram.buckets

Buckets fixes pour les Histogram. Globale ou par métrique.

mp.metrics.distribution.timer.buckets

Buckets fixes pour les Timer, exprimés en ms, s, ns, etc. Globale ou par métrique.

mp.metrics.smallrye.timer.minmax.histogram.buckets.percentiles

Compat éventuelle (clé non standard) — vérifier DistributionConfig.

La spec MP Metrics 5.1 ne définit pas d’option de chemin (équivalent quarkus.smallrye-metrics.path). L’endpoint /metrics est fixé par la spec §2.3.

Types MetricUnits

org.eclipse.microprofile.metrics.MetricUnits énumère les unités canoniques :

  • Durées — NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS

  • Tailles — BITS, KILOBITS, MEGABITS, BYTES, KILOBYTES, MEGABYTES, GIGABYTES

  • Génériques — NONE, PERCENT, PER_SECOND

Dirac n’effectue pas de conversion automatique : l’unité est exposée telle que déclarée. Convention Prometheus : exprimer les durées en SECONDS, les tailles en BYTES.

Endpoint GET /metrics

Route

GET /metrics, GET /metrics/{scope}, GET /metrics/{scope}/{name}

Verbes

GET, OPTIONS

Types

text/plain;version=0.0.4 (défaut, OpenMetrics), application/json (MP Metrics §3.2)

Source

MetricRegistryImpl (les trois scopes)

Statut

200 succès, 404 scope/métrique inconnu

Implémentation

MetricsEndpoint dans dirac-rest

MetricRegistry injectable

@Inject
MetricRegistry application;                                          // APPLICATION

@Inject @RegistryScope(scope = MetricRegistry.BASE_SCOPE)
MetricRegistry base;

@Inject @RegistryScope(scope = MetricRegistry.VENDOR_SCOPE)
MetricRegistry vendor;

Compatibilité

  • Java 25 (LTS), Maven 3.9.16.

  • CDI 4.1 Lite (Vauban) ou Lite-compatible — l'`Interceptor` standard et la BuildCompatibleExtension suffisent.

  • JAX-RS 4.0 (Cassini) — uniquement si dirac-rest est utilisé.

  • MicroProfile Config 3.1 (Ravel) — fortement recommandé pour mp.metrics.tags et mp.metrics.distribution.*.

  • Pas de dépendance Jakarta EE Full Profile.

Bugs et benchmarks

  • BUG.md — bugs reproductibles tracés.

  • BENCH.md — benchmarks JMH (vs Micrometer / SmallRye).

Pour aller plus loin