The new micrometer observation API in Spring Boot 3.0
This time we’ll present one more great feature that comes with spring boot 3.0: support for the new observation APIs added in Micrometer 1.10 – the Micrometer Observation API.
One of the spring boot 3 features is GraalVM Native Image Support. This time we’ll present one more great feature that comes with spring boot 3.0: support for the new observation APIs added in Micrometer 1.10. To demonstrate how to use it in your own applications, we’ll add it to a sample application.
What is the observation API in Micrometer?
The Micrometer Observation API is a new kind of API in micrometer that lets us hide low level APIs like metrics, logging, and tracing behind a new concept called Observation. Previously, you set out to measure, log or trace something; now you simply want to observe that something took place in our system, and on that basis you can attach metrics, logs, or traces. And since it is merely a facade over the low level API, you can still send your metrics and traces to monitoring or tracing systems like Datadog, Graphite, Prometheus, or Zipkin. The complete list of supported systems is available in the spring boot metrics documentation and the spring boot tracing documentation.
The key sentence in the docs sums it up nicely: Instrument your code a single time and reap many benefits from it. Those many benefits mean you can build numerous features on top of the observation you added. What’s more – and this matters most to me – this API moves our attention to what we want to observe rather than how. We no longer have to deal with low-level abstractions such as Timer, Counter, or Logger to measure something; we simply state what we want to observe. Let me demonstrate with an example.
How to use this API
I’ll wrap our UserService in a sample observation and explain what is meant by many benefits.
Below is a fragment of the UserService class that we’ll decorate using the observation API
public class UserApplicationService implements UserService {
private final UserRepository userRepository;
private final PasswordEncoder passwordEncoder;
private final BearerTokenSupplier bearerTokenSupplier;
public UserApplicationService(
UserRepository userRepository, PasswordEncoder passwordEncoder, BearerTokenSupplier bearerTokenSupplier) {
this.userRepository = userRepository;
this.passwordEncoder = passwordEncoder;
this.bearerTokenSupplier = bearerTokenSupplier;
}
@Transactional
@Override
public User signUp(SignUpUserRequest request) {
if (userRepository.existsByEmail(request.email())) {
throw new IllegalArgumentException("Email(`%s`) already exists.".formatted(request.email()));
}
if (userRepository.existsByUsername(request.username())) {
throw new IllegalArgumentException("Username(`%s`) already exists.".formatted(request.username()));
}
User newUser = this.createNewUser(request);
return userRepository.save(newUser);
}
}
And this is the decorated singUp method in a new class named ObservedUserService, which wraps our signUp method in an Observation
private static final String USER_CONTEXT = "user";
@Override
public User signUp(SignUpUserRequest request) {
Observation observation = Observation.start(USER_CONTEXT + ".signUp", this::createUserContext, observationRegistry);
try (Observation.Scope ignored = observation.openScope()) {
User registeredUser = userService.signUp(request);
observation.event(Observation.Event.of("signedUp", "User signed up"));
return registeredUser;
} catch (Exception ex) {
observation.error(ex);
throw ex;
} finally {
observation.stop();
}
}
private Observation.Context createUserContext() {
Observation.Context context = new Observation.Context();
context.addLowCardinalityKeyValues(KeyValues.of("context", "user"));
return context;
}
Since all we do is add some extra behavior, we applied the decorator pattern to introduce the observation, so that our business logic isn’t mixed with the additional observation abstraction. Notice that this code contains no Timer, Counter or logger.info – those low-level abstractions aren’t needed here. At last, we can concentrate on what matters. We want to know what goes on in our application: when it began (observation.start), when it ended (observation.stop), whether any errors occurred along the way (observation.error), or whether something significant happened during the process (observation.event) etc. . We describe what we want to observe, not how to accomplish it. Naturally, this is only a basic example of using the new API. The API offers much more, and I’m confident you’ll find something that suits your needs.
Fine – we can now focus on our intent, which is great, but how do we get metrics, logs, or traces when all we’ve done is add an observation? That’s where the ObservationHandler comes into play. All that remains is to register a particular handler instance in the ObservationRegistry.
Below is a fragment of the ObservationHandler code from the micrometer library, showing at which points of the observation’s lifecycle we can perform extra work.
public interface ObservationHandler<T extends Observation.Context> {
default void onStart(T context) {
}
default void onError(T context) {
}
default void onEvent(Observation.Event event, T context) {
}
default void onStop(T context) {
}
.
.
.
boolean supportsContext(Observation.Context context);
}
A few ObservationHandlers are already available out of the box. One of them is DefaultMeterObservationHandler, which creates Timer and Counter metrics for our Observation, so every observation gets measured for us. All we have to do is export the metrics to our metrics storage system. Let me show you how to expose metrics from observations for prometheus on a dedicated endpoint.
How to configure metrics for observations
The simplest approach is to use the spring-boot-starter-actuator module. Let’s add the required modules to our application in build.gradle.kts
implementation("org.springframework.boot:spring-boot-starter-actuator")
implementation(platform("io.micrometer:micrometer-bom:1.11.0"))
implementation("io.micrometer:micrometer-core")
implementation("io.micrometer:micrometer-registry-prometheus")
implementation("io.micrometer:micrometer-observation") // new micrometer module with observation API
Every line of this configuration should speak for itself.
The Spring configuration part
Next, let’s expose the metrics in prometheus format on an HTTP endpoint., For that, all we need is to set the exposed endpoints in our application.yaml file
management:
endpoints:
web:
exposure:
include: "health,metrics,**prometheus**"
That’s it – spring-boot will now create a DefaultMeterObservationHandler bean for us automatically, and here comes the spring magic: every bean of type ObservationHandler, along with a few others from the observations API, gets registered in the observation registry for us without any extra effort. This particular handler attaches Timer.Sample and Counter metrics to every observation. Isn’t that awesome!!!! Let me show you which metrics now appear in the prometheus metrics endpoint.
A fragment of the metrics endpoint response
...
# HELP user_signUp_seconds_max
# TYPE user_signUp_seconds_max gauge
user_signUp_seconds_max{error="none",} 0.147985042
# HELP user_signUp_seconds
# TYPE user_signUp_seconds summary
user_signUp_seconds_count{error="none",} 2.0
user_signUp_seconds_sum{error="none",} 0.219810917
...
Pretty great, but there’s one more thing I’d like to show you…
How to configure logs for observations
Would you like to add logging to this process? A ready-made handler for that already exists – ObservationTextPublisher – and all we need to do is register it as a spring bean.
@Configuration
public class ObservationLogsConfiguration {
private final Logger logger = LoggerFactory.getLogger(ObservationLogsConfiguration.class);
@Bean
public ObservationTextPublisher observationTextPublisher() {
return new ObservationTextPublisher(
logger::info,
context -> context
.getLowCardinalityKeyValues()
.stream()
.anyMatch(keyValue -> keyValue.getKey().equals("context") && keyValue.getValue().equals("user")),
Observation.Context::getName);
}
}
The first argument of ObservationTextPublisher is the message consumer – here, logger::info. The second argument, a Predicate<Observation.Context>, lets you limit the handler to chosen contexts; we added a simple filter based on low cardinality tags. The final argument is the converter that turns the context into a message, Function<Observation.Context, String> converter; we simply used the context name as the message.
Below are some logs produced by our process
...
c.s.r.a.c.ObservationLogsConfiguration : STOP - user.signUp
c.s.r.a.c.ObservationLogsConfiguration : START - user.login
c.s.r.a.c.ObservationLogsConfiguration : OPEN - user.login
...
Conclusion
Clearly, the new micrometer API together with spring-boot-actuator is extremely powerful. It lets us concentrate on intent rather than on low-level implementation details. It’s a fresh way of approaching observability, and I’m a fan!