Package io.micrometer.observation

Interface Observation

All Superinterfaces:
ObservationView
All Known Implementing Classes:
NullObservation
public interface Observation extends ObservationView
An act of viewing or noticing a fact or an occurrence for some scientific or other special purpose (According to dictionary.com). You can wrap an operation within your code in an Observation so that actions can take place within the lifecycle of that observation via the ObservationHandler. According to what is configured the actions can be e.g. taking measurements via Timer, creating spans for distributed tracing, correlating logs or just logging out additional information. You instrument your code once with an Observation but you can get as many benefits out of it as many ObservationHandler you have.
Since:
1.10.0

  • Field Details

    • NOOP

      static final Observation NOOP
      No-op observation.

  • Method Details

    • start

      static Observation start(String name, @Nullable ObservationRegistry registry)
      Create and start an Observation with the given name. All Observations of the same type must share the same name.

      When no registry is passed or the observation is not applicable, a no-op observation will be returned.

      Parameters:
      name - name of the observation
      registry - observation registry
      Returns:
      a started observation

    • start

      static <T extends Observation.Context> Observation start(String name, Supplier<T> contextSupplier, @Nullable ObservationRegistry registry)
      Creates and starts an Observation. When the ObservationRegistry is null or the no-op registry, this fast returns a no-op Observation and skips the creation of the Observation.Context. This check avoids unnecessary Observation.Context creation, which is why it takes a Supplier for the context rather than the context directly. If the observation is not enabled (see ObservationConfig#observationPredicate), a no-op observation will also be returned.
      Parameters:
      name - name of the observation
      contextSupplier - mutable context supplier
      registry - observation registry
      Returns:
      started observation

    • createNotStarted

      static Observation createNotStarted(String name, @Nullable ObservationRegistry registry)
      Creates but does not start an Observation. Remember to call start() when you want the measurements to start. When no registry is passed or observation is not applicable will return a no-op observation.
      Parameters:
      name - name of the observation
      registry - observation registry
      Returns:
      created but not started observation

    • createNotStarted

      static <T extends Observation.Context> Observation createNotStarted(String name, Supplier<T> contextSupplier, @Nullable ObservationRegistry registry)
      Creates but does not start an Observation. Remember to call start() when you want the measurements to start. When the ObservationRegistry is null or the no-op registry, this fast returns a no-op Observation and skips the creation of the Observation.Context. This check avoids unnecessary Observation.Context creation, which is why it takes a Supplier for the context rather than the context directly. If the observation is not enabled (see ObservationConfig#observationPredicate), a no-op observation will also be returned.
      Parameters:
      name - name of the observation
      contextSupplier - supplier for mutable context
      registry - observation registry
      Returns:
      created but not started observation

    • createNotStarted

      static <T extends Observation.Context> Observation createNotStarted(@Nullable ObservationConvention<T> customConvention, ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, @Nullable ObservationRegistry registry)
      Creates but does not start an Observation.

      Remember to call start() when you want the measurements to start. When the ObservationRegistry is null or the no-op registry, this returns a no-op Observation and skips the creation of the Observation.Context. If the observation is not enabled (see ObservationConfig#observationPredicate), a no-op observation will also be returned.

      A single convention will be used for this observation for getting its name and key values:

      1. the customConvention given as an argument, if not null
      2. a GlobalObservationConvention configured on the ObservationRegistry.ObservationConfig.observationConvention(GlobalObservationConvention) that matches this observation
      3. as a fallback, the defaultConvention will be used if none of the above are available
      Type Parameters:
      T - type of context
      Parameters:
      customConvention - custom convention. If null, the default one will be picked.
      defaultConvention - default convention when no custom convention was passed, nor a pre-configured one was found
      contextSupplier - supplier for the observation context
      registry - observation registry
      Returns:
      created but not started observation

    • start

      static Observation start(ObservationConvention<Observation.Context> observationConvention, ObservationRegistry registry)
      Creates and starts an Observation. When no registry is passed or observation is not applicable will return a no-op observation.

      Please check the javadoc of createNotStarted(ObservationConvention, ObservationConvention, Supplier, ObservationRegistry) method for the logic of choosing the convention.

      Parameters:
      observationConvention - observation convention
      registry - observation registry
      Returns:
      started observation

    • start

      static <T extends Observation.Context> Observation start(ObservationConvention<T> observationConvention, Supplier<T> contextSupplier, ObservationRegistry registry)
      Creates and starts an Observation. When the ObservationRegistry is null or the no-op registry, this fast returns a no-op Observation and skips the creation of the Observation.Context. This check avoids unnecessary Observation.Context creation, which is why it takes a Supplier for the context rather than the context directly. If the observation is not enabled (see ObservationConfig#observationPredicate), a no-op observation will also be returned.

      Please check the javadoc of createNotStarted(ObservationConvention, ObservationConvention, Supplier, ObservationRegistry) method for the logic of choosing the convention.

      Type Parameters:
      T - type of context
      Parameters:
      observationConvention - observation convention
      contextSupplier - mutable context supplier
      registry - observation registry
      Returns:
      started observation

    • start

      static <T extends Observation.Context> Observation start(@Nullable ObservationConvention<T> customConvention, ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, ObservationRegistry registry)
      Creates and starts an Observation. When the ObservationRegistry is null or the no-op registry, this fast returns a no-op Observation and skips the creation of the Observation.Context. This check avoids unnecessary Observation.Context creation, which is why it takes a Supplier for the context rather than the context directly. If the observation is not enabled (see ObservationConfig#observationPredicate), a no-op observation will also be returned. Allows to set a custom ObservationConvention and requires to provide a default one if neither a custom nor a pre-configured one (via ObservationRegistry.ObservationConfig.getObservationConvention(Context, ObservationConvention)) was found.

      Please check the javadoc of createNotStarted(ObservationConvention, ObservationConvention, Supplier, ObservationRegistry) method for the logic of choosing the convention.

      Type Parameters:
      T - type of context
      Parameters:
      customConvention - custom convention. If null, the default one will be picked.
      defaultConvention - default convention when no custom convention was passed, nor a configured one was found
      contextSupplier - the observation context supplier
      registry - observation registry
      Returns:
      started observation

    • createNotStarted

      static Observation createNotStarted(ObservationConvention<Observation.Context> observationConvention, ObservationRegistry registry)
      Creates but does not start an Observation. Remember to call start() when you want the measurements to start. When no registry is passed or observation is not applicable will return a no-op observation.

      Please check the javadoc of createNotStarted(ObservationConvention, ObservationConvention, Supplier, ObservationRegistry) method for the logic of choosing the convention.

      Parameters:
      observationConvention - observation convention
      registry - observation registry
      Returns:
      created but not started observation

    • createNotStarted

      static <T extends Observation.Context> Observation createNotStarted(ObservationConvention<T> observationConvention, Supplier<T> contextSupplier, ObservationRegistry registry)
      Creates but does not start an Observation. Remember to call start() when you want the measurements to start. When the ObservationRegistry is null or the no-op registry, this fast returns a no-op Observation and skips the creation of the Observation.Context. This check avoids unnecessary Observation.Context creation, which is why it takes a Supplier for the context rather than the context directly. If the observation is not enabled (see ObservationConfig#observationPredicate), a no-op observation will also be returned.

      Important! If you're using the ObservationConvention.getContextualName(Context) method to override the contextual name you MUST use a non null context (i.e. the context parameter of this method MUST NOT be null). The ObservationConvention.getContextualName(Context) requires a concrete type of Observation.Context to be passed and if you're not providing one we won't be able to initialize it ourselves.

      Please check the javadoc of createNotStarted(ObservationConvention, ObservationConvention, Supplier, ObservationRegistry) method for the logic of choosing the convention.

      Type Parameters:
      T - type of context
      Parameters:
      observationConvention - observation convention
      contextSupplier - mutable context supplier
      registry - observation registry
      Returns:
      created but not started observation

    • contextualName

      Observation contextualName(@Nullable String contextualName)
      Sets the name that can be defined from the contents of the context. E.g. a span name should not be the default observation name but one coming from an HTTP request.
      Parameters:
      contextualName - contextual name
      Returns:
      this

    • parentObservation

      Observation parentObservation(@Nullable Observation parentObservation)
      If you have access to a previously created Observation you can manually set the parent Observation using this method - that way you won't need to open scopes just to create a child observation. If you're using the openScope() method then the parent observation will be automatically set, and you don't have to call this method.
      Parameters:
      parentObservation - parent observation to set
      Returns:
      this

    • lowCardinalityKeyValue

      Observation lowCardinalityKeyValue(io.micrometer.common.KeyValue keyValue)
      Adds a low cardinality key value. Low cardinality means that this key value will have a bounded number of possible values. A templated HTTP URL is a good example of such a key value (e.g. /foo/{userId}).
      Parameters:
      keyValue - key value
      Returns:
      this

    • lowCardinalityKeyValue

      default Observation lowCardinalityKeyValue(String key, String value)
      Adds a low cardinality key value. Low cardinality means that this key value will have a bounded number of possible values. A templated HTTP URL is a good example of such a key value (e.g. /foo/{userId}).
      Parameters:
      key - key
      value - value
      Returns:
      this

    • lowCardinalityKeyValues

      default Observation lowCardinalityKeyValues(io.micrometer.common.KeyValues keyValues)
      Adds multiple low cardinality key value instances. Low cardinality means that the key value will have a bounded number of possible values. A templated HTTP URL is a good example of such a key value (e.g. /foo/{userId}).
      Parameters:
      keyValues - key value instances
      Returns:
      this

    • highCardinalityKeyValue

      Observation highCardinalityKeyValue(io.micrometer.common.KeyValue keyValue)
      Adds a high cardinality key value. High cardinality means that this key value will have an unbounded number of possible values. An HTTP URL is a good example of such a key value (e.g. /foo/bar, /foo/baz etc.).
      Parameters:
      keyValue - key value
      Returns:
      this

    • highCardinalityKeyValue

      default Observation highCardinalityKeyValue(String key, String value)
      Adds a high cardinality key value. High cardinality means that this key value will have an unbounded number of possible values. An HTTP URL is a good example of such a key value (e.g. /foo/bar, /foo/baz etc.).
      Parameters:
      key - key
      value - value
      Returns:
      this

    • highCardinalityKeyValues

      default Observation highCardinalityKeyValues(io.micrometer.common.KeyValues keyValues)
      Adds multiple high cardinality key value instances. High cardinality means that the key value will have an unbounded number of possible values. An HTTP URL is a good example of such a key value (e.g. /foo/bar, /foo/baz etc.).
      Parameters:
      keyValues - key value instances
      Returns:
      this

    • isNoop

      default boolean isNoop()
      Checks whether this Observation is no-op.
      Returns:
      true when this is a no-op observation

    • observationConvention

      Observation observationConvention(ObservationConvention<?> observationConvention)
      Sets an observation convention that can be used to attach key values to the observation. Implementations should only set the convention when it supports (see: ObservationConvention.supportsContext(Context)) the current Observation.Context. WARNING: You must set the ObservationConvention to the Observation before it is started.
      Parameters:
      observationConvention - observation convention
      Returns:
      this

    • error

      Observation error(Throwable error)
      Signals an error.
      Parameters:
      error - error
      Returns:
      this

    • event

      Observation event(Observation.Event event)
      Signals an arbitrary Observation.Event.
      Parameters:
      event - event
      Returns:
      this

    • start

      Observation start()
      Starts the observation. Remember to call this method, otherwise timing calculations will not take place.
      Returns:
      this

    • getContext

      Observation.Context getContext()
      Returns the context attached to this observation.
      Returns:
      corresponding context

    • getContextView

      default Observation.ContextView getContextView()
      Returns the context attached to this observation as a read only view.
      Specified by:
      getContextView in interface ObservationView
      Returns:
      corresponding context

    • stop

      void stop()
      Stop the observation. Remember to call this method, otherwise timing calculations won't be finished.

    • openScope

      Observation.Scope openScope()
      When put in scope, additional operations can take place by the ObservationHandlers such as putting entries in thread local.
      Returns:
      new scope

    • observe

      default void observe(Runnable runnable)
      Observes the passed Runnable, this means the followings:
      • Starts the Observation
      • Opens a Scope
      • Calls Runnable.run()
      • Closes the Scope
      • Signals the error to the Observation if any
      • Stops the Observation
      Parameters:
      runnable - the Runnable to run

    • wrap

      default Runnable wrap(Runnable runnable)

    • observeChecked

      default <E extends Throwable> void observeChecked(Observation.CheckedRunnable<E> checkedRunnable) throws E
      Observes the passed Observation.CheckedRunnable, this means the followings:
      Type Parameters:
      E - type of exception thrown
      Parameters:
      checkedRunnable - the Observation.CheckedRunnable to run
      Throws:
      E

    • wrapChecked

      default <E extends Throwable> Observation.CheckedRunnable<E> wrapChecked(Observation.CheckedRunnable<E> checkedRunnable) throws E
      Throws:
      E

    • observe

      default <T> T observe(Supplier<T> supplier)
      Observes the passed Supplier, this means the followings:
      • Starts the Observation
      • Opens a Scope
      • Calls Supplier.get()
      • Closes the Scope
      • Signals the error to the Observation if any
      • Stops the Observation
      Type Parameters:
      T - the type parameter of the Supplier
      Parameters:
      supplier - the Supplier to call
      Returns:
      the result from Supplier.get()

    • wrap

      default <T> Supplier<T> wrap(Supplier<T> supplier)

    • observeChecked

      default <T, E extends Throwable> T observeChecked(Observation.CheckedCallable<T,E> checkedCallable) throws E
      Observes the passed Observation.CheckedCallable, this means the followings:
      Type Parameters:
      T - the return type of the Observation.CheckedCallable
      E - type of exception checkedCallable throws
      Parameters:
      checkedCallable - the Observation.CheckedCallable to call
      Returns:
      the result from Observation.CheckedCallable.call()
      Throws:
      E

    • wrapChecked

      default <T, E extends Throwable> Observation.CheckedCallable<T,E> wrapChecked(Observation.CheckedCallable<T,E> checkedCallable) throws E
      Throws:
      E

    • scoped

      default void scoped(Runnable runnable)
      Wraps the given action in a scope and signals an error.
      Parameters:
      runnable - the Runnable to run

    • scopedChecked

      default <E extends Throwable> void scopedChecked(Observation.CheckedRunnable<E> checkedRunnable) throws E
      Wraps the given action in a scope and signals an error.
      Type Parameters:
      E - type of exception thrown
      Parameters:
      checkedRunnable - the Observation.CheckedRunnable to run
      Throws:
      E

    • scoped

      default <T> T scoped(Supplier<T> supplier)
      Wraps the given action in a scope and signals an error.
      Type Parameters:
      T - the return type of the Supplier
      Parameters:
      supplier - the Supplier to call
      Returns:
      the result from Supplier.get()

    • scopedChecked

      default <T, E extends Throwable> T scopedChecked(Observation.CheckedCallable<T,E> checkedCallable) throws E
      Wraps the given action in a scope and signals an error.
      Type Parameters:
      T - the return type of the Observation.CheckedCallable
      E - type of exception checkedCallable throws
      Parameters:
      checkedCallable - the Observation.CheckedCallable to call
      Returns:
      the result from Observation.CheckedCallable.call()
      Throws:
      E

    • tryScoped

      static void tryScoped(@Nullable Observation parent, Runnable action)
      Tries to run the action against an Observation. If the Observation is null, we just run the action, otherwise we run the action in scope.
      Parameters:
      parent - observation, potentially null
      action - action to run

    • tryScopedChecked

      static <E extends Throwable> void tryScopedChecked(@Nullable Observation parent, Observation.CheckedRunnable<E> checkedRunnable) throws E
      Tries to run the action against an Observation. If the Observation is null, we just run the action, otherwise we run the action in scope.
      Type Parameters:
      E - type of exception checkedRunnable throws
      Parameters:
      parent - observation, potentially null
      checkedRunnable - the Observation.CheckedRunnable to run
      Throws:
      E

    • tryScoped

      static <T> T tryScoped(@Nullable Observation parent, Supplier<T> action)
      Tries to run the action against an Observation. If the Observation is null, we just run the action, otherwise we run the action in scope.
      Parameters:
      parent - observation, potentially null
      action - action to run
      Returns:
      result of the action

    • tryScopedChecked

      static <T, E extends Throwable> T tryScopedChecked(@Nullable Observation parent, Observation.CheckedCallable<T,E> checkedCallable) throws E
      Tries to run the action against an Observation. If the Observation is null, we just run the action, otherwise we run the action in scope.
      Type Parameters:
      T - the return type of the Observation.CheckedCallable
      E - type of exception checkedCallable throws
      Parameters:
      parent - observation, potentially null
      checkedCallable - the Observation.CheckedCallable to call
      Returns:
      the result from Observation.CheckedCallable.call()
      Throws:
      E