Class DmxObservation

java.lang.Object
dmx.fun.observation.DmxObservation
@NullMarked public final class DmxObservation extends Object
dmx-fun adapter for the Micrometer Observation API.

Instruments Try and Result executions automatically, opening a named Observation around each call. Depending on the handlers registered in the ObservationRegistry, a single call records both metrics (counters, timers) and distributed tracing spans — without manual bookkeeping: 

DmxObservation dmx = DmxObservation.of(observationRegistry);

Try<Response> result = dmx.observeTry("http.client.get",
    () -> httpClient.get(url)
);

Signals recorded per call

  • Observation named after the name argument.
  • outcome low-cardinality key — "success" or "failure".
  • exception low-cardinality key — classifier label of the cause (failure only).
  • Observation marked as error via Observation.error(Throwable) (failure only).

Exception key cardinality

By default the exception key uses getClass().getSimpleName(), which is unbounded when arbitrary third-party exceptions can appear — a violation of Micrometer's lowCardinalityKeyValue contract (≤ 100 distinct values). In production, supply an explicit exceptionClassifier via of(ObservationRegistry, Function): 

DmxObservation dmx = DmxObservation.of(observationRegistry, cause ->
    switch (cause) {
        case IOException _           -> "io";
        case TimeoutException _      -> "timeout";
        default                      -> "other";
    }
);

Spring Boot 3.0+ autoconfigures an ObservationRegistry with metrics and tracing handlers when both micrometer-core and a Micrometer Tracing bridge are on the classpath. When fun-spring-boot is also present, a DmxObservation bean is registered automatically — inject it directly.

For a fluent builder alternative see DmxObserved.

Requires micrometer-core ≥ 1.10 on the classpath at runtime.

  • Method Details

    • of

      public static DmxObservation of(io.micrometer.observation.ObservationRegistry registry)
      Creates an instance bound to the given ObservationRegistry.

      Warning: uses getClass().getSimpleName() as the exception key — an unsafe default in production where arbitrary exceptions may appear. Prefer of(ObservationRegistry, Function) with an explicit classifier.

      Parameters:
      registry - the registry to create observations with; must not be null
      Returns:
      a new DmxObservation bound to the given registry

    • of

      public static DmxObservation of(io.micrometer.observation.ObservationRegistry registry, Function<Throwable, String> exceptionClassifier)
      Creates an instance bound to the given ObservationRegistry and exception classifier.

      The exceptionClassifier maps each failure Throwable to the value written to the exception low-cardinality key. It must return a value from a small, bounded set (≤ 100 distinct values) to satisfy Micrometer's contract.

      Parameters:
      registry - the registry to create observations with; must not be null
      exceptionClassifier - maps a failure cause to its exception key value; must not be null, must return bounded values
      Returns:
      a new DmxObservation bound to the given registry and classifier

    • observeTry

      public <V> Try<V> observeTry(String name, CheckedSupplier<V> supplier)
      Executes supplier inside a new Observation named name.

      The observation is tagged with outcome=success on success, or outcome=failure plus exception=<classifier result> (the value returned by exceptionClassifier.apply(cause)) and marked as error on failure. The observation is always stopped before this method returns.

      Type Parameters:
      V - the value type returned on success
      Parameters:
      name - the observation name; must not be null
      supplier - the operation to execute; must not be null
      Returns:
      Success(value) on success, Failure(cause) on any exception

    • observeResult

      public <V> Result<V, Throwable> observeResult(String name, CheckedSupplier<V> supplier)
      Executes supplier inside a new Observation named name.

      Equivalent to observeTry(String, CheckedSupplier) converted to a Result.

      Type Parameters:
      V - the value type returned on success
      Parameters:
      name - the observation name; must not be null
      supplier - the operation to execute; must not be null
      Returns:
      Ok(value) on success, Err(cause) on any exception