Javadoc and nullability checks

Author: bclozel

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

@@ -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);
     }
 
@@ -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();
     }
 
@@ -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);
     }
 
@@ -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;
         }
@@ -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.
@@ -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;