Skip to content

Commit a4007b7

Browse files
bclozelmarcingrzejszczak
bclozel
authored and
marcingrzejszczak
committed
Javadoc and nullability checks
1 parent c9dad1f commit a4007b7

1 file changed

Lines changed: 27 additions & 43 deletions

File tree

‎micrometer-observation/src/main/java/io/micrometer/observation/Observation.java‎

Lines changed: 27 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,16 @@ public interface Observation extends ObservationView {
5555
Observation NOOP = NoopObservation.INSTANCE;
5656

5757
/**
58-
* Creates and starts an {@link Observation}. When no registry is passed or
59-
* observation is not applicable will return a no-op observation.
58+
* Create and start an {@link Observation} with the given name.
59+
* All Observations of the same type must share the same name.
60+
* <p>When no registry is passed or the observation is
61+
* {@link ObservationRegistry.ObservationConfig#observationPredicate(ObservationPredicate) not applicable},
62+
* a no-op observation will be returned.
6063
* @param name name of the observation
6164
* @param registry observation registry
62-
* @return started observation
65+
* @return a started observation
6366
*/
64-
static Observation start(String name, ObservationRegistry registry) {
67+
static Observation start(String name, @Nullable ObservationRegistry registry) {
6568
return start(name, Context::new, registry);
6669
}
6770

@@ -81,7 +84,7 @@ static Observation start(String name, ObservationRegistry registry) {
8184
* @return started observation
8285
*/
8386
static <T extends Context> Observation start(String name, Supplier<T> contextSupplier,
84-
ObservationRegistry registry) {
87+
@Nullable ObservationRegistry registry) {
8588
return createNotStarted(name, contextSupplier, registry).start();
8689
}
8790

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

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

130133
// @formatter:off
131134
/**
132-
* Creates but <b>does not start</b> an {@link Observation}. Remember to call
133-
* {@link Observation#start()} when you want the measurements to start. When the
134-
* {@link ObservationRegistry} is null or the no-op registry, this fast returns a
135-
* no-op {@link Observation} and skips the creation of the
136-
* {@link Observation.Context}. This check avoids unnecessary
137-
* {@link Observation.Context} creation, which is why it takes a {@link Supplier} for
138-
* the context rather than the context directly. If the observation is not enabled
139-
* (see
135+
* Create but <b>does not start</b> an {@link Observation}.
136+
* <p>Remember to call {@link Observation#start()} when you want the measurements to start.
137+
* When the {@link ObservationRegistry} is null or the no-op registry, this returns a
138+
* no-op {@link Observation} and skips the creation of the {@link Observation.Context}.
139+
* If the observation is not enabled (see
140140
* {@link ObservationRegistry.ObservationConfig#observationPredicate(ObservationPredicate)
141141
* ObservationConfig#observationPredicate}), a no-op observation will also be
142-
* returned. Allows to set a custom {@link ObservationConvention} and requires to
143-
* provide a default one if neither a custom nor a pre-configured one (via
144-
* {@link ObservationRegistry.ObservationConfig#getObservationConvention(Context, ObservationConvention)})
145-
* was found. The {@link ObservationConvention} implementation can override
146-
* {@link Observation} names (i.e. name and contextual name) and key values.
147-
* <pre>
148-
* Here you can find the matrix of choosing the convention:
149-
* 1. custom default no pre-configured -> custom
150-
* 2. custom default pre-configured -> custom (not a valid case, just use custom)
151-
* 3. no custom default no pre-configured -> default
152-
* 4. no custom default pre-configured -> pre-configured
153-
* 5. custom no default no pre-configured -> custom (providing default is recommended)
154-
* 6. custom no default pre-configured -> custom (providing default is recommended)
155-
* 7. no custom no default no pre-configured -> local names/tags will be used
156-
* 8. no custom no default pre-configured -> pre-configured
157-
* </pre>
158-
* <p>
159-
* Also, if you set a convention using,
160-
* {@link Observation#observationConvention(ObservationConvention)} (not recommended),
161-
* the convention you set here will be used and everything else (custom, default,
162-
* pre-configured) will be ignored.
163-
* </p>
164-
* <p>
165-
* If you want to add to the all the contexts or mutate them,
166-
* use the ObservationFilter (e.g.: add region=cloud-1 or remove PII).
167-
* </p>
142+
* returned.
143+
* <p>A single {@link ObservationConvention convention} will be used for this observation
144+
* for getting its name and {@link KeyValues key values}:
145+
* <ol>
146+
* <li>the {@code customConvention} given as an argument, if not {@code null}
147+
* <li>a {@link GlobalObservationConvention} configured on the
148+
* {@link ObservationRegistry.ObservationConfig#observationConvention(GlobalObservationConvention)}
149+
* that matches this observation
150+
* <li>as a fallback, the {@code defaultConvention} will be used if none of the above are available
151+
* </ol>
168152
* @param <T> type of context
169153
* @param customConvention custom convention. If {@code null}, the default one will be
170154
* picked.
@@ -176,8 +160,8 @@ static <T extends Context> Observation createNotStarted(String name, Supplier<T>
176160
*/
177161
// @formatter:on
178162
static <T extends Context> Observation createNotStarted(@Nullable ObservationConvention<T> customConvention,
179-
ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, ObservationRegistry registry) {
180-
if (registry.isNoop()) {
163+
ObservationConvention<T> defaultConvention, Supplier<T> contextSupplier, @Nullable ObservationRegistry registry) {
164+
if (registry == null || registry.isNoop()) {
181165
return Observation.NOOP;
182166
}
183167
ObservationConvention<T> convention;

0 commit comments

Comments
 (0)