0Pricing
Spring Boot 4 Complete Guide · Урок

Передача контекста и инструментирование интервалов

Передавайте контекст трассировки между потоками и сервисами с помощью наблюдений Micrometer и OpenTelemetry.

«Передача контекста и инструментирование интервалов» — бесплатный урок Spring Boot 4 Complete Guide на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения 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.

Часто задаваемые вопросы

Урок «Передача контекста и инструментирование интервалов» бесплатный?

Да — полный текст урока «Передача контекста и инструментирование интервалов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Spring Boot 4 Complete Guide, подпишись на CoddyKit PRO. Курс Spring Boot 4 Complete Guide содержит 4 уроков всего.

Чему я научусь в уроке «Передача контекста и инструментирование интервалов»?

Передавайте контекст трассировки между потоками и сервисами с помощью наблюдений Micrometer и OpenTelemetry. Ты практикуешь Spring Boot 4 Complete Guide с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Spring Boot 4 Complete Guide?

Предыдущий опыт не требуется. Spring Boot 4 Complete Guide на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Передача контекста и инструментирование интервалов»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Spring Boot 4 Complete Guide?

Да. Каждый урок Spring Boot 4 Complete Guide включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Передача контекста и инструментирование интервалов
  2. Автоматические выключатели и изоляция перегородками
  3. Ограничение частоты, повторы и ограничители времени
  4. Связывание журналов, метрик и трассировок
← Назад к Spring Boot 4 Complete Guide