Skip to content

Commit

Permalink
Javadoc and nullability checks
Browse files Browse the repository at this point in the history
  • Loading branch information
@bclozel @marcingrzejszczak
bclozel authored and marcingrzejszczak committed Nov 23, 2022
1 parent c9dad1f commit a4007b7
Showing 1 changed file with 27 additions and 43 deletions.
70 changes: 27 additions & 43 deletions micrometer-observation/src/main/java/io/micrometer/observation/Observation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,13 +55,16 @@ public interface Observation extends ObservationView {
Observation NOOP = NoopObservation.INSTANCE;

/**
* Creates and starts an {@link Observation}. When no registry is passed or
* observation is not applicable will return a no-op observation.
* Create and start an {@link Observation} with the given name.
* All Observations of the same type must share the same name.
* <p>When no registry is passed or the observation is
* {@link ObservationRegistry.ObservationConfig#observationPredicate(ObservationPredicate) not applicable},
* a no-op observation will be returned.
* @param name name of the observation
* @param registry observation registry
* @return started observation
* @return a started observation
*/
static Observation start(String name, ObservationRegistry registry) {
static Observation start(String name, @Nullable ObservationRegistry registry) {
return start(name, Context::new, registry);
}

Expand All @@ -81,7 +84,7 @@ static Observation start(String name, ObservationRegistry registry) {
* @return started observation
*/
static <T extends Context> Observation start(String name, Supplier<T> contextSupplier,
ObservationRegistry registry) {
@Nullable ObservationRegistry registry) {
return createNotStarted(name, contextSupplier, registry).start();
}

Expand All @@ -94,7 +97,7 @@ static <T extends Context> Observation start(String name, Supplier<T> contextSup
* @param registry observation registry
* @return created but not started observation
*/
static Observation createNotStarted(String name, ObservationRegistry registry) {
static Observation createNotStarted(String name, @Nullable ObservationRegistry registry) {
return createNotStarted(name, Context::new, registry);
}

Expand All @@ -116,7 +119,7 @@ static Observation createNotStarted(String name, ObservationRegistry registry) {
* @return created but not started observation
*/
static <T extends Context> Observation createNotStarted(String name, Supplier<T> contextSupplier,
ObservationRegistry registry) {
@Nullable ObservationRegistry registry) {
if (registry == null || registry.isNoop()) {
return NOOP;
}
Expand All @@ -129,42 +132,23 @@ static <T extends Context> Observation createNotStarted(String name, Supplier<T>

// @formatter:off
/**
* Creates but <b>does not start</b> an {@link Observation}. Remember to call
* {@link Observation#start()} when you want the measurements to start. When the
* {@link ObservationRegistry} is null or the no-op registry, this fast returns a
* no-op {@link Observation} and skips the creation of the
* {@link Observation.Context}. This check avoids unnecessary
* {@link Observation.Context} creation, which is why it takes a {@link Supplier} for
* the context rather than the context directly. If the observation is not enabled
* (see
* Create but <b>does not start</b> an {@link Observation}.
* <p>Remember to call {@link Observation#start()} when you want the measurements to start.
* When the {@link ObservationRegistry} is null or the no-op registry, this returns a
* no-op {@link Observation} and skips the creation of the {@link Observation.Context}.
* If the observation is not enabled (see
* {@link ObservationRegistry.ObservationConfig#observationPredicate(ObservationPredicate)
* ObservationConfig#observationPredicate}), a no-op observation will also be
* returned. Allows to set a custom {@link ObservationConvention} and requires to
* provide a default one if neither a custom nor a pre-configured one (via
* {@link ObservationRegistry.ObservationConfig#getObservationConvention(Context, ObservationConvention)})
* was found. The {@link ObservationConvention} implementation can override
* {@link Observation} names (i.e. name and contextual name) and key values.
* <pre>
* Here you can find the matrix of choosing the convention:
* 1. custom default no pre-configured -> custom
* 2. custom default pre-configured -> custom (not a valid case, just use custom)
* 3. no custom default no pre-configured -> default
* 4. no custom default pre-configured -> pre-configured
* 5. custom no default no pre-configured -> custom (providing default is recommended)
* 6. custom no default pre-configured -> custom (providing default is recommended)
* 7. no custom no default no pre-configured -> local names/tags will be used
* 8. no custom no default pre-configured -> pre-configured
* </pre>
* <p>
* Also, if you set a convention using,
* {@link Observation#observationConvention(ObservationConvention)} (not recommended),
* the convention you set here will be used and everything else (custom, default,
* pre-configured) will be ignored.
* </p>
* <p>
* If you want to add to the all the contexts or mutate them,
* use the ObservationFilter (e.g.: add region=cloud-1 or remove PII).
* </p>
* returned.
* <p>A single {@link ObservationConvention convention} will be used for this observation
* for getting its name and {@link KeyValues key values}:
* <ol>
* <li>the {@code customConvention} given as an argument, if not {@code null}
* <li>a {@link GlobalObservationConvention} configured on the
* {@link ObservationRegistry.ObservationConfig#observationConvention(GlobalObservationConvention)}
* that matches this observation
* <li>as a fallback, the {@code defaultConvention} will be used if none of the above are available
* </ol>
* @param <T> type of context
* @param customConvention custom convention. If {@code null}, the default one will be
* picked.
Expand All @@ -176,8 +160,8 @@ static <T extends Context> Observation createNotStarted(String name, Supplier<T>
*/
// @formatter:on
static <T extends Context> Observation createNotStarted(@Nullable ObservationConvention<T> customConvention,
ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, ObservationRegistry registry) {
if (registry.isNoop()) {
ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, @Nullable ObservationRegistry registry) {
if (registry == null || registry.isNoop()) {
return Observation.NOOP;
}
ObservationConvention<T> convention;
Expand Down

0 comments on commit a4007b7

Please sign in to comment.