Package org.apache.juneau.rest.server.observation

Class Observations

java.lang.Object
org.apache.juneau.rest.server.observation.Observations
public class Observations extends Object
Static facade over an explicitly-installed default Observer for ergonomic custom (non-request) observations.

juneau-rest-server has no method-interception / AOP substrate, so custom observations are explicit: wrap the block of work in a try-with-resources over observe(String, String). This mirrors how the request path is instrumented (the framework opens / closes the observation around the @RestOp handler) but lets application code instrument arbitrary work.

Installing a backend

The default observer is Observer.NOOP until a backend is installed via install(Observer) — typically once at startup, after the application's MetricsRecorder / TracerHook beans are known. Until then (and in any process that never installs one) observe(String, String) hands back Observation.NOOP and costs nothing.

// At startup, once the observability beans are built: Observations.install(new Observer(metricsRecorder, tracerHook)); // Anywhere in application code: try (Observation o = Observations.observe("order.load", "team=payments")) { return loadOrder(id); } catch (RuntimeException e) { o.setError(e); throw e; }

Code that prefers explicit dependency injection over a global can hold an Observer directly (resolved from the RestContext bean store) and call Observer.start(String, String) — this facade is a convenience, not the only entry point.

See Also:
Since:
10.0.0

  • Method Details

    • install

      public static void install(Observer observer)
      Installs the process-wide default Observer used by observe(String, String).

      Intended to be called once at application startup. Passing Observer.NOOP (or calling reset()) restores the no-op default.

      Parameters:
      observer - The observer to install. Must not be null.

    • reset

      public static void reset()
      Resets the process-wide default observer back to Observer.NOOP.

    • observer

      public static Observer observer()
      Returns the currently-installed default Observer.
      Returns:
      The default observer; Observer.NOOP if none was installed. Never null.

    • observe

      public static Observation observe(String name, String tags)
      Starts a custom observation against the installed default Observer.
      Parameters:
      name - The observation name — used as both the span name and the metric timer name. Must not be null or blank.
      tags - Additional metric tags as comma-separated key=value pairs, or null / empty for none.
      Returns:
      The started Observation (a try-with-resources handle). Never null.

    • observe

      public static Observation observe(String name)
      Starts a custom observation with no additional tags.
      Parameters:
      name - The observation name. Must not be null or blank.
      Returns:
      The started Observation. Never null.