Spring Boot 4 Complete Guide · 课时

上下文传播与跨度插桩

使用 Micrometer Observation 和 OpenTelemetry，跨线程和服务传播跟踪上下文。

上下文传播与跨度插桩 是 CoddyKit 上的免费 Spring Boot 4 Complete Guide 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Spring Boot 4 Complete Guide 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Spring Boot 4 Complete Guide 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Context Propagation Matters

In a distributed system, a single user request hops across threads, queues, and services. Distributed tracing stitches these hops together using a shared trace context (a trace ID plus the current span ID).

If the context is lost, your trace breaks into disconnected fragments.
Spring Boot 4 uses Micrometer Observation as the unified API and OpenTelemetry (or Brave) as the tracing bridge.
The challenge: keep the active span attached as work crosses thread and process boundaries.

This lesson shows how to instrument spans and propagate context both in-process (across threads) and across services (over HTTP/messaging headers).

The Observation API

Micrometer's ObservationRegistry is the entry point. An Observation abstracts both metrics and a tracing span, so one instrumentation point feeds both pillars.

Observation.createNotStarted(name, registry) builds it.
observe(Runnable) opens a scope, runs the code, and closes it — making the span the active one for the current thread.

While the scope is open, any nested instrumentation (HTTP client, JDBC, logging MDC) automatically becomes a child span.

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

@Service
public class OrderService {

    private final ObservationRegistry registry;

    public OrderService(ObservationRegistry registry) {
        this.registry = registry;
    }

    public Order place(Long id) {
        return Observation.createNotStarted("order.place", registry)
            .lowCardinalityKeyValue("order.type", "standard")
            .observe(() -> doPlace(id));
    }

    private Order doPlace(Long id) {
        // child spans created here join the same trace
        return new Order(id);
    }
}

High vs Low Cardinality Tags

Observation key-values become both metric tags and span attributes. Choosing the right cardinality is a key decision:

lowCardinalityKeyValue: bounded values (HTTP method, status, region). Safe for metric dimensions.
highCardinalityKeyValue: unbounded values (user ID, order ID). Attached only to the span, never to metrics, to avoid a tag explosion.

Putting a user ID into a low-cardinality tag would create one time series per user and overwhelm your metrics backend.

Observation.createNotStarted("order.place", registry)
    .lowCardinalityKeyValue("order.type", order.getType())   // bounded -> metric + span
    .highCardinalityKeyValue("order.id", order.getId().toString()) // span only
    .observe(() -> process(order));

The Active Span and Thread-Locals

OpenTelemetry stores the current Context in a thread-local. Micrometer mirrors this with an Observation scope that is also thread-bound.

Inside observe(...), Span.current() returns the live span.
The moment you hand work to another thread (executor, CompletableFuture, reactive scheduler), the thread-local is empty there — the span does not follow automatically.

This is the root cause of broken traces in async code. The next scenes fix it.

import io.opentelemetry.api.trace.Span;

public void log() {
    Span span = Span.current();
    System.out.println("traceId=" + span.getSpanContext().getTraceId());
}

Propagating Across Threads with ContextSnapshot

Micrometer's context-propagation library captures all registered thread-local values into a ContextSnapshot and restores them in another thread.

Capture on the producing thread with ContextSnapshotFactory.captureAll().
Restore inside the worker by wrapping the task with snapshot.wrap(runnable).

This carries the OpenTelemetry context and Observation scope so the worker's spans join the original trace.

import io.micrometer.context.ContextSnapshot;
import io.micrometer.context.ContextSnapshotFactory;
import java.util.concurrent.ExecutorService;

public void runAsync(ExecutorService pool) {
    ContextSnapshot snapshot = ContextSnapshotFactory.builder().build().captureAll();
    pool.submit(snapshot.wrap(() -> {
        // active span here is the same as on the calling thread
        doWork();
    }));
}

Auto-Propagating Executors

Wrapping every task by hand is error-prone. Instead, decorate the executor once so every submitted task captures and restores context automatically.

ContextExecutorService.wrap(delegate, () -> ContextSnapshot.captureAll()) from context-propagation, or
Spring's ContextPropagatingTaskDecorator on a ThreadPoolTaskExecutor.

With Spring Boot 4, registering the task decorator means @Async methods keep the trace context with no per-call code.

import org.springframework.core.task.support.ContextPropagatingTaskDecorator;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

@Bean
public ThreadPoolTaskExecutor applicationTaskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(8);
    executor.setTaskDecorator(new ContextPropagatingTaskDecorator());
    executor.initialize();
    return executor;
}

Creating Custom Spans Manually

Sometimes you need a span around a specific block without a full Observation. Inject the Micrometer Tracer and manage the span explicitly.

tracer.nextSpan().name("...").start() creates a child of the current span.
Open a SpanInScope with tracer.withSpan(span) so nested code sees it as current.
Always end() in a finally block, and record errors with span.error(ex).

