Observability & Tracing · OpenTelemetry course

Lesson 03

The Spring Boot 3.x tracing stack, layer by layer

This is the lesson that dissects “a lot of setup” from your meeting — core tracing, then Spring, then Micrometer. There are five layers and three dependencies, and each owns exactly one job. Once you can name the owner of every line, the config stops being magic.

Start with the boundary, not the layers

No. And that single answer is worth more than the rest of the lesson, because almost everyone assumes otherwise. Actuator is not a stage in the pipeline. It is the thing that builds the pipeline at startup and then steps out of the data path. Your telemetry never travels through it.

There are two entirely different axes here, and confusing them is the root of most Spring tracing confusion:

Actuator is the vertical arrow in the second block. It is never a box in the first.

Layer 1 — the Observation API: instrument once

Your code does not create spans. It creates Observations. The Micrometer Observation API exists for one stated reason: “Instrument code once, and get multiple benefits out of it.”^[micrometer] One Observation can become a timer, a span, a log — or all three — depending on what is listening.

Spring Boot's own words: “For metrics and traces, Spring Boot uses Micrometer Observation.”^[boot] And you mostly do not write them by hand — Spring MVC controllers and Spring Data repositories are already instrumented for you.

Layer 2 — the registry and its handlers

An Observation is reported to the ObservationRegistry. Registered ObservationHandlers are notified as it starts, stops or errors. Boot wires this for you: “Beans of type ObservationPredicate, GlobalObservationConvention, ObservationFilter and ObservationHandler will be automatically registered on the ObservationRegistry.”^[boot]

Micrometer Tracing contributes the tracing handler. That handler is the moment an Observation becomes a span — “Whenever an Observation is used, a corresponding span is created, started, stopped and reported.”^[tracing]

Layer 3 — the Tracer facade

The handler does not call OpenTelemetry. It calls Tracer, Micrometer Tracing's vendor-neutral facade — “a simple facade for the most popular tracer libraries.”^[tracing] Exactly the SLF4J pattern, applied to tracing instead of logging.

This layer is why your application code contains no OpenTelemetry imports at all.

Layer 4 — the bridge: the actual crossing

Something has to implement Tracer using a real tracing library. That is the bridge, and it is the single point where your application crosses into OpenTelemetry:

Inside the bridge — what “bridge” actually means

One per interface. The bridge is a textbook adapter: for every type in Micrometer's tracing API there is an Otel-prefixed class that implements it by wrapping the equivalent OpenTelemetry object. Here is the real package, io.micrometer.tracing.otel.bridge:^[source]

Nothing clever is happening. Each class holds a reference to the OTel object and forwards to it. Straight from OtelTracer.java:

That is the entire trick. Micrometer's interface on the outside, OpenTelemetry's object on the inside, one delegating call between them. [OtelTracer.java]

Follow one span all the way through

Concretely, when Spring MVC handles a request:

Why there are three tracing handlers, not one

Micrometer Tracing ships a small family of handlers, and which one runs decides the span's kind and whether context propagation happens:^{[handler package]}

So the inject/extract machinery from Lesson 2 is not somewhere else in the stack — it is these two handlers, calling through the same bridge into OtelPropagator. That is why one dependency swap changes both how spans are made and how headers are written.

The bridge does more than spans

Two classes in that package pay off things you have already met:

• Slf4JEventListener — this is your log correlation. Its javadoc: “Reacts to events with updating of Slf4j's MDC.” On span scope open it calls MDC.put("traceId", …) and MDC.put("spanId", …), and removes them when the scope closes. That is the entire mechanism by which a trace ID appears in a log line — no magic, just an MDC write keyed traceId and spanId by default.^{[Slf4JEventListener]}
• BaggageTaggingSpanProcessor — copies configured baggage entries onto spans as tags. This is the machinery behind management.tracing.baggage.tag-fields, and therefore the fix for the Lesson 2 trap where baggage never showed up in Jaeger.

Now the swap claim is concrete rather than a slogan. Changing to micrometer-tracing-bridge-brave substitutes a parallel package of Brave-prefixed adapters implementing those same interfaces. Your code, Spring's instrumentation and the handlers all still talk to Tracer, Span and TraceContext — so nothing above the bridge notices.

Layer 5 — the OTel SDK and the exporter

Past the bridge you are in the territory from Lesson 1. The SDK applies the sampling decision, batches spans, and stamps them with the Resource — including service.name. The exporter serialises to OTLP and puts it on the wire, over HTTP :4318 or gRPC :4317.

The three dependencies, and what each buys

Boot's docs: “Spring Boot Actuator provides dependency management and auto-configuration for Micrometer Tracing.” [src]

Three artifacts, three jobs: wire it, cross into OTel, put it on the wire. Adding the bridge alone does nothing — no auto-configuration runs without Actuator. That is your meeting's “a lot of setup,” and it is genuinely only three lines.

The config, and the two traps

Both warnings cost people days:

• Sampling defaults to 0.1. Out of the box you export 10% of traces, so the one test request you are watching for usually vanishes. Set 1.0 in dev.
• endpoint has had no default since Boot 3.2. The OTLP span exporter bean is only auto-configured when that property has a value; before 3.2 it defaulted to http://localhost:4318/v1/traces. On 3.2+ omitting it means spans are produced and then go nowhere. Everything looks wired. Nothing arrives.

Note also that transport defaults to http, so Actuator wires an HTTP exporter aimed at :4318. A config pointing at :4317 while transport is still http is a misconfiguration worth catching in review.

Other defaults you now own: management.tracing.enabled = true; batching at max-queue-size 2048, max-batch-size 512, schedule-delay 5s; and propagation.consume = [W3C, B3, B3_MULTI] — the traceparent header from Lesson 2.^{[boot props]}

The other route — the Java agent

Everything above is the library route: Spring produces the telemetry, in-process, from dependencies you declared. There is a second, completely different way to instrument the same app, and you should be able to recognise it on sight.

The agent “dynamically injects bytecode to capture telemetry from many popular libraries and frameworks” at class-load time, covering “inbound requests, outbound HTTP calls, database calls, and so on” — with no code or dependency changes at all.^[agent] Spring is never consulted; the agent rewrites the classes as they load.

Running both at once is a known source of duplicate spans. So the first question to ask your team is which route this project is on — because if it is the agent, none of the management.* properties above apply.

Prove it — recall drill

Everything the questions ask about is in this recap, so you do not have to scroll back for it.

Primary source — read this next

Fifteen minutes on Spring Boot → Actuator → Tracing, then open your own build.gradle beside it and name the owner of every tracing line. That exercise is the win for this lesson. Pin the versioned URL that matches your project's exact minor — the live docs drift.