OpenTelemetry for Spring Boot: Guide with Examples

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

export OTEL_SERVICE_NAME=spring-app
export OTEL_SERVICE_VERSION=1.0.0
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.uptrace.dev:4317
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=<your_uptrace_dsn>
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

java -javaagent:opentelemetry-javaagent.jar -jar your-spring-app.jar

spring:
  application:
    name: spring-app

otel:
  exporter:
    otlp:
      protocol: grpc
      endpoint: https://api.uptrace.dev:4317
      headers:
        uptrace-dsn: <your_uptrace_dsn>
      compression: gzip
  resource:
    attributes:
      service.version: 1.0.0
      deployment.environment: production

spring.application.name=spring-app
otel.exporter.otlp.protocol=grpc
otel.exporter.otlp.endpoint=https://api.uptrace.dev:4317
otel.exporter.otlp.headers.uptrace-dsn=<your_uptrace_dsn>
otel.exporter.otlp.compression=gzip
otel.resource.attributes.service.version=1.0.0
otel.resource.attributes.deployment.environment=production

# Maven
./mvnw -Pnative native:compile
./target/your-app

# Gradle
./gradlew nativeCompile
./build/native/nativeCompile/your-app

@RestController
@RequestMapping("/api/orders")
public class ReactiveOrderController {

    private final OrderService orderService;

    @GetMapping("/{id}")
    public Mono<Order> getOrder(@PathVariable String id) {
        // Automatically instrumented - spans propagate through reactive chain
        return orderService.findById(id)
            .doOnSuccess(order -> log.info("Found order: {}", order.getId()));
    }

    @GetMapping("/stream")
    public Flux<Order> streamOrders() {
        // Streaming endpoint also instrumented
        return orderService.streamAllOrders();
    }
}

@Service
public class PaymentClient {

    private final WebClient webClient;

    public PaymentClient(WebClient.Builder builder) {
        this.webClient = builder
            .baseUrl("https://payment-service")
            .build();
    }

    public Mono<PaymentResult> processPayment(Payment payment) {
        // Trace context automatically propagated to downstream service
        return webClient.post()
            .uri("/api/payments")
            .bodyValue(payment)
            .retrieve()
            .bodyToMono(PaymentResult.class);
    }
}

import io.opentelemetry.instrumentation.annotations.WithSpan;
import io.opentelemetry.instrumentation.annotations.SpanAttribute;
import io.opentelemetry.api.trace.SpanKind;

@Service
public class OrderService {

    @WithSpan
    public Order processOrder(String orderId) {
        // Creates span named "OrderService.processOrder"
        return doProcess(orderId);
    }

    @WithSpan("custom-operation-name")
    public void customNamedOperation() {
        // Creates span with custom name
    }

    @WithSpan(kind = SpanKind.CLIENT)
    public ExternalResult callExternalService() {
        // Creates CLIENT span for external calls
    }

    @WithSpan
    public Order findOrder(
            @SpanAttribute("order.id") String orderId,
            @SpanAttribute("customer.id") String customerId) {
        // Captures method parameters as span attributes
        return repository.find(orderId);
    }
}

import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;
import io.opentelemetry.semconv.UrlAttributes;
import io.opentelemetry.contrib.sampler.RuleBasedRoutingSampler;
import io.opentelemetry.api.trace.SpanKind;

@Configuration
public class OtelConfiguration {

    @Bean
    public AutoConfigurationCustomizerProvider otelCustomizer() {
        return p -> p.addSamplerCustomizer((sampler, config) ->
            RuleBasedRoutingSampler.builder(SpanKind.SERVER, sampler)
                .drop(UrlAttributes.URL_PATH, "^/actuator")
                .drop(UrlAttributes.URL_PATH, "^/health")
                .build()
        );
    }
}

# Capture thread name and ID
otel.instrumentation.logback-appender.experimental-log-attributes=true

# Capture source code location (may add overhead)
otel.instrumentation.logback-appender.experimental.capture-code-attributes=true

# Capture all MDC attributes
otel.instrumentation.logback-appender.experimental.capture-mdc-attributes=*

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} trace_id=%X{trace_id} span_id=%X{span_id} - %msg%n</pattern>
    </encoder>
  </appender>

  <appender name="OpenTelemetry"
      class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
    <captureExperimentalAttributes>true</captureExperimentalAttributes>
    <captureCodeAttributes>true</captureCodeAttributes>
    <captureMdcAttributes>*</captureMdcAttributes>
  </appender>

  <root level="INFO">
    <appender-ref ref="console"/>
    <appender-ref ref="OpenTelemetry"/>
  </root>
</configuration>

@Service
public class OrderProcessingService {

    private final Tracer tracer;

    public OrderProcessingService(OpenTelemetry openTelemetry) {
        this.tracer = openTelemetry.getTracer("com.example.orders", "1.0.0");
    }

    public OrderResult processOrder(OrderRequest request) {
        Span orderSpan = tracer.spanBuilder("process-order")
            .setAttribute("order.id", request.getOrderId())
            .setAttribute("customer.id", request.getCustomerId())
            .setAttribute("order.amount", request.getTotalAmount())
            .startSpan();

        try (Scope scope = orderSpan.makeCurrent()) {
            // Business logic with automatic context propagation
            validateOrder(request);
            orderSpan.addEvent("order.validated");

            PaymentResult payment = processPayment(request);
            orderSpan.setAttribute("payment.status", payment.getStatus());

            OrderResult result = finalizeOrder(request);
            orderSpan.setStatus(StatusCode.OK);

            return result;
        } catch (Exception e) {
            orderSpan.setStatus(StatusCode.ERROR, e.getMessage());
            orderSpan.recordException(e);
            throw e;
        } finally {
            orderSpan.end();
        }
    }
}

