clarify recommendations for instrumenting a Spring Boot application

[stevesea]

Is your feature request related to a problem? Please describe.

As a adopter of OpenTelemetry it's hard to navigate the documentation and weigh the trade-offs of how to integrate instrumentation for Spring Boot apps.

This comment on #12878 poses 3 options #12878 (comment)

1. Instrumentation in Spring Boot (Micrometer), configured to export via OTLP

   • no autoconfiguration
   • no OTel agent autoinstrumentation of client libraries
   • this recent blog post https://spring.io/blog/2024/10/28/lets-use-opentelemetry-with-spring feels 'off' IMO. OpenTelemetry isn't OTLP.
     • The telemetry exported doesn't follow OTel's semantic conventions.
     • You'll get data to your o11y platform, but data may not be immediately usable if the platform expects semconv compatibility.
     • This also puts more complication into your otel-collector configuration to handle these non-semconv instruments along with streams of data from semconv-compliant apps.

2. OpenTelemetry Spring Boot Starter

   • autoconfiguration matching the otel spec
   • missing some autoinstrumentation of the agent?
   • contrasting this option against the otel agent in the docs about what's missing

3. OpenTelemetry Java Agent

   • autoconfiguration matching the otel spec
   • autoinstrumentation
   • semconv compatibility
   • you can enable export Micrometer metrics.
     • If you do enable it, you should disable runtime-telemetry instrumentation. And, there are other weird problems in the export of some instruments. for example, I ran into this recently -- the http.server.requests Micrometer histogram metric gets exported without any buckets micrometer http.server.requests metric breaks metrics UI with IndexOutOfRangeException dotnet/aspire#6962
     • bubbling up these other config flags for micrometer export would be nice, and clarifying the docs on in what circumstances they should be toggled on https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/micrometer/micrometer-1.5/javaagent/README.md

Describe the solution you'd like

I really like this recent blog post putting the starter into context, and its section on when to use the starter -- https://opentelemetry.io/blog/2024/spring-starter-stable/

Describe alternatives you've considered

No response

Additional context

My organization runs 1100+ apps on Kubernetes and VMs. 80%+ of those applications are JVM + Spring Boot apps; the remaining are Node.js, Go, Python, or are non-Spring JVM apps (Quarkus, KTor, http4k, or otherwise).

Organizationally, we see huge benefits from OpenTelemetry:

• OTel SDKs following the configuration spec mean all our apps can be configured similarly to export telemetry to our otel-collector infrastructor.
• OTel SDKs following semantic conventions mean the telemetry from all our apps is similar when it lands at the observability platform.

But, our heavy investment in Spring Boot also means that when most dev teams look up telemetry docs and advice from the Spring Community, they can find conflicting directions. Understanding the trade-offs in interoperability isn't easy.

[trask]

hi @stevesea!

2. OpenTelemetry Spring Boot Starter

• autoconfiguration

the spring boot starter autoconfiguration should be matching the otel spec as well, can you open an issue for any specifics where you notice this is not the case?

• missing some autoinstrumentation of the agent?

yeah, this is definitely true, it's probably worth opening an issue if there's a specific instrumentation that you'd like to see integrated into the spring boot starter, as that could help with our prioritization (and of course PRs are welcome too)

• contrasting this option against the otel agent in the docs about what's missing

it's kind of covered here: https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/

would you mind opening an issue at https://github.com/open-telemetry/opentelemetry.io/issues with any specific suggestions (and tagging @open-telemetry/java-instrumentation-approvers)?

3. OpenTelemetry Java Agent

• you can enable export Micrometer metrics [but]

bridging different telemetry collection SDKs is always going to be challenging, which is one of the reasons OpenTelemetry was created and OpenTracing, OpenCensus and Jaeger SDKs have been deprecated in favor of it

it would be great if you can open issue(s) if there are things missing in OpenTelemetry that are preventing you from migrating from Micrometer

at the same time, we would definitely welcome contributions to make the interoperability with Micrometer smoother and improve the Micrometer bridging documentation

[stevesea]

the spring boot starter autoconfiguration should be matching the otel spec as well, can you open an issue for any specifics where you notice this is not the case?

Oops! I was unclear, I'll update the ticket. I meant that autoconfiguration is a positive aspect of using the OpenTelemetry spring boot starter, not that it was missing.