What is Micrometer Tracing and how does it work in Spring Boot?
If you run Spring Boot services that call each other over HTTP or messaging, you need to see where a request spends its time across those hops. Micrometer Tracing is one part of a small stack that does this.
The pieces
- Observation API. Your code, or Spring's built-in instrumentation for things like web requests and HTTP clients, wraps an operation in an
Observation. It records the start, the stop, any error, and a set of key-value tags. It does not decide whether the result becomes a metric or a trace. - Observation handlers. Handlers registered on the
ObservationRegistryreact to each observation's lifecycle. A meter handler turns the observation into a timer. A tracing handler turns the same observation into a span. - Micrometer Tracing. This is a vendor-neutral facade (
Tracer,Span, baggage) over a tracer bridge. The usual bridge is OpenTelemetry, so the spans are real OpenTelemetry spans underneath. - Propagators. These write trace context and baggage into outgoing request headers and read them on the receiving side. That is how a span in one service becomes the parent of a span in the next.
- Exporter. Finished spans are batched and sent, typically over OTLP, to a collector. The collector forwards them to your tracing backend.
How it works, step by step
Here is the path of a single request through two services:
- A request arrives at service A. Spring's server instrumentation starts an observation for the incoming HTTP request.
- The tracing handler starts a span. Before it creates the span, the propagator reads the incoming headers. If they carry a trace context, the new span becomes a child of the caller's span. If they don't, it becomes a new root span with a new trace ID.
- Context becomes current. The span is made current on the request thread, and its
traceIdandspanIdare written into the logging MDC. Every log line written while handling the request carries those IDs. - Service A calls service B. A client built from an auto-configured builder starts a child observation for the outbound call. The tracing handler creates a client span, and the propagator injects the trace context and any allow-listed baggage into the request headers.
- Service B repeats step 2. It reads those headers, so its server span is a child of A's client span. Both spans share one trace ID.
- Observations stop. When each operation finishes, its observation stops. The meter handler records the duration in a timer, and the tracing handler ends the span and hands it to the SDK's batch processor.
- Spans are exported. The exporter sends batches of finished spans over OTLP to a collector. The backend reassembles them into one trace tree using the shared trace ID and the parent span IDs.
Why one instrumentation point matters
Without the Observation API, you write a timer and a span for every operation and keep their names and tags aligned by hand. They drift: a tag gets added to the metric but not the span, or a rename happens on one side only.
With one observation per operation, both signals get identical names and tags from a single call. You can jump from a latency spike on a dashboard to traces for that same operation without translating between two naming schemes. You also maintain one piece of instrumentation code instead of two.
+---------------------------------------+
| Your code / Spring instrumentation |
+---------------------------------------+
|
v
+---------------------------------------+
| Observation: start, stop, error, tags |
+---------------------------------------+
|
v
+---------------------------------------+
| ObservationRegistry -> handlers |
+---------------------------------------+
| |
v v
+------------------+ +-----------------------+ +---------------------+
| Meter handler | | Tracing handler | | Service B |
| -> Timer | | -> Micrometer Tracing | | propagator reads |
| (metrics) | | (Tracer facade) | | headers; new span |
+------------------+ | -> OTel bridge: spans | | is a child of A's |
+-----------------------+ +---------------------+
| | ^
| +---------------------+
| propagator: trace context
v + baggage in request headers
+----------+ OTLP +-----------+ +---------+
| Exporter |----->| Collector |-->| Backend |
+----------+ +-----------+ +---------+
One Observation feeds both a meter handler (timer) and a tracing handler (span via Micrometer Tracing over the OpenTelemetry bridge); propagators carry context to the next service, and the exporter sends finished spans over OTLP to a collector and on to the tracing backend.
Who should use Micrometer Tracing?
Micrometer Tracing fits best when most of these are true:
- You run several Spring Boot services that call each other. Tracing is most useful when a request crosses process boundaries, over HTTP or messaging, and you need to see which hop is slow or failing.
- You already use Micrometer for metrics. If your dashboards are built on Micrometer timers, the Observation API gives you spans with the same names and tags. Your metrics and traces then share one vocabulary.
- You want to stay vendor-neutral. Code depends on the Observation API and the Micrometer Tracing facade, not on a specific backend. With OTLP export through a collector, you can change backends with configuration instead of code changes.
- You want instrumentation you can see and test. Custom spans live in your source code, are reviewed like other code, and can be asserted in unit tests.
It is a weaker fit in a few cases. A single monolith with simple call paths usually gets more value from metrics and structured logs. Services you cannot modify, and mixed fleets of non-Spring JVM services, are often better served by the OpenTelemetry Java agent. Teams with a working Brave/Zipkin setup and no plan to migrate can stay on the Brave bridge. The last section of this article covers these alternatives.
How do you set up Micrometer Tracing with OpenTelemetry in Spring Boot?
Three dependencies are enough. Spring Boot Actuator brings in the auto-configuration that wires tracing together. micrometer-tracing-bridge-otel lets Micrometer's tracer abstraction delegate to the OpenTelemetry SDK. opentelemetry-exporter-otlp sends finished spans to a collector or backend over OTLP. Let Spring Boot's dependency management choose the versions. Bridges and exporters with mismatched versions often fail quietly instead of at startup.
Next, set management.tracing.sampling.probability. The default is low, so most requests are never recorded. When you send a handful of requests locally, it can look like tracing is broken when it is only sampling. Set the value to 1.0 in development and choose a lower rate deliberately for production.
What gets instrumented for free
Incoming HTTP requests are traced automatically. Outgoing calls are traced only when the client is built from the auto-configured RestTemplateBuilder, RestClient.Builder or WebClient.Builder. Spring Boot customizes those builders with the ObservationRegistry and the interceptors or filters that create client spans and inject trace headers. A client created with new RestTemplate() skips the builder entirely, so it never receives any of that. The call still succeeds, but the downstream service starts a new, unrelated trace. Inject the builder and call build() on it.
Log correlation
The tracer puts traceId and spanId into the logging MDC. Make sure your log pattern prints them, using %X{traceId} and %X{spanId}. Depending on your Boot version, the default pattern may already include them. If it does not, add them through logging.pattern.level or your Logback configuration. You can then copy the trace ID from any log line and find the matching trace in your backend.
spring:
application:
name: order-service
management:
tracing:
sampling:
# Record every request locally so traces don't appear to be missing.
# Choose a lower rate deliberately for production.
probability: 1.0
otlp:
tracing:
# OTLP over HTTP. Set OTLP_TRACING_ENDPOINT to your collector's
# OTLP/HTTP traces endpoint (the OTLP/HTTP receiver conventionally
# listens on port 4318, with traces under the /v1/traces path).
endpoint: ${OTLP_TRACING_ENDPOINT}
logging:
pattern:
# Print the traceId and spanId that the tracer puts into the MDC.
# The ':-' fallback prints nothing when a line is logged outside a span.
level: "%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]"
A development configuration that samples every request, exports spans over OTLP/HTTP and adds traceId and spanId to each log line for trace correlation.
How do you create custom spans with the Observation API?
Auto-instrumentation covers framework boundaries such as incoming HTTP requests and outgoing client calls. To trace the work between those boundaries, you create observations yourself. The Observation API gives you two ways to do this.
Programmatic observations
Observation.createNotStarted(name, observationRegistry) builds an observation. You attach key-values to it, then call .observe(...) with the code to measure. The observation starts, runs your code, records any exception, and stops, even if the code throws. One observation can produce a timer and a span, depending on which handlers are registered.
The @Observed annotation
@Observed on a method does the same thing declaratively. It does nothing until you register an ObservedAspect bean and have AOP on the classpath. It also follows Spring AOP proxy rules. If one method calls another method on the same object, that internal call bypasses the proxy and is not observed.
Choosing key-value cardinality
Low-cardinality key-values become metric tags and span attributes. High-cardinality key-values go only on spans. Every distinct tag combination creates a separate time series. If you put a user ID or request ID in the low-cardinality bucket, you create one series per user or per request. That can exhaust memory in the application and storage in your metrics backend. Put a value in the low-cardinality bucket only if it comes from a small, bounded set, such as an operation type or an outcome.
Covering what auto-instrumentation misses
Auto-instrumentation does not see:
- custom thread handoffs
- raw JDBC calls
- in-house frameworks
Work in these places either shows up as unexplained self-time on a parent span or lands in a disconnected trace. You then see a long parent span with nothing underneath it. That time is real, but it is unattributed rather than unexplained latency. Wrapping the untraced work in a custom observation turns that gap into named child spans you can measure.
import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;
import io.micrometer.observation.annotation.Observed;
import io.micrometer.observation.aop.ObservedAspect;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Service;
@Configuration
class ObservationConfig {
// Without this bean (and AOP on the classpath), @Observed does nothing.
@Bean
ObservedAspect observedAspect(ObservationRegistry registry) {
return new ObservedAspect(registry);
}
}
@Service
class InvoiceService {
private final ObservationRegistry registry;
InvoiceService(ObservationRegistry registry) { this.registry = registry; }
// Programmatic: wraps the raw JDBC work that auto-instrumentation can't see.
Invoice load(String invoiceId, String userId) {
return Observation.createNotStarted("invoice.load", registry)
.lowCardinalityKeyValue("source", "jdbc") // bounded set: metric tag + span attribute
.highCardinalityKeyValue("invoice.id", invoiceId) // unbounded: span only
.highCardinalityKeyValue("user.id", userId) // never a metric tag
.observe(() -> queryInvoice(invoiceId)); // stops and records errors even if it throws
}
// Declarative: only observed when called through the Spring proxy, not via this.render(...).
@Observed(name = "invoice.render", lowCardinalityKeyValues = {"format", "pdf"})
byte[] render(Invoice invoice) { return new byte[0]; }
private Invoice queryInvoice(String id) { return new Invoice(id); }
}
record Invoice(String id) {}
A programmatic Observation around raw JDBC work and an @Observed method enabled by an ObservedAspect bean, with bounded values as low-cardinality tags and IDs as high-cardinality span-only attributes.
How do trace propagation and baggage work across services?
Spans only join into one trace if each hop reads the context the previous hop wrote. Spring Boot supports two header formats:
| W3C Trace Context | B3 | |
|---|---|---|
| Headers | traceparent, tracestate |
X-B3-* multi-header, or single b3 |
| Origin | W3C standard, OpenTelemetry default | Zipkin ecosystem |
| Baggage carrier | Separate W3C baggage header |
No standard; implementation-specific |
Set the format with management.tracing.propagation.type. Every service, gateway and mesh proxy in the path must agree on it. A hop that does not recognise the incoming header does not raise an error. It starts a new root span, and the trace quietly splits into unrelated fragments. When migrating from B3 to W3C, set the property to w3c,b3 so that services emit both formats until the last B3-only component has been upgraded.
Baggage is a set of key-value pairs that travel with the context. List names under management.tracing.baggage.remote-fields so they cross process boundaries. List them under management.tracing.baggage.correlation.fields so they appear in the MDC and your log lines. In code, call tracer.createBaggageInScope(name, value) inside a try-with-resources block to set a value, and use tracer.getBaggage(name) to read one.
Span tags stay on the local span. Baggage is sent downstream on every outbound call. That has consequences:
- Each field increases header size on every request.
- Tenant or user identifiers can reach third-party APIs.
- Callers can forge values, so never use incoming baggage for authorization.
Allow-list the fields you need, and strip baggage at ingress and egress trust boundaries.
management:
tracing:
propagation:
# Migration window: emit and accept both W3C and B3 headers.
# Switch to 'w3c' only after the last B3-only service, gateway
# or mesh proxy has been upgraded. A hop that cannot read the
# incoming header starts a new root span and reports no error.
type: w3c, b3
baggage:
# Allow-list: only these keys cross process boundaries.
# Each one is added to every outbound request, so keep the list short.
# Never put user identifiers, emails or tokens here.
remote-fields:
- tenant-id
- request-origin
correlation:
# Copy these keys into the MDC so they appear in log lines.
fields:
- tenant-id
Spring Boot tracing configuration that emits both W3C and B3 headers during a migration, propagates an allow-listed set of baggage fields, and copies one of them into the MDC for logging.
Why do traces break in async and reactive code, and how do you fix it?
Trace context lives in thread-local state. The current span and the traceId/spanId values in the logging MDC are bound to the thread handling the request. When work moves to another thread, such as a pool task, an @Async method, or a Reactor operator that switches schedulers, that state stays on the original thread. The new thread starts with no current span. Any span it creates becomes a new root, and its log lines have no trace fields.
Fixing executors and @Async
Wrap executors so that each task captures the caller's context when it is submitted and restores it on the worker thread. The Micrometer Context Propagation library provides wrappers for Executor and ExecutorService. Spring provides ContextPropagatingTaskDecorator, which you can register as a TaskDecorator on the executor that backs @Async. Check every executor you define yourself. A bean you build by hand does not pick up decorators automatically.
Fixing Reactor
Reactor carries context in its subscriber Context, not in thread locals. Enable automatic context propagation, either through Reactor's hook or through Spring Boot's context-propagation property. Once it is enabled, thread-local values are restored when operators hop between schedulers.
Detecting breakage
Context loss produces no error. You only see it in the output:
- Disconnected root spans: short traces that start in a background method instead of at an HTTP or messaging entry point.
- Missing
traceIdin logs: log lines from worker threads have empty trace fields. - Unexpected parents: a span attached to the wrong request, usually because a pooled thread kept stale context from earlier work.
Add a test that checks the parent-child relationship of spans across every async boundary and thread hop, so stale context fails the build instead of showing up on a dashboard.
How should you export spans and test that instrumentation works?
Export through a collector
Point the application at an OpenTelemetry Collector running as a sidecar or node agent, not at a vendor backend. Set management.otlp.tracing.endpoint to the collector's local OTLP address. The application then needs only one fast, nearby hop. Retries, authentication, sampling and routing all live in the collector, so changing backends does not require a redeploy.
The SDK batches spans in memory and exports them on a timer or when the batch fills. That buffer creates two failure modes:
- Lost spans on shutdown: a crash,
SIGKILLor a container killed before its grace period ends discards everything still queued. That is often the trace you most need. Enable graceful shutdown and give the pod enough termination time for the final flush. - Silent drops under backpressure: when the exporter cannot keep up, the queue fills and new spans are discarded with no error in the request path. Watch the SDK's dropped-span signals or the collector's receiver metrics.
To check the export path locally, run a collector with an OTLP receiver wired to the debug exporter. It prints each span it receives, which shows whether names, attributes, baggage-derived tags and parent IDs actually arrived.
Assert instrumentation in tests
Inject a TestObservationRegistry and use its assertions to verify that an observation with the expected name and low-cardinality keys was started and stopped. For spans, micrometer-tracing-test provides a SimpleTracer and span assertions that check names, tags and parent-child links. These tests catch an instrumentation regression in CI, where it is cheap to fix, instead of during an incident.
How can Micrometer Tracing save engineering time?
Most of the time saved comes from shorter investigations and from writing less instrumentation code.
- Faster incident triage. Without tracing, finding a slow request across services means searching each service's logs by timestamp and guessing which lines belong to the same request. With trace IDs in every log line and a trace tree in the backend, you open one trace and see which hop took the time or threw the error.
- Less instrumentation to write and maintain. Server requests and builder-based HTTP clients are instrumented without code. Where you do add code, one observation gives you both the timer and the span, so you don't keep two sets of names and tags in sync.
- Gaps become visible. A long parent span with no children points directly at the untraced code. You add one observation there instead of adding timing logs across several candidate methods.
- Regressions caught early. Tests built on
TestObservationRegistryandmicrometer-tracing-testfail in CI when a refactor drops an observation or breaks context propagation. Without them, you find out during the next incident, when the trace you need is missing. - Backend changes without code changes. Because services export OTLP to a collector, switching or adding a tracing backend is a collector configuration change, not a change rolled out to every service.
Illustrative estimate
The following is an illustrative estimate. Every input is assumed, not measured, so substitute your own figures.
- Assumed: 4 cross-service latency or error investigations per month.
- Assumed: each one takes 3 engineer-hours when reconstructed from per-service logs.
- Assumed: each one takes 1 engineer-hour with correlated traces and logs.
Under these assumptions, investigations take 8 fewer engineer-hours per month (4 × (3 − 1)). Against that, count the one-time setup work: adding dependencies, configuring propagation and executors, and writing custom observations and tests. Also count the ongoing cost of collector infrastructure and backend storage. If your own numbers show few cross-service investigations, the savings may not cover those costs. The next section covers that case.
When should you avoid Micrometer Tracing, and what are the alternatives?
Tracing cost scales with sampling rate and span volume. Every sampled request allocates span objects, serializes them and ships them to a backend that bills or provisions storage by volume. Head-based sampling at a fixed probability is decided when the trace starts, so it costs almost nothing. It also discards most of the rare error traces you wanted. Tail sampling in a collector keeps traces based on outcome, such as errors or high latency. The price is buffering every span until the trace completes and running extra collector infrastructure sized for that memory.
| Option | Fits when | Development cost |
|---|---|---|
| Micrometer Tracing | Spring Boot apps that want traces and metrics from one Observation API | Low for framework paths, moderate for custom spans |
| OpenTelemetry Java agent | You can't change code, or you run mixed non-Spring JVM services | Near zero code, but less control over span shape |
| OpenTelemetry API/SDK directly | Libraries or non-Spring code that must stay vendor-neutral | Highest: you wire context and exporters yourself |
| Brave bridge | Existing Zipkin/B3 infrastructure you're not migrating | Low if Brave is already in place |
| Metrics-only Micrometer | Single service or simple call graphs where dashboards answer most questions | Lowest |
Don't run Micrometer Tracing alongside the OpenTelemetry agent. Both instrument the same HTTP and JDBC calls, which produces duplicate spans. They can also register conflicting propagators that break parent-child links. Pick one instrumentation path per service.
Weigh setup effort against debugging time saved. Distributed tracing pays off once a request crosses several services and nobody can reconstruct its path from logs. For a single monolith, metrics plus structured logs with a correlation ID are usually enough.
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.