Add Libraries doc or section for Java, showing how to set up library instrumentation without an agent

[cartermp]

There's scenarios where you may not want to/cannot use the java agent for autoinstrumentation, but do want to get library instrumentation. This should be documented with code samples, similar to the .NET page: https://opentelemetry.io/docs/instrumentation/net/libraries/

[nerudadhich]

Hi @svrnm, I would like to contribute on this. I am planning to add a SpringBoot example for this, in case you have any other idea let me know I can explore that option as well.

Also would you mind assigning this to me ?

[svrnm]

HEy @nerudadhich, thanks for offering your help! For SpringBoot we have the following in process already:

#3377

SpringBoot seems to be a "special case" because of the Starter being available, I think in the library page there should be something easier and more clearer of beeing an Instrumentation Library.

@open-telemetry/java-approvers any suggestions/comments?

[nerudadhich]

Hi @svrnm I am planning to add java-http-client end to end working example.

Plan:

1. build.gradle - For dependency
2. SampleAutoConfigure.java - To initialise otel sdk
3. TestOtelHttpClient.java - To make external http api call using HttpClient (This will generate traces)
4. Jaeger docker-compose link to start in local

Let me know if this looks fine to you ?

[svrnm]

Let me know if this looks fine to you ?

Overall that sounds good to me, there are a few adjustments I would like to make.

Ultimately this should be the content of Using instrumentation libraries, which is very basic right now. At the end it should have more similarity with the one you can see for JavaScript

So, here is my proposal how it should look like:

Begin the page with the following:

• A language-independent introduction to the page (reuse the existing ones from the pages shared above)
• A note on "natively instrumented libraries" as it exists on the JS one (copy & paste, we can refine the text later)

The "real" work is the "Use Instrumentation Libraries" section:

• Build it on top of the "Getting Started"/"Manual Instrumentation" example, i.e. use the "roll the dice application", e.g. there is a client using java-http-client calling that as a backend
• Use whatever you need for that (build.gradle, SampleAutoConfigure.java, TestOtelHttpClient.java, etc.), but keep it in sync with the other examples.
• Do not use Jaeger or docker-compose here, you can make a reference to the Exporters page, that this can be used/done, but using Console exporters is good enough.

[nerudadhich]

Thanks @svrnm this sounds good to me. Will work and raise a PR.

[svrnm]

Thanks @svrnm this sounds good to me. Will work and raise a PR.

nice :-)

[cartermp]

Also @tylerbenson don't feel ashamed to copy-paste from the JS docs or something else and just tweak! Especially for the commentary between code samples, more uniformity (if it makes sense) is generally good.

[nerudadhich]

Hi @svrnm I have raised the PR, the preview is available here.

Please review and suggest if anything needs to update.
Thank you.

[jeanbisutti]

@cartermp

There's scenarios where you may not want to/cannot use the java agent for autoinstrumentation

What do you have in mind?

Is it for the following reasons or others?

https://opentelemetry.io/docs/languages/java/automatic/spring-boot/

[cartermp]

Those are good reasons, yes, although I think there's a few more:

• Runtime overhead of the agent being unacceptable (we've seen people report up to 20% increase cpu utilization)
• General desire not to run an agent

[jeanbisutti]

• Runtime overhead of the agent being unacceptable (we've seen people report up to 20% increase cpu utilization)

You probably mean the Java agent overhead after the application startup.

In this case, the user could try to turn off some Java agent instrumentations.

[cartermp]

You probably mean the Java agent overhead after the application startup.

Nope, in this case what we observed had nothing to do with startup. The only way forward was to explicitly turn on just a few instrumentations in-app and focus on manual instrumentation.