Java programmatic configuration should not be suggested by default

[jeanbisutti]

What needs to be changed? Describe the update that is required.

The Java manual instrumentation page provides an example based on the Spring Boot framework. Some users could find this page and starts to do programmatic configurations with Spring Boot. However, the Java agent, or the OpenTelemetry starter for some cases such as GraalVM native images, should be the options suggested first for Spring Boot in the documentation.

What is the name + path of the page that needs changed?

Manual Instrumentation docs/instrumentation/java/manual/

cc @open-telemetry/java-approvers @open-telemetry/java-instrumentation-approvers

[jeanbisutti]

This issue began to be discussed during the Java SIG meeting of January 4, 2024. Some options have been suggested:

• The Java manual instrumentation page could show an example not based on a microservice framework (Spring Boot, Quarkus)
• the Java manual instrumentation page could give pointers to the Spring Boot page and the new Quarkus page (cc @brunobat).

[svrnm]

Thanks for raising this issue @jeanbisutti, I am not sure if I understand the title of this issue correctly + the description of it: to me it sounds that using spring boot is the problem and not "programmatic configuration". I am OK with switching the framework, but then we also need to consider chaning it as well for the getting started to keep consistency. What alternative options do we have? Spring Boot is used because the example is fairly small and allows us to express everything that is needed in only a few lines of code.

[theletterf]

I think the best option is number 1 from Jean's comment, that is, showing an example that doesn't instrument a framework. Couldn't we use the dice roll demo app for that?

[jeanbisutti]

@svrnm

to me it sounds that using spring boot is the problem and not "programmatic configuration"

The problem is to implicitly incite people to use programmatic configuration with Spring Boot. We have seen an issue doing this in the opentelemetry-java-instrumentation repo.

I am OK with switching the framework, but then we also need to consider chaning it as well for the getting started to keep consistency.

I don't think. The getting started uses a Spring Boot application with the OpenTelemetry Java agent. Spring Boot is know by a lot of Java programmers and the Java agent should cover most of the user needs with Spring Boot. I will create a PR to clarify more when it could be interested to use the OTel starter with Spring Boot and not the Java agent.

Spring Boot is used because the example is fairly small and allows us to express everything that is needed in only a few lines of code.

This point was mentioned by @jack-berg (I think) during the last Java SIG meeting.

[jeanbisutti]

I think the best option is number 1 from Jean's comment, that is, showing an example that doesn't instrument a framework.

It's the most time-consuming option to change the doc.

Couldn't we use the dice roll demo app for that?

@theletterf You may mean in the doc but not in the opentelemetry-demo repo?

[svrnm]

My argument for switching the framework for the getting started as well, is not only around "what people know", but also for maintaining consistency. If people go through the getting started with the Spring Boot App, then switch to manual instrumentation and are presented with an example app that does something entirely different, this is a break in their user experience.

[theletterf]

Any update?