Distributed Tracing with OpenTelemetry & Spring Boot: Complete Production Guide (2026)

<!-- Micrometer Tracing core -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<!-- OTel OTLP exporter (sends to Jaeger/Tempo/any OTLP-compatible backend) -->
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 1.0   # 100% for dev; 0.1 for prod (10%)
    propagation:
      type: w3c           # W3C traceparent (recommended)
  otlp:
    tracing:
      endpoint: http://jaeger:4318/v1/traces
  zipkin:
    tracing:
      endpoint: http://zipkin:9411/api/v2/spans  # if using Zipkin

spring:
  application:
    name: order-service   # appears as service name in trace backend

// You see: "POST /api/orders" taking 3s — but WHY? Which sub-operation is slow?

// Option 1: @Observed annotation (declarative, AOP-based)
@Observed(name = "order.payment", contextualName = "processPayment",
          lowCardinalityKeyValues = {"payment.provider", "stripe"})
public PaymentResult processPayment(Order order) {
    return stripeService.charge(order);
}

// Option 2: Tracer API for fine-grained control
@Service
public class InventoryService {
    @Autowired private Tracer tracer;

    public void deductInventory(String productId, int qty) {
        Span span = tracer.nextSpan()
            .name("inventory.deduct")
            .tag("product.id", productId)
            .tag("quantity", String.valueOf(qty))
            .start();
        try (Tracer.SpanInScope ws = tracer.withSpan(span.start())) {
            // Business logic
            Product p = productRepository.findById(productId).orElseThrow();
            if (p.getStock() < qty) {
                span.tag("error", "insufficient_stock");
                span.event("insufficient_stock_detected");
                throw new InsufficientStockException(productId);
            }
            p.setStock(p.getStock() - qty);
            productRepository.save(p);
            span.tag("new.stock", String.valueOf(p.getStock()));
        } catch (Exception ex) {
            span.error(ex);
            throw ex;
        } finally {
            span.end();  // always end the span
        }
    }
}

// In order-service: set business baggage that all downstream services see
@PostMapping("/orders")
public ResponseEntity<Order> createOrder(@RequestBody OrderRequest request) {
    // Baggage is auto-propagated via traceparent to all downstream services
    BaggageField.create("tenant.id").updateValue(request.getTenantId());
    BaggageField.create("user.id").updateValue(request.getUserId());
    return ResponseEntity.ok(orderService.create(request));
}

// In inventory-service: read baggage without any code coupling
@Service
public class InventoryService {
    public void deductStock(String productId, int qty) {
        String tenantId = BaggageField.getByName("tenant.id").getValue();
        // tenantId is automatically available here — propagated via HTTP header!
        log.info("Deducting stock for tenant={} product={}", tenantId, productId);
    }
}

// Producer: trace headers injected AUTOMATICALLY by Spring Kafka + Micrometer Tracing
@Service
public class OrderEventPublisher {
    @Autowired private KafkaTemplate<String, OrderCreatedEvent> kafkaTemplate;

    public void publish(OrderCreatedEvent event) {
        // traceparent header is auto-added to Kafka message headers — no manual code!
        kafkaTemplate.send("order-created", event.getOrderId(), event);
    }
}

// Consumer: trace automatically continued from message headers
@KafkaListener(topics = "order-created", groupId = "inventory-group")
@Observed(name = "kafka.order.inventory.process")
public void handleOrderCreated(OrderCreatedEvent event) {
    // This span is automatically a child of the producer's span — full trace!
    inventoryService.deductInventory(event.getProductId(), event.getQuantity());
}

logging:
  pattern:
    console: "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} [%X{traceId},%X{spanId}] - %msg%n"
  level:
    io.micrometer.tracing: DEBUG   # see trace propagation in logs during debugging

# Result: every log line contains the traceId
# 09:15:42.001 [nio-8080-exec-1] INFO  OrderService [4bf92f3577b34da6a...] - Processing order 123
# Click traceId in Grafana/Jaeger to see the full request waterfall!

• Micrometer Tracing + OTel bridge in all services
• Service name set per service (spring.application.name)
• W3C traceparent propagation enabled
• Custom spans for critical business operations
• Business attributes on spans (orderId, userId)
• traceId in log pattern (MDC)
• Sampling 10% in prod; 100% for errors
• Trace IDs in error API responses
• Grafana Tempo linked to Loki logs
• OTel Collector as sidecar (buffer + retry)