OpenTelemetry Integration with Spring Boot 4.x

Recommended Configuration and Common Pitfalls

1. Recommended Approach

For new Spring Boot 4.x applications, the preferred and supported integration path is the native starter.

• Library: org.springframework.boot:spring-boot-starter-opentelemetry
• Rationale: Avoids conflicts from legacy community starters and ensures full Boot 4 compatibility.

Key Features

• Native Micrometer Tracing integration
• Auto-configured OpenTelemetry SDK
• Automatic instrumentation for RestClient, RestTemplate, and WebClient
• OTLP/Zipkin export support
• Supports AOT/GraalVM compilation

Required Additional Dependencies (Maven)

Add the bridge and the exporter to your pom.xml:

<dependencies>
    <!-- Core OTel Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-opentelemetry</artifactId>
    </dependency>

    <!-- Micrometer Bridge -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-otel</artifactId>
    </dependency>

    <!-- Exporter (e.g., Zipkin via OTLP) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-zipkin</artifactId>
    </dependency>
</dependencies>

---

2. Configuration Example

Add the following to your application.yml.

management:
  opentelemetry:
    resource-attributes:
      service.name: my-app
  tracing:
    sampling:
      probability: 1.0  # Adjust as needed for production (0.1 = 10%)

# OTLP exporter (Zipkin-compatible via collector)
otel:
  exporter:
    otlp:
      endpoint: http://localhost:4317

Important Notes

1. Bean Injection: Ensure the application retrieves beans from the application context. new RestClient() will not be instrumented. Use the auto-configured builders (RestClient.Builder, etc.) injected by Spring.
2. Zipkin: For Zipkin via OTLP, the exporter handles conversion automatically; direct Zipkin endpoint configuration is optional.

---

3. Approaches to Avoid or Use with Caution

Approach	Issue	Recommendation
Community opentelemetry-spring-boot-starter (pre-late-2025 versions)	References Boot 3 auto-config classes (e.g., RestClientAutoConfiguration); may cause ClassNotFoundException; incomplete Boot 4 conditional checks.	Use only latest release with explicit Boot 4 support; prefer Spring native starter.
micrometer-tracing-bridge-brave + zipkin-reporter-brave	Legacy path; no default auto-configuration in Boot 4; may not create spans automatically.	Migrate to OpenTelemetry bridge.
References to Boot 3 auto-config classes	ClassNotFoundException or missing beans (due to package changes in Boot 4).	Update imports or use Spring starter for auto-configuration.
Manual interceptors on RestClient / RestTemplate	Propagation and auto-configuration may be skipped; spans may not appear.	Use auto-configured builders provided by the Spring Boot starter.
Mixing Java Agent with library starter	Duplicate spans or instrumentation conflicts.	Use either the Java Agent (broad instrumentation) or the starter (config simplicity), not both.

---

4. Additional Best Practices

• Sampling: Set management.tracing.sampling.probability according to expected load. Use 1.0 in development to ensure all traces are captured.
• Custom Metrics: Use ObservationRegistry for custom observations if needed.
• Logs: Enable MDC logging for trace and span IDs to correlate logs and traces.
• Version: Confirm Spring Boot version 4.0.1+ to include bug fixes related to RestClient auto-instrumentation.
• BOM: Verify that exporters and tracing dependencies are compatible; rely on the Spring Boot BOM for dependency management.

---

5. References

• Spring Boot 4.x Reference Documentation:
  • Actuator Observability
  • Micrometer Tracing
• Spring Blog Post (November 18, 2025): OpenTelemetry with Spring Boot
• OpenTelemetry Java Instrumentation Changelog / GitHub: Community starter releases with Boot 4 fixes (PR #15459, #15433, etc.)
• Spring Boot 4 Migration Guide & Release Notes: Boot 4 starter introductions, modular observability, AOT/native support.