What is Micrometer Tracing in Spring Boot and how do the pieces fit together?
Micrometer Tracing is easiest to understand as four stacked layers, each with one job.
The layers
- Observation API (instrumentation facade). Your code and Spring's own instrumentation describe what happened: an operation started, gained some key-value tags, maybe failed, then stopped. An
Observationdoes not decide whether that becomes a metric, a span or a log line. - Micrometer Tracing (tracing facade). It provides a vendor-neutral
Tracer, span and propagation abstraction, much as Micrometer core does for metrics. - Bridge. An OpenTelemetry or Brave bridge implements that facade and records the actual spans.
- Exporter. It ships finished spans to a backend, for example over OTLP or in Zipkin format.
What Spring Boot wires up
With Actuator, a tracing bridge and an exporter on the classpath, Spring Boot auto-configures an ObservationRegistry. It registers handlers on that registry and instruments inbound HTTP requests. It also instruments HTTP clients, but only those built from the auto-configured builders.
One observation, two signals
Handlers are what turn a single Observation into more than one signal. A meter handler records a timer, and a tracing handler opens and closes a span. Both handlers read the same observation name and low-cardinality tags. As a result, the latency metric on your dashboard and the span in your trace UI share a name, so you can move between them without keeping a mapping table up to date.
This model pays off most for backend and platform teams running several services, where correlating metrics, traces and logs across service boundaries is a daily need.
Dependency coordinates and property names have changed across Spring Boot generations. Check the reference documentation for your version before you copy any configuration.
+--------------------------------------------------------------+
| Application code + Spring instrumentation |
| (inbound HTTP, auto-configured HTTP client builders) |
+-----------------------------+--------------------------------+
| Observation: name + low-cardinality tags
v
+--------------------------------------------------------------+
| ObservationRegistry (auto-configured by Spring Boot) |
+-------------+---------------------------------+--------------+
| |
v v
+---------------------------+ +----------------------------+
| Meter handler | | Tracing handler |
| -> Micrometer timer | | -> Micrometer Tracing |
| (same name + tags) | | Tracer facade |
+-------------+-------------+ +-------------+--------------+
| |
v v
+---------------------------+ +----------------------------+
| MeterRegistry | | Bridge: OpenTelemetry or |
| -> metrics backend | | Brave (records spans) |
+---------------------------+ +-------------+--------------+
|
v
+----------------------------+
| Exporter (OTLP or Zipkin) |
| -> tracing backend |
+----------------------------+
A single Observation flows through the auto-configured ObservationRegistry, where a meter handler records a timer and a tracing handler opens a span, which the OpenTelemetry or Brave bridge records and the exporter ships, using the same name and low-cardinality tags.
How does it work at runtime?
The layers above describe structure. At runtime, one observation goes through a fixed lifecycle, and each step triggers callbacks on every registered ObservationHandler whose supportsContext method accepts the observation's context type.
- Start. When an observation starts, the registry first applies any
ObservationPredicatebeans. If a predicate rejects the observation, it becomes a no-op. Otherwise each handler'sonStartruns. The meter handler starts a timer sample. The tracing handler asks theTracerfor a new span. If a span is already current on the thread, the new span becomes its child. If not, the tracing handler starts a new trace, or continues one extracted from inbound headers. - Scope. Opening a scope (which
observe(...)does for you) makes the observation and its span current on that thread. This is what lets nested observations find their parent and lets the logging integration puttraceIdandspanIdinto the MDC. Closing the scope restores the previous state. - Error and events. If the wrapped code throws,
onErrorruns. The exception is attached to the context, the span is marked as failed, and the timer gets an error tag. - Stop. Before
onStop,ObservationFilterbeans and conventions get the final say over the name and key values. Then the meter handler stops the timer, recording duration under the observation name and low-cardinality tags. The tracing handler ends the span, with low-cardinality values as span tags and high-cardinality values added only to the span. - Propagation. For outbound calls, a sender-side tracing handler uses the configured propagator to write the current trace context into the request or message headers. On the receiving side, a receiver-side handler extracts it so the server span joins the same trace.
- Export. Finished spans go to the bridge, which hands them to the exporter. With the OpenTelemetry bridge, spans are normally batched and exported asynchronously, off the request thread. That is why a span can show up in the backend a moment after the request completes, and why export failures appear in logs rather than as request errors.
Sampling is decided when the root span is created. An unsampled span still exists so that context and IDs propagate, but it is not recorded or exported. The timer from step 4 is recorded either way.
Why use the Observation API instead of instrumenting metrics and traces separately?
With the Observation API, application code records one thing, "this operation happened, with these attributes," and registered handlers turn it into telemetry. A meter handler produces a timer, and a tracing handler produces a span. Without it, each important code path needs a timer sample and a span. Two calls means two sets of names and two error paths, and the two drift apart over time. With one observation, the metric name and span name come from the same source, and low-cardinality key values become both metric tags and span attributes. High-cardinality values such as an order ID go only to the span, which keeps cardinality out of your metrics backend.
Your code depends only on the observation abstraction, so the tracer is no longer a code decision. Moving from the Brave bridge to the OpenTelemetry bridge means changing dependencies and configuration. Service classes stay the same.
Adopt it by default in these cases:
- New services, where there is no existing instrumentation to migrate.
- Services already on Spring Boot with Actuator, where the framework's own HTTP, data and messaging instrumentation already emits observations.
- Teams standardising telemetry, where shared conventions can enforce naming across many repositories.
The cost is indirection. When a span goes missing, the cause could be in any of several layers:
- The observation was never started or stopped.
- No tracing handler was registered.
- Context was lost across a thread hop.
- The sampler dropped the trace.
- The exporter failed.
A no-op registry fails silently, so "nothing appeared" tells you very little. Debug from the inside out. First confirm the observation fires with a test registry, then check each layer outward to the exporter.
How can Micrometer Tracing save engineering time?
Most of the time savings come from work you no longer do, or no longer repeat:
- No hand-written instrumentation for common paths. Inbound HTTP, clients from the auto-configured builders, and messaging templates and listeners with observation enabled all produce timers and spans without application code. You only write observations for your own business operations.
- One call instead of two. Each custom observation replaces a separate timer and span, along with their duplicated naming and error handling. Code review has one thing to check, and metric and span names cannot drift apart.
- Faster cross-service debugging. With
traceIdin every log line and propagation set up across services, you can go from an alert to the trace, then filter logs from every service by one ID. Without that, you correlate timestamps across services by hand. - Backend changes without code changes. Switching between the Brave and OpenTelemetry bridges, or changing exporters, means changing dependencies and configuration rather than editing service classes across many repositories.
- Cheap regression protection. Tests using
TestObservationRegistrycatch a renamed observation or a dropped tag in CI, before it silently breaks a dashboard or alert in production. - Central policy instead of per-service edits. Predicates, filters and conventions defined once, for example in a shared configuration module, apply noise suppression and common tags to every observation in a service.
The savings depend on doing the setup properly. A service that creates clients with new RestTemplate() or loses context on thread hops gets broken traces, and debugging those can take longer than having no tracing.
How do you instrument custom code with observations?
For code your frameworks don't already instrument, wrap the unit of work explicitly: Observation.createNotStarted("order.checkout", registry), attach key values, then call .observe(() -> ...). observe starts the observation, opens a scope so the span becomes current, records any thrown exception as an error, and stops it. One call produces a timer and a span, and you never manage the lifecycle by hand.
@Observed gives the same result declaratively. It is enforced by ObservedAspect, so you need AspectJ on the classpath (typically via the AOP starter). Depending on your Boot version, you either register an ObservedAspect bean yourself or enable annotation support through configuration. Because it is proxy-based, self-invocation inside the same bean bypasses it.
Key values come in two kinds, and choosing the wrong one is the usual mistake:
| Low-cardinality | High-cardinality | |
|---|---|---|
| Becomes | Metric tag and span attribute | Span attribute only |
| Good examples | payment.method, outcome, region |
order.id, user.id, full URL |
| Risk if misused | One time series per distinct value | Negligible |
If you put user IDs, order IDs or raw URLs into low-cardinality values, every distinct value creates a new time series. Memory use and backend cost grow without limit. Keep identifiers high-cardinality, and template paths before you tag them.
Use an ObservationPredicate bean to suppress noise. It receives the name and context and returns false to drop the observation. A common use is skipping server requests whose path starts with /actuator, so health probes don't flood traces. To add common key values such as deployment environment, use an ObservationFilter. It mutates the context before handlers see it. To rename observations or reshape their tags, supply an ObservationConvention (or a global convention) instead of rewriting the instrumentation.
// Imports omitted. Assumes the Micrometer Observation API, Spring Boot 3.x and the AOP starter.
@Configuration
class ObservationConfig {
// Drop actuator and health-probe requests so they never become spans or timers.
@Bean
ObservationPredicate skipActuator() {
return (name, context) -> !(context instanceof ServerRequestObservationContext server
&& server.getCarrier().getRequestURI().startsWith("/actuator"));
}
// Add a bounded, common tag to every observation before handlers see it.
@Bean
ObservationFilter environmentTag() {
return context -> context.addLowCardinalityKeyValue(KeyValue.of("deployment.env", "staging"));
}
// Required for @Observed. Register this bean unless your Boot version enables it via config.
@Bean
ObservedAspect observedAspect(ObservationRegistry registry) {
return new ObservedAspect(registry);
}
}
@Service
class CheckoutService {
private final ObservationRegistry registry;
private final PaymentGateway gateway;
CheckoutService(ObservationRegistry registry, PaymentGateway gateway) {
this.registry = registry;
this.gateway = gateway;
}
Receipt checkout(Order order) {
return Observation.createNotStarted("order.checkout", registry)
.lowCardinalityKeyValue("payment.method", order.paymentMethod()) // small fixed set: metric tag + span attribute
.highCardinalityKeyValue("order.id", order.id()) // unbounded: span attribute only
.observe(() -> gateway.charge(order)); // start, scope, record error, stop
}
// Declarative equivalent. It is proxy-based, so calls from inside this class bypass it.
@Observed(name = "order.refund")
void refund(String orderId) { gateway.refund(orderId); }
}
This example wraps checkout in Observation.observe with low- and high-cardinality key values and shows @Observed with its ObservedAspect bean. It also uses an ObservationPredicate to drop /actuator requests and an ObservationFilter to add a common environment tag.
How does trace propagation work across HTTP clients, messaging and threads?
Propagation only happens where something both injects context on the way out and extracts it on the way in. Spring Boot handles this for clients built from the auto-configured RestTemplateBuilder, RestClient.Builder and WebClient.Builder. Those builders carry the ObservationRegistry and a propagator that writes trace headers on every outgoing request. A client created with new RestTemplate() never passes through that customization, so it sends no headers and records no client span. Inject the builder instead. Kafka and RabbitMQ templates and listeners follow the same model, but you must turn observation on for each through its observation-enabled properties. With it on, the producer writes headers into the message and the listener restores them before your handler runs.
Every service in a call path has to use the same header format, set with management.tracing.propagation.type (W3C traceparent or B3). A mismatch produces no error. The receiver finds no header it recognizes and starts a new trace, so a single request shows up as two unrelated traces in your backend.
Thread hops lose context because it lives in thread-locals. The Context Propagation library copies it across these hops:
- Executors: wrap them with
ContextExecutorService. @Asyncmethods: give the task executor aContextPropagatingTaskDecorator.- Reactor pipelines: enable automatic context propagation.
The symptoms point to the cause. A new root span at a service boundary means a header was missing or used the wrong format. Check the raw request or message headers to confirm. Blank trace IDs in logs that run partway through a request point to a thread hop that didn't carry context. Log the thread name next to the trace ID to find where the ID disappears.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskDecorator;
import org.springframework.core.task.support.ContextPropagatingTaskDecorator;
import org.springframework.web.client.RestClient;
@Configuration
class TracingPropagationConfig {
// Build from the auto-configured RestClient.Builder. It already carries the
// ObservationRegistry and propagator, so every request gets a client span
// and traceparent (or B3) headers.
@Bean
RestClient inventoryClient(RestClient.Builder builder) {
return builder.baseUrl("").build();
}
// Anti-pattern: RestClient.create() or new RestTemplate() bypasses the
// builder customizers, so no headers are sent. The downstream service
// then starts a new root span.
// Spring Boot applies a TaskDecorator bean to its auto-configured
// applicationTaskExecutor, which @Async methods use. This decorator
// captures thread-local context (current span, MDC trace IDs) on the
// calling thread and restores it on the worker thread.
@Bean
TaskDecorator contextPropagatingTaskDecorator() {
return new ContextPropagatingTaskDecorator();
}
}
// application.yml (illustrative):
// management.tracing.propagation.type: w3c # must match every service in the path
// spring.kafka.template.observation-enabled: true
// spring.kafka.listener.observation-enabled: true
// spring.reactor.context-propagation: auto # Reactor pipelines
Injecting the auto-configured RestClient.Builder so outgoing calls carry trace headers, and registering a ContextPropagatingTaskDecorator so @Async tasks keep the caller's trace context.
How do you use baggage and correlate trace IDs in logs?
Declare baggage in configuration before you set it in code. management.tracing.baggage.remote-fields lists the keys that propagate to downstream services. management.tracing.baggage.correlation.fields lists the keys that are also copied into the logging MDC. A field you set in code but never declare stays local to the process, which is usually not what you meant.
Set values at a request boundary, such as a servlet filter or message listener, after you have authenticated or parsed the inbound request. Use Tracer.createBaggageInScope(name, value) and close the returned scope in a finally block or try-with-resources. Leaving the scope open lets the value leak onto whatever work that thread runs next.
The MDC keys for trace correlation are traceId and spanId. Recent Spring Boot versions add both to the default console pattern. If you use a custom pattern or a JSON encoder, you must reference these keys yourself, or log lines will have nothing to link back to a trace.
To verify async behavior, write a test that logs inside an @Async method or executor task and asserts that its traceId matches the caller's. If the IDs are blank, the executor is not propagating context. Wrap the executor with Spring's ContextPropagatingTaskDecorator or a context-propagation wrapper to fix this.
Every remote field travels as a header on every outbound call, including calls to payment providers or external APIs. Keep the list short, and keep values small and non-sensitive. Tenant IDs are usually acceptable to send; user emails and internal role names are not. For third-party egress, drop baggage with a client interceptor or a separate client that has propagation disabled.
// Assumes application.yml declares the field before code sets it:
// management.tracing.baggage.remote-fields: tenantId
// management.tracing.baggage.correlation.fields: tenantId
import io.micrometer.tracing.BaggageInScope;
import io.micrometer.tracing.Tracer;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
@Component
public class TenantBaggageFilter extends OncePerRequestFilter {
private static final Logger log = LoggerFactory.getLogger(TenantBaggageFilter.class);
private final Tracer tracer;
public TenantBaggageFilter(Tracer tracer) { this.tracer = tracer; }
@Override
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
throws ServletException, IOException {
// In real code, take the tenant from the authenticated principal, not a raw header.
String tenantId = req.getHeader("X-Tenant-Id");
if (tenantId == null || tenantId.isBlank()) { chain.doFilter(req, res); return; }
// try-with-resources closes the scope so the value cannot leak to the thread's next task.
try (BaggageInScope scope = tracer.createBaggageInScope("tenantId", tenantId)) {
// MDC now holds traceId, spanId and tenantId, so this line links back to the trace.
log.info("Handling request for tenant");
chain.doFilter(req, res);
}
}
}
A servlet filter sets a declared remote baggage field at the request boundary, closes its scope with try-with-resources, and writes a log line whose MDC carries traceId, spanId and the correlated tenantId.
How should you configure sampling, and when does tracing hurt more than it helps?
Spring Boot controls trace sampling with management.tracing.sampling.probability, a value between 0.0 and 1.0. The default is low rather than 1.0. In local development, most requests therefore produce no exported span, and tracing can look broken when it is just unsampled. Set it to 1.0 in dev, and choose a deliberate value for production.
Sampling is head-based. The root service decides once, and the sampled flag travels in the propagation headers (for W3C, the traceparent flags). Downstream services follow that decision, so a trace is either complete or absent. Each hop does not re-roll the dice.
At 1% sampling, rare errors and slow outliers usually never appear as traces. Metrics are recorded from every observation regardless of sampling, so a timer can show 40 failures while you find two matching traces. This is expected. Use metrics to detect problems and traces to explain the samples you have.
Illustrative estimate. Assume 5,000 requests/s, 8 spans per request and about 1 KB per exported span. At 1.0, that is roughly 40 MB/s, or about 3.5 TB/day of span data. At 0.1, it is about 350 GB/day. Unsampled requests still pay for context creation and propagation.
Limit or skip tracing in these cases:
- Latency-critical hot paths: keep metrics on these and drop custom spans.
- Small single-service apps: metrics and logs are usually enough.
- The OpenTelemetry Java agent alongside Spring's instrumentation: the agent can create duplicate spans and run competing propagators. Pick one.
When should you use Micrometer Tracing, and when should you avoid it?
When to use it
- Spring Boot services that call each other. If a request crosses several services, queues or async workers, traces show where time goes and where failures start, which a per-service metric can't show.
- Teams that want metrics and traces from one instrumentation point. If you already rely on Micrometer timers, observations add spans to them without a second instrumentation effort.
- Organisations that may change tracing backends. Code depends on the Micrometer facade, so moving between Brave and OpenTelemetry, or between exporters, stays a dependency and configuration change.
- Services where logs need request correlation. Even at a low sampling rate, trace and span IDs in the MDC let you group every log line belonging to one request across services.
- Multi-tenant or routed systems that need small amounts of request context downstream. Declared baggage carries values like a tenant ID without threading them through every method signature.
When to avoid it
- Single-process applications with no remote calls. A trace with one service mostly repeats what the timer already says. Metrics and structured logs are cheaper and enough.
- Services already instrumented by the OpenTelemetry Java agent. Running both produces duplicate spans and competing propagators. Choose the agent or Micrometer Tracing per service, not both.
- Non-Spring or mixed codebases with an OpenTelemetry API standard. If most of your code uses OpenTelemetry types directly, adding a Micrometer facade on top adds a layer without a portability benefit.
- Extremely latency-sensitive inner loops. Creating an observation per iteration adds allocation and handler work. Instrument the enclosing operation instead, or use metrics only.
- Teams without a tracing backend or the capacity to run one. Spans that are never exported or never looked at cost CPU and memory for nothing. Start with metrics and add tracing when there is somewhere to send and query spans.
- Code paths that would carry sensitive data in baggage or span attributes. If you can't keep identifiers and personal data out of propagated fields and exported spans, fix that before you enable tracing on those paths.
How do you test observations, and what are the alternatives to Micrometer Tracing?
Testing observations directly is faster and more reliable than checking a tracing backend. The micrometer-observation-test module provides TestObservationRegistry. You inject it in place of the real registry, run the code, and assert that an observation with the expected name was started and stopped and carries the expected low- and high-cardinality key values. This catches renamed observations and missing tags, which silently break dashboards and alerts. To check span structure, such as parent-child relationships or error status, the micrometer-tracing-test module offers an in-memory SimpleTracer that records finished spans so you can assert on them without a running exporter.
Alternatives
| Option | Code coupling | Ecosystem fit | OTLP export | Debugging effort |
|---|---|---|---|---|
| Micrometer + OpenTelemetry bridge | Micrometer API only | Strong with Spring and the OTel collector | Native | Moderate, because there are two abstraction layers |
| Micrometer + Brave bridge | Micrometer API only | Strong for existing Zipkin setups | Needs extra components | Moderate |
| OpenTelemetry Java agent | None, bytecode instrumentation | Broad library coverage | Native | Higher, because behaviour is hidden in the agent |
| Direct OpenTelemetry API | Tight, OTel types in business code | Good outside Spring | Native | Low, because what you write is what runs |
| Micrometer metrics only | Micrometer API only | Strong in Spring | Metrics only, no traces | Lowest |
For new Spring Boot services, choose the OpenTelemetry bridge. Choose Brave if Zipkin is already in place. Use the agent for services you can't modify.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to micrometer tracing spring boot, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.