@Component
public class BusinessMetricsCollector {

    private final LongCounter orderCounter;
    private final DoubleHistogram orderValueHistogram;

    public BusinessMetricsCollector(OpenTelemetry openTelemetry) {
        Meter meter = openTelemetry.getMeter("com.example.business", "1.0.0");

        orderCounter = meter.counterBuilder("orders.processed.total")
            .setDescription("Total orders processed")
            .build();

        orderValueHistogram = meter.histogramBuilder("order.value")
            .setDescription("Order value distribution")
            .setUnit("USD")
            .build();
    }

    public void recordOrder(String type, String status, double value) {
        orderCounter.add(1, Attributes.of(
            AttributeKey.stringKey("order.type"), type,
            AttributeKey.stringKey("order.status"), status
        ));

        orderValueHistogram.record(value, Attributes.of(
            AttributeKey.stringKey("order.type"), type
        ));
    }
}

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderProcessingService orderService;
    private final BusinessMetricsCollector metricsCollector;

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(@RequestBody OrderRequest request) {
        // Current span enrichment
        Span currentSpan = Span.current();
        currentSpan.setAttribute("order.items.count", request.getItems().size());
        currentSpan.setAttribute("customer.region", request.getCustomerRegion());

        try {
            OrderResult result = orderService.processOrder(request);

            // Record business metrics
            metricsCollector.recordOrder(
                request.getOrderType(),
                result.getStatus(),
                request.getTotalAmount()
            );

            currentSpan.setStatus(StatusCode.OK);
            return ResponseEntity.ok(new OrderResponse(result.getOrderId()));

        } catch (OrderValidationException e) {
            currentSpan.setStatus(StatusCode.ERROR, "Validation failed");
            return ResponseEntity.badRequest()
                .body(new ErrorResponse("VALIDATION_ERROR", e.getMessage()));
        }
    }
}

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 1000
  memory_limiter:
    check_interval: 1s
    limit_mib: 1000
    spike_limit_mib: 200

exporters:
  otlp:
    endpoint: https://api.uptrace.dev:4317
    headers:
      uptrace-dsn: ${UPTRACE_DSN}
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp]

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: spring-app
spec:
  template:
    spec:
      containers:
        - name: spring-app
          image: your-spring-app:latest
          env:
            - name: OTEL_SERVICE_NAME
              value: spring-app
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: http://otel-collector:4317
            - name: OTEL_EXPORTER_OTLP_PROTOCOL
              value: grpc
            - name: OTEL_TRACES_SAMPLER
              value: parentbased_traceidratio
            - name: OTEL_TRACES_SAMPLER_ARG
              value: "0.1"

# docker-compose.yml
services:
  spring-app:
    image: your-spring-app:latest
    environment:
      - OTEL_SERVICE_NAME=spring-app
      - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
      - OTEL_TRACES_SAMPLER=parentbased_traceidratio
      - OTEL_TRACES_SAMPLER_ARG=0.1
    depends_on:
      - otel-collector

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-collector-config.yaml"]
    environment:
      - UPTRACE_DSN=${UPTRACE_DSN}
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
    ports:
      - "4317:4317"
      - "4318:4318"

# Enable debug logging for Java Agent
export OTEL_JAVAAGENT_DEBUG=true

# For Spring Boot Starter, add to application.properties
logging.level.io.opentelemetry=DEBUG

# Check connectivity to collector
curl -v http://your-collector:4318/v1/traces

otel:
  exporter:
    otlp:
      endpoint: http://collector:4318
      protocol: http/protobuf

@GetMapping("/debug/trace")
public Map<String, String> debugTrace(HttpServletRequest request) {
    Map<String, String> headers = new HashMap<>();
    headers.put("traceparent", request.getHeader("traceparent"));
    headers.put("current-trace-id", Span.current().getSpanContext().getTraceId());
    headers.put("current-span-id", Span.current().getSpanContext().getSpanId());
    return headers;
}

@Bean
public TextMapPropagator textMapPropagator() {
    return TextMapPropagator.composite(
        W3CTraceContextPropagator.getInstance(),
        W3CBaggagePropagator.getInstance()
    );
}

# Reduce batch queue size
export OTEL_BSP_MAX_QUEUE_SIZE=1024
export OTEL_BSP_MAX_EXPORT_BATCH_SIZE=256
export OTEL_BSP_SCHEDULE_DELAY=2000

# Implement sampling to reduce trace volume
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

# Disable unused instrumentations
export OTEL_INSTRUMENTATION_SPRING_SCHEDULING_ENABLED=false

export OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false
export OTEL_INSTRUMENTATION_SPRING_WEBMVC_ENABLED=true
export OTEL_INSTRUMENTATION_JDBC_ENABLED=true

# Increase timeout
export OTEL_EXPORTER_OTLP_TIMEOUT=30000

# Enable compression
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

# Use async exporter
export OTEL_BSP_SCHEDULE_DELAY=5000

# JVM optimization
export JAVA_OPTS="-XX:+UseG1GC -Xms2g -Xmx4g"

# OpenTelemetry performance tuning
export OTEL_BSP_SCHEDULE_DELAY=5000
export OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512
export OTEL_TRACES_SAMPLER_ARG=0.1

# Disable unnecessary instrumentation
export OTEL_INSTRUMENTATION_LOGBACK_APPENDER_ENABLED=false

otel:
  traces:
    sampler: parentbased_always_on  # Full sampling
  exporter:
    otlp:
      protocol: grpc
      endpoint: http://localhost:4317

otel:
  traces:
    sampler: parentbased_traceidratio
    sampler.arg: 0.1  # Controlled sampling
  exporter:
    otlp:
      protocol: grpc
      endpoint: https://prod-collector:4317
      compression: gzip