Package io.micrometer.observation.docs

Interface ObservationDocumentation

public interface ObservationDocumentation

In order to describe your samples via e.g. enums instead of Strings you can use this interface that returns all the characteristics of a sample. We can analyze the sources and reuse this information to build a table of known metrics, their names and tags. We can generate documentation for all created samples but certain requirements need to be met.

• Observations are grouped within an enum - the enum implements the ObservationDocumentation interface
• If the observation contains KeyName then those need to be declared as nested enums
• The getHighCardinalityKeyNames() need to call the nested enum's values() method to retrieve the array of allowed keys
• The getLowCardinalityKeyNames() need to call the nested enum's values() method to retrieve the array of allowed keys
• Javadocs around enums will be used as description
• If you want to merge different KeyName enum values() methods you need to call the KeyName.merge(KeyName[]...) method

Since:

1.10.0

Field Summary

Fields

Modifier and Type	Field	Description
static final io.micrometer.common.docs.KeyName[]	EMPTY	Empty key names.
static final Observation.Event[]	EMPTY_EVENT_NAMES	Empty event names.

Method Summary

Modifier and Type	Method	Description
default String	getContextualName()	More human-readable name available within the given context (e.g.: span name).
default Class<? extends ObservationConvention<? extends Observation.Context>>	getDefaultConvention()	Default naming convention (sets technical and contextual names, and key values).
default Observation.Event[]	getEvents()	Event values.
default io.micrometer.common.docs.KeyName[]	getHighCardinalityKeyNames()	High cardinality key names.
default io.micrometer.common.docs.KeyName[]	getLowCardinalityKeyNames()	Low cardinality key names.
default String	getName()	Default technical name (e.g.: metric name).
default String	getPrefix()	Returns required prefix to be there for tags.
default <T extends Observation.Context> Observation	observation(ObservationConvention<T> customConvention, ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, ObservationRegistry registry)	Creates an Observation for the given ObservationConvention.
default Observation	observation(ObservationRegistry registry)	Creates an Observation.
default Observation	observation(ObservationRegistry registry, Supplier<Observation.Context> contextSupplier)	Creates an Observation.
default <T extends Observation.Context> Observation	start(ObservationConvention<T> customConvention, ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, ObservationRegistry registry)	Creates and starts an Observation.
default Observation	start(ObservationRegistry registry)	Creates and starts an Observation.
default Observation	start(ObservationRegistry registry, Supplier<Observation.Context> contextSupplier)	Creates and starts an Observation.

Field Details

EMPTY

static final io.micrometer.common.docs.KeyName[] EMPTY

Empty key names.

EMPTY_EVENT_NAMES

static final Observation.Event[] EMPTY_EVENT_NAMES

Empty event names.

Method Details

getName

@Nullable
default String getName()

Default technical name (e.g.: metric name). You can set the name either by this method or getDefaultConvention(). You can't use both.

Returns:

name

getDefaultConvention

@Nullable
default Class<? extends ObservationConvention<? extends Observation.Context>> getDefaultConvention()

Default naming convention (sets technical and contextual names, and key values). You can set the names either by this method or getName() and getContextualName().

Returns:

default naming convention

getContextualName

@Nullable
default String getContextualName()

More human-readable name available within the given context (e.g.: span name). You can set the name either by this method or getDefaultConvention(). This method will override what getDefaultConvention() has set.

Returns:

contextual name

getLowCardinalityKeyNames

default io.micrometer.common.docs.KeyName[] getLowCardinalityKeyNames()

Low cardinality key names.

Returns:

allowed tag keys for low cardinality key-values

getHighCardinalityKeyNames

default io.micrometer.common.docs.KeyName[] getHighCardinalityKeyNames()

High cardinality key names.

Returns:

allowed tag keys for high cardinality key-values

getEvents

default Observation.Event[] getEvents()

Event values.

Returns:

allowed event values

getPrefix

default String getPrefix()

Returns required prefix to be there for tags. For example, foo. would require the tags to have a foo. prefix like this: foo.bar=true.

Returns:

required prefix

observation

default Observation observation(ObservationRegistry registry)

Creates an Observation. You need to manually start it.

Parameters:

registry - observation registry

Returns:

observation

observation

default Observation observation(ObservationRegistry registry,
 Supplier<Observation.Context> contextSupplier)

Creates an Observation. You need to manually start it. 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 by an ObservationPredicate, a no-op observation will also be returned.

Parameters:

registry - observation registry

contextSupplier - observation context supplier

Returns:

observation

observation

default <T extends Observation.Context> Observation observation(@Nullable
 ObservationConvention<T> customConvention,
 ObservationConvention<T> defaultConvention,
 Supplier<T> contextSupplier,
 ObservationRegistry registry)

Creates an Observation for the given ObservationConvention. You need to manually start it. 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 by an ObservationPredicate, a no-op observation will also be returned.

Parameters:

customConvention - convention that (if not null) will override any pre-configured conventions

defaultConvention - default convention that will be picked if there was neither custom convention nor a pre-configured one via ObservationRegistry.ObservationConfig.observationConvention(GlobalObservationConvention)

contextSupplier - observation context supplier

registry - observation registry

Returns:

observation

start

default Observation start(ObservationRegistry registry)

Creates and starts an Observation.

Parameters:

registry - observation registry

Returns:

observation

start

default Observation start(ObservationRegistry registry,
 Supplier<Observation.Context> contextSupplier)

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 by an ObservationPredicate, a no-op observation will also be returned.

Parameters:

registry - observation registry

contextSupplier - observation context supplier

Returns:

observation

start

default <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 by an ObservationPredicate, a no-op observation will also be returned.

Parameters:

customConvention - convention that (if not null) will override any pre-configured conventions

defaultConvention - default convention that will be picked if there was neither custom convention nor a pre-configured one via ObservationRegistry.ObservationConfig.observationConvention(GlobalObservationConvention)

contextSupplier - observation context supplier

registry - observation registry

Returns:

observation