Added more high-overview docs with graphs; fixes micrometer-metricsgh…

…-4726

docs/modules/ROOT/nav.adoc

@@ -61,7 +61,7 @@
 * xref:observation.adoc[Micrometer Observation]
 ** xref:observation/installing.adoc[Installing]
 ** xref:observation/introduction.adoc[Introduction]
-** xref:observation/handler.adoc[Observation Handlers]
+** xref:observation/components.adoc[Components]
 ** xref:observation/instrumenting.adoc[Instrumenting]
 ** xref:observation/testing.adoc[Testing]
 ** xref:observation/projects.adoc[Instrumented Projects]

docs/modules/ROOT/pages/observation/handler.adoc → docs/modules/ROOT/pages/observation/components.adoc

@@ -1,5 +1,69 @@
+[[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 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
 
 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:
@@ -19,13 +83,8 @@ include::{include-java}/observation/ObservationHandlerTests.java[tags=observatio
 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).
 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`: