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

Interface Observation

All Superinterfaces:
AutoCloseable
public interface Observation extends AutoCloseable
Handle to one in-flight custom (non-request) observation.

Returned by Observer.start(String, String) and by the Observations facade. An observation pairs a metric timer with a tracing span around an arbitrary block of work that has no associated HTTP request — the request-path equivalent is the framework-driven boundary in RestOpInvoker.

Usage

The handle is AutoCloseable and is designed for try-with-resources. On close() it records the elapsed time to the metrics recorder and ends the span. Mark a failure with setError(Throwable) before the block exits so both the timer's exception tag and the span's error status reflect it:

try (Observation o = Observations.observe("order.load", "team=payments")) { return loadOrder(id); } catch (RuntimeException e) { o.setError(e); throw e; }

No-backend contract

When no metrics recorder / tracer is installed, Observations hands back NOOP — a process-wide singleton whose methods do nothing and whose timing is never taken, so an observation in an unconfigured process costs nothing beyond the try-with-resources scaffolding.

Since:
10.0.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Observation
    NOOP
    Process-wide no-op observation, returned whenever no backend is installed.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the observation — records the elapsed timer sample and ends the span.
    void
    setError(Throwable error)
    Marks the observed block as failed.

  • Field Details

    • NOOP

      static final Observation NOOP
      Process-wide no-op observation, returned whenever no backend is installed.

      Drops the error on the floor and does nothing on close.

  • Method Details

    • setError

      void setError(Throwable error)
      Marks the observed block as failed.

      The throwable is surfaced as the metric timer's exception tag and recorded on the tracing span (status ERROR + exception.type attribute) when the observation closes. Safe to call at most once; a null argument is treated as "no error".

      Parameters:
      error - The exception that caused the block to fail. May be null (treated as success).

    • close

      void close()
      Closes the observation — records the elapsed timer sample and ends the span.

      Always called via the try-with-resources finally contract. Implementations must not throw.

      Specified by:
      close in interface AutoCloseable