Vidocq Documentation

Dirac est l’implémentation MicroProfile Metrics 5.1.1 de l’écosystème Vidocq. Elle mesure l’état d’exécution d’une application — compteurs, jauges, histogrammes, minuteries — et l’expose en OpenMetrics / Prometheus text et JSON, sans jamais altérer l’observable par l’observation. Les annotations CDI (@Counted, @Timed, @Gauge) sont câblées via Vauban, l’endpoint optionnel GET /metrics est servi par Cassini, et la configuration mp.metrics.* est résolue via Ravel.

Origine du nom

Paul Dirac (1902-1984), physicien anglais, lauréat du prix Nobel 1933. Auteur de l’équation de Dirac (équation relativiste de l’électron, 1928), il prédit l’existence de l’antimatière par pure symétrie mathématique, et fonde avec Fermi la statistique d’occupation des fermions. Voir la fiche Wikipédia.

Dirac a posé le cadre formel qui sépare l’observable de l’instrument — son formalisme bra-ket ordonne la mesure quantique sans confondre l’état avec le geste qui le sonde. Le runtime Dirac applique la même discipline aux métriques d’application : pas de synchronized, pas de ThreadLocal, des compteurs LongAdder sans contention, et System.nanoTime() partout pour la résolution temporelle. L’instrumentation est orthogonale au code métier, jamais intrusive sur le chemin chaud.

Paul Dirac, le physicien Dirac, le runtime de métriques

Équation de Dirac — formalisme relativiste de l’électron

Modèle MP Metrics 5.1.1 — Counter, Gauge, Histogram, Timer

Prédiction de l’antimatière par symétrie

Compteurs négatifs autorisés (deltas), LongAdder non bloquant

Statistique de Fermi-Dirac — occupation discrète

Histogrammes par buckets discrets, percentiles p50–p999

Constante de Dirac (ℏ) — quantum fondamental

System.nanoTime() — résolution minimale du runtime

Notation bra-ket — observable orthogonal à l’état

Instrumentation orthogonale au code métier (intercepteurs)

Mesure quantique sans perturber l’état

Zéro synchronized, zéro ThreadLocal sur le chemin chaud

En un coup d’œil

Spec implémentée

MicroProfile Metrics 5.1.1

Dépôt

https://codeberg.org/Vidocq/dirac

Java

25 (LTS)

Modules JPMS

io.vidocq.dirac.api, io.vidocq.dirac.core, io.vidocq.dirac.cdi.vauban, io.vidocq.dirac.rest, microprofile.metrics.api (repackage)

Packages publics

io.vidocq.dirac.api. (SPI stable), io.vidocq.dirac.cdi.internal. (intégration CDI)

Dépendances runtime

microprofile-metrics-api 5.1.1, jakarta.enterprise.cdi-api 4.1, jakarta.interceptor-api 2.2, jakarta.annotation-api 3.0, jakarta.ws.rs-api 4.0 (uniquement dirac-rest)

Prête pour jlink

✅ — chaque sous-module a son module-info.java, dirac-mp-metrics-api repackage la spec MP avec un module-info.class explicite (M9)

TCK MP Metrics 5.1.1

🚧 M8 — statut à confirmer dans BENCH.md et dirac-tck/target/tck-report.txt

Trois traits identitaires

  1. Zéro librairie tierce — pas de Micrometer, pas de Dropwizard Metrics, pas de SmallRye Metrics. Seule microprofile-metrics-api est compilée dans dirac-core. Les formatters OpenMetrics et JSON sont écrits à la main avec StringBuilder.

  2. Zéro contention sur le chemin d’instrumentation — LongAdder pour les compteurs, AtomicLongArray pour les histogrammes, System.nanoTime() pour les minuteries, ConcurrentHashMap pour les registres. Aucun synchronized, aucun ThreadLocal, aucun verrou plateforme — virtual-thread-friendly par construction.

  3. JPMS strict + jlink validé (M9) — chaque artefact Dirac a son module-info.java. dirac-mp-metrics-api est un repackage local de la spec MP Metrics 5.1.1 avec module-info.class explicite, livré pour que jlink n’ait pas à traverser un module automatique sans nom canonique.

Positionnement dans l’écosystème

Diagram

Dirac consomme l’écosystème de bas en haut : Chappe sert l’endpoint, Cassini expose la ressource JAX-RS GET /metrics, Vauban orchestre les intercepteurs et la BCE DiracExtension, Ravel résout les clés mp.metrics.*. Dirac ajoute la couche d’observation — compteurs, histogrammes, formatters — sans rien réécrire ailleurs.

Ressources rapides

  • Démarrage rapide — premier compteur, premier /metrics.

  • Cas d’usage — @Counted, @Timed, @Gauge, tags, format, configuration.

  • Concepts — types de métriques, scopes, tags, formats, registres.

  • Fonctionnement interne — registre lock-free, BCE Vauban, formatters.

  • TCK — exécution, statut, runner hors reactor.

  • Référence — artefacts, annotations, clés mp.metrics.*.

  • Migration — depuis SmallRye, Micrometer ou Dropwizard.

Bugs et benchmarks consolidés : BUG.md, BENCH.md.

Suivant : Démarrage rapide.