Vidocq Documentation

Dirac is the MicroProfile Metrics 5.1.1 implementation of the Vidocq ecosystem. It measures the runtime state of an application — counters, gauges, histograms, timers — and exposes it as OpenMetrics / Prometheus text and JSON, without ever altering the observable through observation. CDI annotations (@Counted, @Timed, @Gauge) are wired through Vauban, the optional GET /metrics endpoint is served by Cassini, and mp.metrics.* configuration is resolved through Ravel.

Origin of the name

Paul Dirac (1902-1984), English physicist, Nobel Prize 1933. Author of the Dirac equation (the relativistic equation of the electron, 1928), he predicted the existence of antimatter through pure mathematical symmetry and laid, with Fermi, the statistics of fermion occupation. See the Wikipedia article.

Dirac built the formal frame that separates the observable from the instrument — his bra-ket notation orders quantum measurement without confusing the state with the gesture that probes it. The Dirac runtime applies the same discipline to application metrics: no synchronized, no ThreadLocal, LongAdder-backed counters with no contention, and System.nanoTime() everywhere for time resolution. Instrumentation stays orthogonal to business code, never intrusive on the hot path.

Paul Dirac, the physicist Dirac, the metrics runtime

Dirac equation — relativistic formalism of the electron

MP Metrics 5.1.1 model — Counter, Gauge, Histogram, Timer

Predicting antimatter by symmetry

Negative counters allowed (deltas), non-blocking LongAdder

Fermi-Dirac statistics — discrete occupation

Discrete-bucket histograms, p50–p999 percentiles

Dirac constant (ℏ) — fundamental quantum

System.nanoTime() — minimal runtime resolution

Bra-ket notation — observable orthogonal to state

Instrumentation orthogonal to business code (interceptors)

Quantum measurement without disturbing the state

Zero synchronized, zero ThreadLocal on the hot path

At a glance

Implemented spec

MicroProfile Metrics 5.1.1

Repo

https://codeberg.org/Vidocq/dirac

Java

25 (LTS)

JPMS modules

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

Public packages

io.vidocq.dirac.api. (stable SPI), io.vidocq.dirac.cdi.internal. (CDI integration)

Runtime dependencies

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 (only dirac-rest)

jlink-ready

✅ — every sub-module ships its own module-info.java, dirac-mp-metrics-api repackages the MP spec with an explicit module-info.class (M9)

MP Metrics 5.1.1 TCK

🚧 M8 — status to be confirmed in BENCH.md and dirac-tck/target/tck-report.txt

Three identifying traits

  1. Zero third-party library — no Micrometer, no Dropwizard Metrics, no SmallRye Metrics. Only microprofile-metrics-api is compiled into dirac-core. The OpenMetrics and JSON formatters are hand-written with StringBuilder.

  2. Zero contention on the instrumentation path — LongAdder for counters, AtomicLongArray for histograms, System.nanoTime() for timers, ConcurrentHashMap for registries. No synchronized, no ThreadLocal, no platform locks — virtual-thread-friendly by construction.

  3. Strict JPMS + validated jlink (M9) — every Dirac artefact has its own module-info.java. dirac-mp-metrics-api is a local repackage of MP Metrics 5.1.1 with an explicit module-info.class, shipped so that jlink does not have to cross an automatic module without a canonical name.

Position in the ecosystem

Diagram

Dirac consumes the ecosystem bottom-up: Chappe serves the endpoint, Cassini exposes the JAX-RS resource GET /metrics, Vauban orchestrates the interceptors and the DiracExtension BCE, Ravel resolves mp.metrics.* keys. Dirac adds the observation layer — counters, histograms, formatters — without rewriting anything else.

  • Getting started — first counter, first /metrics.

  • Usage patterns — @Counted, @Timed, @Gauge, tags, format, configuration.

  • Concepts — metric types, scopes, tags, formats, registries.

  • Internals — lock-free registry, Vauban BCE, formatters.

  • TCK — execution, status, out-of-reactor runner.

  • Reference — artefacts, annotations, mp.metrics.* keys.

  • Migration — from SmallRye, Micrometer or Dropwizard.

Consolidated bugs and benchmarks: BUG.md, BENCH.md.

Next: Getting started.