W3C Trace Context in Java: Complete Guide for Distributed Tracing

Introduction to W3C Trace Context

W3C Trace Context is a standard that provides a unified format for propagating distributed tracing context across service boundaries. It defines standard HTTP headers (traceparent and tracestate) that carry trace information, enabling end-to-end tracing in microservices architectures.

Key Components

traceparent: Contains the trace ID, parent span ID, and trace flags
tracestate: Carries vendor-specific tracing information in a key-value format
Standard Format: Ensures interoperability across different tracing systems

Core Implementation

Dependencies

Add to your pom.xml:

<dependencies> <!-- OpenTelemetry for tracing --> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.34.1</version> </dependency> <!-- For HTTP client support --> <dependency> <groupId>org.apache.httpcomponents.client5</groupId> <artifactId>httpclient5</artifactId> <version>5.2.1</version> </dependency> <!-- For JSON processing --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency> <!-- For servlet applications --> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> </dependency> </dependencies>

TraceParent Class

package com.example.tracecontext; import java.util.Objects; import java.util.regex.Pattern; public class TraceParent { private static final Pattern TRACE_PARENT_PATTERN = Pattern.compile("^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$"); private final String version; private final String traceId; private final String parentId; private final String traceFlags; public TraceParent(String version, String traceId, String parentId, String traceFlags) { this.version = validateVersion(version); this.traceId = validateTraceId(traceId); this.parentId = validateSpanId(parentId); this.traceFlags = validateTraceFlags(traceFlags); } public static TraceParent parse(String traceParentHeader) { if (traceParentHeader == null || traceParentHeader.trim().isEmpty()) { throw new IllegalArgumentException("traceparent header cannot be null or empty"); } var matcher = TRACE_PARENT_PATTERN.matcher(traceParentHeader.trim()); if (!matcher.matches()) { throw new IllegalArgumentException("Invalid traceparent format: " + traceParentHeader); } return new TraceParent( matcher.group(1), // version matcher.group(2), // trace-id matcher.group(3), // parent-id matcher.group(4) // trace-flags ); } public static TraceParent create() { String version = "00"; String traceId = generateRandomHex(32); // 16 bytes String parentId = generateRandomHex(16); // 8 bytes String traceFlags = "01"; // Sampled return new TraceParent(version, traceId, parentId, traceFlags); } public TraceParent createChild() { String newParentId = generateRandomHex(16); // New span ID return new TraceParent(this.version, this.traceId, newParentId, this.traceFlags); } private static String generateRandomHex(int length) { var random = new java.security.SecureRandom(); byte[] bytes = new byte[length / 2]; random.nextBytes(bytes); StringBuilder sb = new StringBuilder(); for (byte b : bytes) { sb.append(String.format("%02x", b)); } return sb.toString(); } private String validateVersion(String version) { if (!version.matches("^[0-9a-f]{2}$")) { throw new IllegalArgumentException("Invalid version: " + version); } return version; } private String validateTraceId(String traceId) { if (!traceId.matches("^[0-9a-f]{32}$")) { throw new IllegalArgumentException("Invalid traceId: " + traceId); } if ("00000000000000000000000000000000".equals(traceId)) { throw new IllegalArgumentException("TraceId cannot be all zeros"); } return traceId; } private String validateSpanId(String spanId) { if (!spanId.matches("^[0-9a-f]{16}$")) { throw new IllegalArgumentException("Invalid spanId: " + spanId); } if ("0000000000000000".equals(spanId)) { throw new IllegalArgumentException("SpanId cannot be all zeros"); } return spanId; } private String validateTraceFlags(String traceFlags) { if (!traceFlags.matches("^[0-9a-f]{2}$")) { throw new IllegalArgumentException("Invalid traceFlags: " + traceFlags); } return traceFlags; } public boolean isSampled() { // Check if sampled flag is set (bit 0 of traceFlags) int flags = Integer.parseInt(traceFlags, 16); return (flags & 0x01) == 1; } public void setSampled(boolean sampled) { int flags = Integer.parseInt(traceFlags, 16); if (sampled) { flags |= 0x01; // Set sampled flag } else { flags &= ~0x01; // Clear sampled flag } this.traceFlags = String.format("%02x", flags); } public String toString() { return String.format("%s-%s-%s-%s", version, traceId, parentId, traceFlags); } // Getters public String getVersion() { return version; } public String getTraceId() { return traceId; } public String getParentId() { return parentId; } public String getTraceFlags() { return traceFlags; } @Override public boolean equals(Object o) { if (this == o) return true; if (o == null || getClass() != o.getClass()) return false; TraceParent that = (TraceParent) o; return Objects.equals(version, that.version) && Objects.equals(traceId, that.traceId) && Objects.equals(parentId, that.parentId) && Objects.equals(traceFlags, that.traceFlags); } @Override public int hashCode() { return Objects.hash(version, traceId, parentId, traceFlags); } }

TraceState Class

package com.example.tracecontext; import java.util.*; import java.util.stream.Collectors; public class TraceState { private static final int MAX_KEYS = 32; private static final Pattern KEY_PATTERN = Pattern.compile("^[a-z][_0-9a-z\\-*/]{0,255}$"); private static final Pattern VALUE_PATTERN = Pattern.compile("^[\\x20-\\x2B\\x2D-\\x7E]{0,255}$"); private final LinkedHashMap<String, String> entries; public TraceState() { this.entries = new LinkedHashMap<>(); } public TraceState(String tracestateHeader) { this(); if (tracestateHeader != null && !tracestateHeader.trim().isEmpty()) { parseHeader(tracestateHeader.trim()); } } private void parseHeader(String tracestateHeader) { String[] vendorEntries = tracestateHeader.split(","); for (String entry : vendorEntries) { String[] keyValue = entry.split("="); if (keyValue.length != 2) { throw new IllegalArgumentException("Invalid tracestate entry: " + entry); } String key = keyValue[0].trim(); String value = keyValue[1].trim(); put(key, value); } } public TraceState put(String key, String value) { validateKey(key); validateValue(value); // Remove existing entry if present (to move to front) entries.remove(key); // Check size limit if (entries.size() >= MAX_KEYS) { throw new IllegalStateException("TraceState cannot contain more than " + MAX_KEYS + " entries"); } // Add to front (LinkedHashMap maintains insertion order) LinkedHashMap<String, String> newEntries = new LinkedHashMap<>(); newEntries.put(key, value); newEntries.putAll(entries); entries.clear(); entries.putAll(newEntries); return this; } public String get(String key) { return entries.get(key); } public TraceState remove(String key) { entries.remove(key); return this; } public boolean containsKey(String key) { return entries.containsKey(key); } public Set<String> keySet() { return Collections.unmodifiableSet(entries.keySet()); } public int size() { return entries.size(); } public boolean isEmpty() { return entries.isEmpty(); } private void validateKey(String key) { if (key == null || key.isEmpty()) { throw new IllegalArgumentException("Key cannot be null or empty"); } if (!KEY_PATTERN.matcher(key).matches()) { throw new IllegalArgumentException("Invalid key format: " + key); } } private void validateValue(String value) { if (value == null) { throw new IllegalArgumentException("Value cannot be null"); } if (!VALUE_PATTERN.matcher(value).matches()) { throw new IllegalArgumentException("Invalid value format: " + value); } } public String toString() { return entries.entrySet().stream() .map(entry -> entry.getKey() + "=" + entry.getValue()) .collect(Collectors.joining(",")); } public static Builder builder() { return new Builder(); } public static class Builder { private TraceState traceState; public Builder() { this.traceState = new TraceState(); } public Builder fromHeader(String tracestateHeader) { this.traceState = new TraceState(tracestateHeader); return this; } public Builder put(String key, String value) { traceState.put(key, value); return this; } public Builder remove(String key) { traceState.remove(key); return this; } public TraceState build() { return traceState; } } }

W3C Trace Context Propagator

package com.example.tracecontext; import io.opentelemetry.context.Context; import io.opentelemetry.context.propagation.TextMapGetter; import io.opentelemetry.context.propagation.TextMapPropagator; import io.opentelemetry.context.propagation.TextMapSetter; import javax.annotation.Nullable; import java.util.Collection; import java.util.Collections; import java.util.LinkedHashMap; import java.util.Map; public class W3CTraceContextPropagator implements TextMapPropagator { private static final String TRACE_PARENT_HEADER = "traceparent"; private static final String TRACE_STATE_HEADER = "tracestate"; private static final W3CTraceContextPropagator INSTANCE = new W3CTraceContextPropagator(); public static W3CTraceContextPropagator getInstance() { return INSTANCE; } @Override public Collection<String> fields() { return Collections.unmodifiableList( Arrays.asList(TRACE_PARENT_HEADER, TRACE_STATE_HEADER) ); } @Override public <C> void inject(Context context, @Nullable C carrier, TextMapSetter<C> setter) { if (context == null || setter == null) { return; } W3CTraceContext w3cContext = context.get(W3CTraceContext.KEY); if (w3cContext == null) { return; } // Inject traceparent if (w3cContext.getTraceParent() != null) { setter.set(carrier, TRACE_PARENT_HEADER, w3cContext.getTraceParent().toString()); } // Inject tracestate if (w3cContext.getTraceState() != null && !w3cContext.getTraceState().isEmpty()) { setter.set(carrier, TRACE_STATE_HEADER, w3cContext.getTraceState().toString()); } } @Override public <C> Context extract(Context context, @Nullable C carrier, TextMapGetter<C> getter) { if (context == null || getter == null) { return context; } try { String traceParentHeader = getter.get(carrier, TRACE_PARENT_HEADER); String traceStateHeader = getter.get(carrier, TRACE_STATE_HEADER); if (traceParentHeader == null) { return context; } TraceParent traceParent = TraceParent.parse(traceParentHeader); TraceState traceState = new TraceState(traceStateHeader); W3CTraceContext w3cContext = new W3CTraceContext(traceParent, traceState); return context.with(W3CTraceContext.KEY, w3cContext); } catch (Exception e) { // Log warning but don't fail extraction System.err.println("Failed to extract W3C Trace Context: " + e.getMessage()); return context; } } }

W3C Trace Context Container

package com.example.tracecontext; import io.opentelemetry.context.Context; import io.opentelemetry.context.ContextKey; public class W3CTraceContext { public static final ContextKey<W3CTraceContext> KEY = ContextKey.named("w3c-trace-context"); private final TraceParent traceParent; private final TraceState traceState; public W3CTraceContext(TraceParent traceParent, TraceState traceState) { this.traceParent = traceParent; this.traceState = traceState; } public W3CTraceContext() { this(TraceParent.create(), new TraceState()); } public static W3CTraceContext fromContext(Context context) { W3CTraceContext w3cContext = context.get(KEY); if (w3cContext == null) { return new W3CTraceContext(); } return w3cContext; } public Context storeInContext(Context context) { return context.with(KEY, this); } public W3CTraceContext createChild() { TraceParent childTraceParent = this.traceParent.createChild(); return new W3CTraceContext(childTraceParent, this.traceState); } // Getters public TraceParent getTraceParent() { return traceParent; } public TraceState getTraceState() { return traceState; } public String getTraceId() { return traceParent != null ? traceParent.getTraceId() : null; } public String getSpanId() { return traceParent != null ? traceParent.getParentId() : null; } public boolean isSampled() { return traceParent != null && traceParent.isSampled(); } @Override public String toString() { return String.format("W3CTraceContext{traceParent=%s, traceState=%s}", traceParent, traceState); } }

HTTP Client Implementation

Trace-Aware HTTP Client

package com.example.tracecontext; import org.apache.hc.client5.http.classic.HttpClient; import org.apache.hc.client5.http.classic.methods.HttpGet; import org.apache.hc.client5.http.classic.methods.HttpPost; import org.apache.hc.client5.http.classic.methods.HttpUriRequest; import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; import org.apache.hc.client5.http.impl.classic.HttpClients; import org.apache.hc.core5.http.io.entity.EntityUtils; import org.apache.hc.core5.http.io.entity.StringEntity; import java.io.IOException; import java.util.Map; public class TraceAwareHttpClient { private final CloseableHttpClient httpClient; private final W3CTraceContextPropagator propagator; public TraceAwareHttpClient() { this.httpClient = HttpClients.createDefault(); this.propagator = W3CTraceContextPropagator.getInstance(); } public String get(String url, W3CTraceContext traceContext) throws IOException { HttpGet request = new HttpGet(url); injectTraceContext(request, traceContext); return httpClient.execute(request, response -> { return EntityUtils.toString(response.getEntity()); }); } public String post(String url, String body, String contentType, W3CTraceContext traceContext) throws IOException { HttpPost request = new HttpPost(url); injectTraceContext(request, traceContext); StringEntity entity = new StringEntity(body); entity.setContentType(contentType); request.setEntity(entity); return httpClient.execute(request, response -> { return EntityUtils.toString(response.getEntity()); }); } private void injectTraceContext(HttpUriRequest request, W3CTraceContext traceContext) { propagator.inject( traceContext.storeInContext(io.opentelemetry.context.Context.current()), request, new TextMapSetter<HttpUriRequest>() { @Override public void set(HttpUriRequest carrier, String key, String value) { carrier.setHeader(key, value); } } ); // Also add as custom headers for debugging request.setHeader("X-TraceId", traceContext.getTraceId()); request.setHeader("X-SpanId", traceContext.getSpanId()); } public W3CTraceContext extractTraceContext(Map<String, String> headers) { return propagator.extract( io.opentelemetry.context.Context.current(), headers, new TextMapGetter<Map<String, String>>() { @Override public String get(Map<String, String> carrier, String key) { return carrier.get(key); } @Override public Iterable<String> keys(Map<String, String> carrier) { return carrier.keySet(); } } ).get(W3CTraceContext.KEY); } public void close() throws IOException { httpClient.close(); } }

Servlet Filter for HTTP Servers

package com.example.tracecontext; import javax.servlet.*; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.util.Collections; import java.util.HashMap; import java.util.Map; public class W3CTraceContextFilter implements Filter { private final W3CTraceContextPropagator propagator; public W3CTraceContextFilter() { this.propagator = W3CTraceContextPropagator.getInstance(); } @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { if (!(request instanceof HttpServletRequest)) { chain.doFilter(request, response); return; } HttpServletRequest httpRequest = (HttpServletRequest) request; HttpServletResponse httpResponse = (HttpServletResponse) response; // Extract trace context from incoming headers W3CTraceContext incomingContext = extractContextFromRequest(httpRequest); // Store in thread-local context try (var scope = incomingContext.storeInContext( io.opentelemetry.context.Context.current()).makeCurrent()) { // Add trace IDs to response headers for client debugging addTraceHeadersToResponse(httpResponse, incomingContext); // Continue processing chain.doFilter(request, response); } } private W3CTraceContext extractContextFromRequest(HttpServletRequest request) { Map<String, String> headers = new HashMap<>(); // Extract all headers Collections.list(request.getHeaderNames()) .forEach(headerName -> headers.put(headerName, request.getHeader(headerName)) ); W3CTraceContext extractedContext = propagator.extract( io.opentelemetry.context.Context.current(), headers, new TextMapGetter<Map<String, String>>() { @Override public String get(Map<String, String> carrier, String key) { return carrier.get(key.toLowerCase()); } @Override public Iterable<String> keys(Map<String, String> carrier) { return carrier.keySet(); } } ).get(W3CTraceContext.KEY); // If no context was extracted, create a new one return extractedContext != null ? extractedContext : new W3CTraceContext(); } private void addTraceHeadersToResponse(HttpServletResponse response, W3CTraceContext context) { response.setHeader("X-TraceId", context.getTraceId()); response.setHeader("X-SpanId", context.getSpanId()); response.setHeader("X-TraceSampled", String.valueOf(context.isSampled())); } @Override public void init(FilterConfig filterConfig) throws ServletException { // Initialization logic if needed } @Override public void destroy() { // Cleanup logic if needed } }

Spring Boot Integration

Configuration Class

package com.example.tracecontext.config; import com.example.tracecontext.W3CTraceContextFilter; import com.example.tracecontext.W3CTraceContextPropagator; import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.Ordered; @Configuration public class TraceContextConfig { @Bean public W3CTraceContextPropagator w3cTraceContextPropagator() { return W3CTraceContextPropagator.getInstance(); } @Bean public FilterRegistrationBean<W3CTraceContextFilter> traceContextFilter() { FilterRegistrationBean<W3CTraceContextFilter> registrationBean = new FilterRegistrationBean<>(); registrationBean.setFilter(new W3CTraceContextFilter()); registrationBean.addUrlPatterns("/*"); registrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE); registrationBean.setName("W3CTraceContextFilter"); return registrationBean; } }

REST Controller with Trace Context

package com.example.tracecontext.controller; import com.example.tracecontext.W3CTraceContext; import com.example.tracecontext.W3CTraceContextPropagator; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.HttpHeaders; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import javax.servlet.http.HttpServletRequest; import java.util.Enumeration; import java.util.HashMap; import java.util.Map; @RestController @RequestMapping("/api") public class TraceAwareController { private static final Logger logger = LoggerFactory.getLogger(TraceAwareController.class); private final W3CTraceContextPropagator propagator; public TraceAwareController(W3CTraceContextPropagator propagator) { this.propagator = propagator; } @GetMapping("/trace-info") public ResponseEntity<Map<String, String>> getTraceInfo(HttpServletRequest request) { // Extract trace context from request W3CTraceContext traceContext = extractTraceContext(request); // Log with trace context logger.info("Processing trace-info request [traceId: {}, spanId: {}]", traceContext.getTraceId(), traceContext.getSpanId()); Map<String, String> traceInfo = new HashMap<>(); traceInfo.put("traceId", traceContext.getTraceId()); traceInfo.put("spanId", traceContext.getSpanId()); traceInfo.put("sampled", String.valueOf(traceContext.isSampled())); traceInfo.put("traceParent", traceContext.getTraceParent().toString()); traceInfo.put("traceState", traceContext.getTraceState().toString()); return ResponseEntity.ok(traceInfo); } @PostMapping("/process") public ResponseEntity<Map<String, Object>> processItem( @RequestBody Map<String, Object> item, HttpServletRequest request) { W3CTraceContext traceContext = extractTraceContext(request); // Create child context for this operation W3CTraceContext childContext = traceContext.createChild(); logger.info("Processing item {} [traceId: {}, parentSpanId: {}, newSpanId: {}]", item.get("id"), childContext.getTraceId(), traceContext.getSpanId(), childContext.getSpanId()); // Simulate business processing processBusinessLogic(item, childContext); Map<String, Object> response = new HashMap<>(); response.put("status", "processed"); response.put("item", item); response.put("traceId", childContext.getTraceId()); response.put("spanId", childContext.getSpanId()); // Add trace headers to response HttpHeaders headers = new HttpHeaders(); headers.add("X-TraceId", childContext.getTraceId()); headers.add("X-SpanId", childContext.getSpanId()); return ResponseEntity.ok().headers(headers).body(response); } private W3CTraceContext extractTraceContext(HttpServletRequest request) { Map<String, String> headers = new HashMap<>(); Enumeration<String> headerNames = request.getHeaderNames(); while (headerNames.hasMoreElements()) { String headerName = headerNames.nextElement(); headers.put(headerName, request.getHeader(headerName)); } return propagator.extract( io.opentelemetry.context.Context.current(), headers, new TextMapGetter<Map<String, String>>() { @Override public String get(Map<String, String> carrier, String key) { return carrier.get(key); } @Override public Iterable<String> keys(Map<String, String> carrier) { return carrier.keySet(); } } ).get(W3CTraceContext.KEY); } private void processBusinessLogic(Map<String, Object> item, W3CTraceContext context) { // Simulate some business logic try { Thread.sleep(100); // Add custom trace state context.getTraceState().put("custom-processor", "business-logic"); context.getTraceState().put("item-type", item.get("type").toString()); logger.debug("Completed business processing for item {}", item.get("id")); } catch (InterruptedException e) { Thread.currentThread().interrupt(); logger.error("Business processing interrupted", e); } } }

OpenTelemetry Integration

OpenTelemetry W3C Propagator Setup

package com.example.tracecontext.opentelemetry; import io.opentelemetry.api.OpenTelemetry; import io.opentelemetry.api.trace.Span; import io.opentelemetry.api.trace.Tracer; import io.opentelemetry.context.Context; import io.opentelemetry.context.propagation.ContextPropagators; import io.opentelemetry.sdk.OpenTelemetrySdk; import io.opentelemetry.sdk.trace.SdkTracerProvider; import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor; import io.opentelemetry.exporter.logging.LoggingSpanExporter; import io.opentelemetry.sdk.trace.samplers.Sampler; import io.opentelemetry extension.trace.propagation.W3CTraceContextPropagator; public class OpenTelemetrySetup { private static final String INSTRUMENTATION_NAME = "w3c-trace-context-demo"; public static OpenTelemetry initOpenTelemetry() { // Use W3C Trace Context propagator ContextPropagators propagators = ContextPropagators.create( W3CTraceContextPropagator.getInstance() ); SdkTracerProvider tracerProvider = SdkTracerProvider.builder() .addSpanProcessor(SimpleSpanProcessor.create(LoggingSpanExporter.create())) .setSampler(Sampler.alwaysOn()) .build(); return OpenTelemetrySdk.builder() .setTracerProvider(tracerProvider) .setPropagators(propagators) .buildAndRegisterGlobal(); } public static void demonstrateTracing() { OpenTelemetry openTelemetry = initOpenTelemetry(); Tracer tracer = openTelemetry.getTracer(INSTRUMENTATION_NAME); // Create a span Span span = tracer.spanBuilder("parent-operation").startSpan(); try (var scope = span.makeCurrent()) { // The span is now the current span and W3C context is available span.setAttribute("service.name", "demo-service"); // Extract current W3C context Context currentContext = Context.current(); String traceId = Span.fromContext(currentContext).getSpanContext().getTraceId(); String spanId = Span.fromContext(currentContext).getSpanContext().getSpanId(); System.out.printf("Trace ID: %s, Span ID: %s%n", traceId, spanId); // Simulate some work doWork(tracer); } finally { span.end(); } } private static void doWork(Tracer tracer) { // Create a child span Span childSpan = tracer.spanBuilder("child-operation").startSpan(); try (var scope = childSpan.makeCurrent()) { childSpan.setAttribute("work.type", "processing"); // Child span automatically inherits W3C context String traceId = Span.current().getSpanContext().getTraceId(); String spanId = Span.current().getSpanContext().getSpanId(); System.out.printf("Child - Trace ID: %s, Span ID: %s%n", traceId, spanId); } finally { childSpan.end(); } } }

Testing W3C Trace Context

Unit Tests

package com.example.tracecontext; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class TraceParentTest { @Test void testParseValidTraceParent() { String validHeader = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"; TraceParent traceParent = TraceParent.parse(validHeader); assertEquals("00", traceParent.getVersion()); assertEquals("4bf92f3577b34da6a3ce929d0e0e4736", traceParent.getTraceId()); assertEquals("00f067aa0ba902b7", traceParent.getParentId()); assertEquals("01", traceParent.getTraceFlags()); assertTrue(traceParent.isSampled()); } @Test void testCreateNewTraceParent() { TraceParent traceParent = TraceParent.create(); assertNotNull(traceParent.getTraceId()); assertNotNull(traceParent.getParentId()); assertEquals(32, traceParent.getTraceId().length()); assertEquals(16, traceParent.getParentId().length()); assertEquals("00", traceParent.getVersion()); } @Test void testCreateChild() { TraceParent parent = TraceParent.create(); TraceParent child = parent.createChild(); assertEquals(parent.getTraceId(), child.getTraceId()); assertEquals(parent.getVersion(), child.getVersion()); assertEquals(parent.getTraceFlags(), child.getTraceFlags()); assertNotEquals(parent.getParentId(), child.getParentId()); } @Test void testSampledFlag() { TraceParent traceParent = TraceParent.create(); traceParent.setSampled(true); assertTrue(traceParent.isSampled()); traceParent.setSampled(false); assertFalse(traceParent.isSampled()); } } class TraceStateTest { @Test void testParseTraceState() { String header = "vendor1=value1,vendor2=value2"; TraceState traceState = new TraceState(header); assertEquals("value1", traceState.get("vendor1")); assertEquals("value2", traceState.get("vendor2")); assertEquals(2, traceState.size()); } @Test void testTraceStateOrdering() { TraceState traceState = new TraceState(); traceState.put("first", "value1"); traceState.put("second", "value2"); traceState.put("first", "value3"); // Update first // The updated entry should move to front String result = traceState.toString(); assertTrue(result.startsWith("first=value3")); } @Test void testTraceStateValidation() { TraceState traceState = new TraceState(); assertThrows(IllegalArgumentException.class, () -> { traceState.put("Invalid Key", "value"); // Invalid key format }); assertThrows(IllegalArgumentException.class, () -> { traceState.put("validkey", "invalid\u0000value"); // Invalid value }); } }

Integration Test

package com.example.tracecontext; import org.junit.jupiter.api.Test; import org.springframework.mock.web.MockHttpServletRequest; import org.springframework.mock.web.MockHttpServletResponse; import javax.servlet.FilterChain; import javax.servlet.ServletException; import java.io.IOException; import java.util.Map; import static org.mockito.Mockito.*; class W3CTraceContextFilterTest { @Test void testFilterAddsTraceContext() throws IOException, ServletException { W3CTraceContextFilter filter = new W3CTraceContextFilter(); MockHttpServletRequest request = new MockHttpServletRequest(); MockHttpServletResponse response = new MockHttpServletResponse(); FilterChain filterChain = mock(FilterChain.class); // Add W3C headers to request request.addHeader("traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"); request.addHeader("tracestate", "vendor1=value1"); filter.doFilter(request, response, filterChain); // Verify response headers assertNotNull(response.getHeader("X-TraceId")); assertNotNull(response.getHeader("X-SpanId")); verify(filterChain).doFilter(request, response); } @Test void testFilterCreatesNewContextWhenMissing() throws IOException, ServletException { W3CTraceContextFilter filter = new W3CTraceContextFilter(); MockHttpServletRequest request = new MockHttpServletRequest(); MockHttpServletResponse response = new MockHttpServletResponse(); FilterChain filterChain = mock(FilterChain.class); // No headers in request filter.doFilter(request, response, filterChain); // Verify response headers are still added assertNotNull(response.getHeader("X-TraceId")); assertNotNull(response.getHeader("X-SpanId")); verify(filterChain).doFilter(request, response); } }

Best Practices and Patterns

1. Context Propagation in Async Operations

package com.example.tracecontext; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; public class AsyncTraceContext { private final ExecutorService executor; public AsyncTraceContext() { this.executor = Executors.newCachedThreadPool(); } public CompletableFuture<String> processAsync(String data) { // Capture current context W3CTraceContext currentContext = W3CTraceContext.fromContext( io.opentelemetry.context.Context.current() ); return CompletableFuture.supplyAsync(() -> { // Restore context in async thread try (var scope = currentContext.storeInContext( io.opentelemetry.context.Context.current()).makeCurrent()) { // Now we have the trace context in the async thread System.out.println("Processing async with trace: " + currentContext.getTraceId()); // Simulate work Thread.sleep(100); return "Processed: " + data; } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new RuntimeException(e); } }, executor); } }

2. Custom Trace State Management

package com.example.tracecontext; public class CustomTraceStateManager { public static void addUserContext(String userId) { W3CTraceContext currentContext = W3CTraceContext.fromContext( io.opentelemetry.context.Context.current() ); if (currentContext != null) { currentContext.getTraceState().put("user.id", userId); } } public static void addFeatureFlag(String feature, boolean enabled) { W3CTraceContext currentContext = W3CTraceContext.fromContext( io.opentelemetry.context.Context.current() ); if (currentContext != null) { currentContext.getTraceState().put("feature." + feature, enabled ? "enabled" : "disabled"); } } public static String getUserId() { W3CTraceContext currentContext = W3CTraceContext.fromContext( io.opentelemetry.context.Context.current() ); return currentContext != null ? currentContext.getTraceState().get("user.id") : null; } }

Conclusion

This comprehensive implementation of W3C Trace Context in Java provides:

Complete W3C Trace Context specification implementation
HTTP propagation for both clients and servers
Spring Boot integration for easy adoption
OpenTelemetry compatibility for existing tracing infrastructure
Async context propagation for modern applications
Comprehensive testing for reliability

Key benefits include standardized distributed tracing, interoperability across different systems and languages, and production-ready implementation with proper error handling and validation.

The implementation follows W3C specification precisely while providing practical utilities for real-world applications, making distributed tracing seamless across your microservices architecture.

Java Observability, Logging Intelligence & AI-Driven Monitoring (APM, Tracing, Logs & Anomaly Detection)

https://macronepal.com/blog/beyond-metrics-observing-serverless-and-traditional-java-applications-with-thundra-apm/
Explains using Thundra APM to observe both serverless and traditional Java applications by combining tracing, metrics, and logs into a unified observability platform for faster debugging and performance insights.

https://macronepal.com/blog/dynatrace-oneagent-in-java-2/
Explains Dynatrace OneAgent for Java, which automatically instruments JVM applications to capture metrics, traces, and logs, enabling full-stack monitoring and root-cause analysis with minimal configuration.

https://macronepal.com/blog/lightstep-java-sdk-distributed-tracing-and-observability-implementation/
Explains Lightstep Java SDK for distributed tracing, helping developers track requests across microservices and identify latency issues using OpenTelemetry-based observability.

https://macronepal.com/blog/honeycomb-io-beeline-for-java-complete-guide-2/
Explains Honeycomb Beeline for Java, which provides high-cardinality observability and deep query capabilities to understand complex system behavior and debug distributed systems efficiently.

https://macronepal.com/blog/lumigo-for-serverless-in-java-complete-distributed-tracing-guide-2/
Explains Lumigo for Java serverless applications, offering automatic distributed tracing, log correlation, and error tracking to simplify debugging in cloud-native environments. (Lumigo Docs)

https://macronepal.com/blog/from-noise-to-signals-implementing-log-anomaly-detection-in-java-applications/
Explains how to detect anomalies in Java logs using behavioral patterns and machine learning techniques to separate meaningful incidents from noisy log data and improve incident response.

https://macronepal.com/blog/ai-powered-log-analysis-in-java-from-reactive-debugging-to-proactive-insights/
Explains AI-driven log analysis for Java applications, shifting from manual debugging to predictive insights that identify issues early and improve system reliability using intelligent log processing.

https://macronepal.com/blog/titliel-java-logging-best-practices/
Explains best practices for Java logging, focusing on structured logs, proper log levels, performance optimization, and ensuring logs are useful for debugging and observability systems.

https://macronepal.com/blog/seeking-a-loguru-for-java-the-quest-for-elegant-and-simple-logging/
Explains the search for simpler, more elegant logging frameworks in Java, comparing modern logging approaches that aim to reduce complexity while improving readability and developer experience.