Add docs for ObservationValidator

Closes micrometer-metricsgh-5387

docs/modules/ROOT/pages/observation/testing.adoc

@@ -40,3 +40,21 @@ To unit-test this code, you can use the `TestObservationRegistry` class:
 -----
 include::{include-java}/observation/ObservationTestingTests.java[tags=test,indent=0]
 -----
+
+[[micrometer-observation-validator]]
+== Observation Validator
+
+If you use `TestObservationRegistry`, an `ObservationHandler` called `ObservationValidator` is registered automatically. The purpose of this `ObservationHandler` is validating the order of the calls on an `Observation` (for example `stop` should not be called before `start` or neither of them should be called twice, etc). Please check `ObservationValidatorTests` for the list of invalid scenarios.
+
+If `ObservationValidator` detects such an issue, it will throw an `InvalidObservationException` which contains a validation message (explains why the `Observation` is invalid), the original `Observation.Context` and a history with the relevant stacktraces of the calls that were made on the `Observation`. These should help you to troubleshoot what went wrong with the instrumentation. The `toString()` method of the `InvalidObservationException` gives you the error message and a textual summary of the history, something like this:
+
+```
+io.micrometer.observation.tck.InvalidObservationException: Invalid error signal: Observation has already been stopped
+START: app//io.micrometer.observation.tck.ObservationValidatorTests.errorAfterStopShouldBeInvalid(ObservationValidatorTests.java:98)
+STOP: app//io.micrometer.observation.tck.ObservationValidatorTests.errorAfterStopShouldBeInvalid(ObservationValidatorTests.java:99)
+ERROR: app//io.micrometer.observation.tck.ObservationValidatorTests.errorAfterStopShouldBeInvalid(ObservationValidatorTests.java:100)
+```
+
+Based on this, it seems that `error` (in `ObservationValidatorTests.java`, line `#100`) was called after `stop` (in `ObservationValidatorTests.java`, line `#99`) which is an invalid scenario. If you view the error in an IDE, the locations (i.e.: `ObservationValidatorTests.java:98`) should be "links" and clicking them should make the IDE jump to that line.
+
+If you get an error like the above coming from the instrumentation of a third-party library, please open an issue/pull request for that project.