import io.micrometer.tracing.Span;
import io.micrometer.tracing.Tracer;

public void doImport(Tracer tracer) {
    Span span = tracer.nextSpan().name("file.import").start();
    try (Tracer.SpanInScope ws = tracer.withSpan(span)) {
        parseAndStore();
    } catch (RuntimeException ex) {
        span.error(ex);
        throw ex;
    } finally {
        span.end();
    }
}

Cross-Service Propagation over HTTP

Across processes, context travels in HTTP headers. The default format is W3C Trace Context: the traceparent header carries trace ID, parent span ID, and flags.

Auto-instrumented RestClient/WebClient beans inject the header outbound.
The receiving Spring Boot app extracts it and continues the same trace.

Use the framework-provided builders (not new RestClient.Builder()) so the tracing interceptor is attached.

@Service
public class InventoryClient {

    private final RestClient restClient;

    // inject the auto-configured, instrumented builder
    public InventoryClient(RestClient.Builder builder) {
        this.restClient = builder.baseUrl("http://inventory").build();
    }

    public Stock check(String sku) {
        // traceparent header is injected automatically
        return restClient.get().uri("/stock/{sku}", sku)
            .retrieve().body(Stock.class);
    }
}

The W3C traceparent Header

Understanding the wire format helps when debugging broken traces. A traceparent looks like:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
00 = version, then 16-byte trace-id, 8-byte parent-id, and 01 = sampled flag.

If a downstream span shows a new trace ID, the header was dropped — often because a non-instrumented client or a manual header copy stripped it. A companion tracestate header carries vendor-specific data.

Propagating Through Messaging

For Kafka or RabbitMQ, context rides in message headers. With instrumented Spring Messaging, the producer injects traceparent into the record headers and the consumer extracts it, creating a span linked to the producer.

Producer span kind = PRODUCER; consumer span kind = CONSUMER.
Across a queue the relationship is often modeled as a span link rather than a strict parent/child, since many consumers may process batches.

Keep using the auto-configured KafkaTemplate/listeners so propagation works without manual header handling.

@Component
public class OrderEvents {

    private final KafkaTemplate<String, OrderEvent> template;

    public OrderEvents(KafkaTemplate<String, OrderEvent> template) {
        this.template = template;
    }

    public void publish(OrderEvent event) {
        // traceparent header added to the Kafka record automatically
        template.send("orders", event.id(), event);
    }

    @KafkaListener(topics = "orders")
    public void consume(OrderEvent event) {
        // this span links back to the producing trace
        process(event);
    }
}

Correlating Logs and Baggage

Two finishing touches make traces usable:

Log correlation: Micrometer pushes traceId and spanId into the SLF4J MDC, so each log line carries the IDs. Spring Boot's default log pattern prints them.
Baggage: arbitrary key-values that propagate across services alongside trace context. Configure management.tracing.baggage.correlation.fields and remote-fields to forward and expose them in MDC.

Use baggage sparingly (e.g. a userId or tenantId) — every value is copied onto every downstream hop.

management:
  tracing:
    sampling:
      probability: 1.0
    baggage:
      remote-fields: tenantId
      correlation:
        fields: tenantId

Quick Check

Test your understanding of in-process context propagation.

Recap

You learned how trace context flows through a Spring Boot 4 system:

Micrometer Observation unifies metrics and spans; observe(...) opens a thread-bound scope.
Choose low-cardinality tags for metrics and high-cardinality attributes for spans only.
Context lives in a thread-local, so async handoffs need ContextSnapshot or a ContextPropagatingTaskDecorator to keep the trace intact.
Create explicit spans with the Tracer when an Observation is overkill, always ending them in a finally block.
Across services, the W3C traceparent header (HTTP) or message headers (Kafka/Rabbit) carry the trace; use auto-instrumented clients.
MDC correlation ties logs to traces, and baggage forwards small key-values downstream.

常见问题解答

「上下文传播与跨度插桩」课时是免费的吗？

是的 — 「上下文传播与跨度插桩」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Spring Boot 4 Complete Guide 课程的其余内容，请升级到 CoddyKit PRO。 Spring Boot 4 Complete Guide 课程共包含 4 节课。

「上下文传播与跨度插桩」这节课中我会学到什么？

使用 Micrometer Observation 和 OpenTelemetry，跨线程和服务传播跟踪上下文。你通过在浏览器中直接运行的动手代码来练习 Spring Boot 4 Complete Guide，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Spring Boot 4 Complete Guide 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Spring Boot 4 Complete Guide 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「上下文传播与跨度插桩」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Spring Boot 4 Complete Guide 课中编写并运行代码吗？

能。每节 Spring Boot 4 Complete Guide 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Spring Boot 4 Complete Guide