Merge branch 'micrometer-metrics:main' into micrometer-metricsgh-1441

Author: jkemming

docs/modules/ROOT/pages/observation.adoc

@@ -3,4 +3,6 @@
 
 Micrometer Observation is part of the https://github.com/micrometer-metrics/micrometer[Micrometer] project and contains the Observation API. The main idea behind it is that you
 
-> Instrument code once, and get multiple benefits out of it.
+****
+_"Instrument code once, and get multiple benefits out of it."_
+****

docs/modules/ROOT/pages/observation/handler.adoc renamed to docs/modules/ROOT/pages/observation/components.adoc

@@ -1,5 +1,73 @@
+[[micrometer-observation-components]]
+= Observation Components
+
+In this section we will describe main components related to Micrometer Observation.
+
+* <<micrometer-observation-context, Observation Context>>
+* <<micrometer-observation-handler, Observation Handler>>
+* <<micrometer-observation-events, Signaling Errors and Arbitrary Events>>
+* <<micrometer-observation-convention-example, Observation Convention>>
+* <<micrometer-observation-predicates-filters, Observation Predicates and Filters>>
+
+*Micrometer Observation basic flow*
+
+`Observation` through `ObservationRegistry` gets created with a mutable `Observation.Context`. On each Micrometer Observation lifecycle action (e.g. `start()`) a corresponding `ObservationHandler` method is called (e.g. `onStart`) with the mutable `Observation.Context` as argument.
+
+// https://arthursonzogni.com/Diagon/#GraphDAG
+// ObservationRegistry->Observation
+// Context->Observation
+// Observation->Handler
+[source,subs=+attributes]
+-----
+┌───────────────────┐┌───────┐
+│ObservationRegistry││Context│
+└┬──────────────────┘└┬──────┘
+┌▽────────────────────▽┐
+│Observation           │
+└┬─────────────────────┘
+┌▽──────┐
+│Handler│
+└───────┘
+-----
+
+*Micrometer Observation detailed flow*
+
+// https://arthursonzogni.com/Diagon/#GraphDAG
+// ObservationRegistry->Observation
+// Context->Observation
+// ObservationConvention->Observation
+// ObservationPredicate->Observation
+// Observation->Handler
+// Handler->ObservationFilter
+[source,subs=+attributes]
+-----
+┌───────────────────┐┌───────┐┌─────────────────────┐┌────────────────────┐
+│ObservationRegistry││Context││ObservationConvention││ObservationPredicate│
+└┬──────────────────┘└┬──────┘└┬────────────────────┘└┬───────────────────┘
+┌▽────────────────────▽────────▽──────────────────────▽┐
+│Observation                                           │
+└┬─────────────────────────────────────────────────────┘
+┌▽──────┐
+│Handler│
+└┬──────┘
+┌▽────────────────┐
+│ObservationFilter│
+└─────────────────┘
+-----
+
+`Observation` through `ObservationRegistry` gets created with a mutable `Observation.Context`. To allow name and key-value customization, an `ObservationConvention` can be used instead of direct name setting. List of `ObservationPredicate` is run to verify if an `Observation` should be created instead of a no-op version.  On each xref:observation/introduction.adoc[Micrometer Observation lifecycle] action (e.g. `start()`) a corresponding `ObservationHandler` method is called (e.g. `onStart`) with the mutable `Observation.Context` as argument. On `Observation` stop, before calling the `ObservationHandler` `onStop` methods, list of `ObservationFilter` is called to optionally further modify the `Observation.Context`.
+
+[[micrometer-observation-context]]
+== Observation.Context
+
+To pass information between the instrumented code and the handler (or between handler methods, such as `onStart` and `onStop`), you can use an `Observation.Context`. An `Observation.Context` is a `Map`-like container that can store values for you while your handler can access the data inside the context.
+
 [[micrometer-observation-handler]]
-= Observation Handler
+== Observation Handler
+
+Observation Handler allows adding capabilities to existing instrumentations (i.e. you instrument code once and depending on the Observation Handler setup, different actions, such as create spans, metrics, logs will happen). In other words, if you have instrumented code and want to add metrics around it, it's enough for you to register an Observation Handler in the Observation Registry to add that behaviour.
+
+Let's look at the following example of adding a timer behaviour to an existing instrumentation.
 
 A popular way to record Observations is storing the start state in a `Timer.Sample` instance and stopping it when the event has ended.
 Recording such measurements could look like this:
@@ -16,16 +84,11 @@ If you want to have more observation options (such as metrics and tracing -- alr
 include::{include-java}/observation/ObservationHandlerTests.java[tags=observation,indent=0]
 -----
 
-Starting with Micrometer 1.10, you can register "handlers" (`ObservationHandler` instances) that are notified about the lifecycle event of an observation (for example, you can run custom code when an observation is started or stopped).
+Starting with Micrometer 1.10, you can register "handlers" (`ObservationHandler` instances) that are notified about the xref:observation/introduction.adoc[lifecycle event] of an observation (for example, you can run custom code when an observation is started or stopped).
 Using this feature lets you add tracing capabilities to your existing metrics instrumentation (see: `DefaultTracingObservationHandler`). The implementation of these handlers does not need to be tracing related. It is completely up to you how you are going to implement them (for example, you can add logging capabilities).
 
-[[micrometer-observation-context]]
-== Observation.Context
-
-To pass information between the instrumented code and the handler (or between handler methods, such as `onStart` and `onStop`), you can use an `Observation.Context`. An `Observation.Context` is a `Map`-like container that can store values for you while your handler can access the data inside the context.
-
 [[micrometer-observation-handler-example]]
-== ObservationHandler Example
+=== ObservationHandler Example
 
 Based on this, we can implement a simple handler that lets the users know about its invocations by printing them out to `stdout`: