java 41 lines · 7 steps

Correlation IDs in a Spring WebFlux filter

A reactive WebFilter tags every request with a correlation ID and threads it through the Reactor context and logs.

Explained by highlit

Spring Advanced reactive web filter correlation id reactor context mdc logging

1@Component
2public class CorrelationIdWebFilter implements WebFilter, Ordered {
3 
  public static final String CORRELATION_ID_HEADER = "X-Correlation-Id";
  private static final String MDC_KEY = "correlationId";
  private static final String CONTEXT_KEY = "CONTEXT_CORRELATION_ID";
7 
  @Override
  public int getOrder() {
      return Ordered.HIGHEST_PRECEDENCE;
  }
12 
  @Override
  public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
      String correlationId = resolveCorrelationId(exchange.getRequest());
16 
      exchange.getResponse().getHeaders().set(CORRELATION_ID_HEADER, correlationId);
18 
      return chain.filter(exchange)
              .contextWrite(Context.of(CONTEXT_KEY, correlationId))
              .doOnEach(signal -> {
                  if (!signal.isOnComplete() && !signal.isOnError() && !signal.isOnNext()) {
                      return;
                  }
                  String id = signal.getContextView().getOrDefault(CONTEXT_KEY, correlationId);
                  try (MDC.MDCCloseable ignored = MDC.putCloseable(MDC_KEY, id)) {
                      if (signal.isOnError()) {
                          log.error("Request failed", signal.getThrowable());
                      }
                  }
              });
  }
33 
  private String resolveCorrelationId(ServerHttpRequest request) {
      String header = request.getHeaders().getFirst(CORRELATION_ID_HEADER);
      if (header != null && !header.isBlank()) {
          return header;
      }
      return UUID.randomUUID().toString();
  }
41}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1In reactive code, thread-local MDC won't survive across operators, so state must ride in the Reactor context instead.
2Running a filter at highest precedence guarantees the correlation ID exists before any downstream logic executes.
3Populating MDC only inside a try-with-resources at log time keeps thread-local state scoped and cleaned up correctly.

Related explainers

java

@Component
@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {

Transparent column encryption in Spring & JPA

encryption aes-gcm jpa-converter

Advanced 10 steps

java

package com.acme.billing.config;
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.ConfigurationProperties;

Feature-flagged beans with Spring @ConditionalOnProperty

feature-flags conditional-beans strategy-pattern

Intermediate 5 steps

java

public static Map<String, String> parseCookieHeader(String header) {
    Map<String, String> cookies = new LinkedHashMap<>();
    if (header == null || header.isBlank()) {
        return cookies;

Parsing an HTTP Cookie header in Java

string-parsing http url-decoding

Intermediate 6 steps

java

public class TimedSocketReader {
 
    private static final int READ_TIMEOUT_MS = 5_000;
    private static final int CONNECT_TIMEOUT_MS = 3_000;

Reading a socket with connect and read timeouts

sockets timeouts io

Intermediate 8 steps

java

public final class EncodingDetector {
 
    public enum Encoding {
        UTF_8, UTF_16LE, UTF_16BE, UTF_32LE, UTF_32BE, ASCII, UNKNOWN

Detecting text encoding from raw bytes in Java

byte-manipulation encoding-detection bitwise-operations

Intermediate 8 steps

java

public final class ImportOrganizer {
 
    private static final Pattern IMPORT_LINE =
            Pattern.compile("^import\\s+(static\\s+)?([\\w.]+(?:\\.\\*)?)\\s*;\\s*$");