Unlock Full Observability in Spring Boot 3: Micrometer Observation API Explained

Preface

Spring observability team adds support for metrics, logging and distributed tracing in Spring Framework 6 and Spring Boot 3, making it easier to understand application internal state.

Spring Boot 3.0.0‑RC1 will include auto‑configuration for Micrometer metrics and Micrometer tracing (formerly Spring Cloud Sleuth). It adds built‑in log correlation, W3C context propagation as default, and automatic metadata propagation for tracing infrastructure.

The idea is to let users detect code with a single API and obtain metrics, tracing and logging information.

1. How Micrometer Observation works

Register an ObservationRegistry and ObservationHandler. The handler only works with supported Observation.Context. The lifecycle methods create timers, spans, etc. start – call Observation#start() to start. stop – call Observation#stop() to stop. error – call Observation#error(exception) to record error. event – call Observation#event(event) for custom events. scope started – call Observation#openScope() to open a scope. scope stopped – call Observation.Scope#close() to close the scope; handlers such as onStart and onStop are invoked.

Observation state diagram:

Observation          Observation
Context              Context
Created --> Started --> Stopped

Observation scope state diagram:

Observation
Context
Scope Started --> Scope Closed

For production debugging, observations can carry extra metadata (tags) that can be used to query metrics or tracing back‑ends. Tags may be high‑cardinality or low‑cardinality.

2. Building an observable application

2.1 WebMvc service

Start with spring-boot-starter-web, add spring-boot-starter-aop for @Observed support, and spring-boot-starter-actuator with Micrometer on the classpath.

Metrics : add io.micrometer:micrometer-registry-prometheus.

Tracing : add a tracer bridge, e.g., io.micrometer:micrometer-tracing-bridge-brave and io.zipkin.reporter2:zipkin-reporter-brave for Zipkin‑compatible spans.

Logs : use com.github.loki4j:loki-logback-appender to push logs to Loki.

Configuration example ( application.properties) sets server port, application name, sampling probability, Prometheus endpoint exposure, histogram buckets, and log pattern including trace and span IDs.

Logback configuration ( logback-spring.xml) defines a Loki appender with HTTP URL and label pattern.

2.2 Server code

Controller logs request and calls a service. The service method is annotated with @Observed (name="user.name", contextualName="getting-user-name", lowCardinalityKeyValues={"userType","userType2"}). This creates a timer ( user.name), a long‑task timer ( user.name.active) and a span ( getting-user-name).

A custom MyHandler implements ObservationHandler<Observation.Context> to log before and after each observation.

Register an ObservedAspect bean and an HttpRequestsObservationFilter for URLs matching /user/*.

2.3 RestTemplate client

Add spring-boot-starter-web and spring-boot-starter-actuator. Configure Prometheus, tracing (OpenTelemetry bridge and Zipkin exporter), and Loki appender similarly to the server.

Define a RestTemplate bean using RestTemplateBuilder. A CommandLineRunner creates a manual observation ( my.observation) with low‑cardinality userType and high‑cardinality userId, then sends a request to the server, logging within the observation scope.

2.4 Running the example

Use docker-compose up to start Prometheus, Grafana, Loki and Tempo. Run the server ( ./mvnw spring-boot:run -pl :server) and client ( ./mvnw spring-boot:run -pl :client). Observe logs, traces and metrics in Grafana, using trace IDs to correlate data.

2.5 Native image support

Build native images with GraalVM (e.g., sdk install java 22.2.r17-nik) and Maven profile native. Run the native server and client binaries.

3. Summary

The article introduced the Micrometer Observation API, showed how to use the API and @Observed annotation to add custom observability, visualized latency, correlated logs, and inspected metrics. It also covered native image execution.

Next steps include community‑driven improvements and a GA release planned for November.