|
This version is still in development and is not considered stable yet. For the latest stable version, please use Micrometer 1.13.4! |
Testing
Micrometer Observation comes with the micrometer-observation-test module, which lets you unit-test your Observations.
Installing
The following example shows the required dependency in Gradle (assuming that the Micrometer BOM has been added):
testImplementation 'io.micrometer:micrometer-observation-test'The following example shows the required dependency in Maven (assuming that the Micrometer BOM has been added):
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-observation-test</artifactId>
<scope>test</scope>
</dependency>Running Observation Unit Tests
Suppose you have the following production code. It will create an observation with two tags (low and high cardinality) and then call observe to start the observation, put it in scope, close the scope, and stop the observation:
static class Example {
private final ObservationRegistry registry;
Example(ObservationRegistry registry) {
this.registry = registry;
}
void run() {
Observation.createNotStarted("foo", registry)
.lowCardinalityKeyValue("lowTag", "lowTagValue")
.highCardinalityKeyValue("highTag", "highTagValue")
.observe(() -> System.out.println("Hello"));
}
}To unit-test this code, you can use the TestObservationRegistry class:
@Test
void should_assert_your_observation() {
// create a test registry in your tests
TestObservationRegistry registry = TestObservationRegistry.create();
// run your production code with the TestObservationRegistry
new Example(registry).run();
// check your observation
TestObservationRegistryAssert.assertThat(registry)
.doesNotHaveAnyRemainingCurrentObservation()
.hasObservationWithNameEqualTo("foo")
.that()
.hasHighCardinalityKeyValue("highTag", "highTagValue")
.hasLowCardinalityKeyValue("lowTag", "lowTagValue")
.hasBeenStarted()
.hasBeenStopped();
}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.
