Rewrite java agent extensions page #8264
Conversation
|
/fix:dict |
|
✅ |
| @@ -1,23 +1,41 @@ | |||
| --- | |||
There was a problem hiding this comment.
[For reviewers] I took the approach of including code examples instead of just linking to the example in the java agent repo because I personally don't like the user experience of having to jump around and reference multiple sources when reading documentation. It also didn't seem like the code would change frequently, so upkeep shouldn't be too bad (hopefully).
With that being said, If we think this is too verbose, I can remove the code example and any other sections and just link out to the example code.
There was a problem hiding this comment.
I agree with you, having code examples directly into documentation without having to open a separate tab is definitely a better experience, one of the main downsides though is keeping this code relevant and maintained over time.
Maybe it's a dumb idea, but if we were able to put some markers in the example in instrumentation and then automatically extract and inline the relevant parts into this documentation it would be nice, but that sounds also quite brittle and could easily break over time.
There was a problem hiding this comment.
we actually have this mechanism - but it's not documented and doesn't run on a regular basis
@svrnm is this something you're planning to do or are looking for help?
|
|
||
| - _"I want to customize instrumentation without modifying the instrumentation"_: | ||
|
|
||
| The `InstrumenterCustomizerProvider` extension point allows you to customize |
There was a problem hiding this comment.
is it worth mentioning that InstrumenterCustomizerProvider is an experimental api?
|
|
||
| There are two ways to use extensions with the Java agent: | ||
|
|
||
| 1. **Load at runtime** using the `-Dotel.javaagent.extensions` option (described |
There was a problem hiding this comment.
Load at runtime is a bit weird, extensions added to agent are also loaded at runtime. Perhaps we shoudl use As a separate jar file or something like that.
|
|
||
| ### Basic Usage | ||
|
|
||
| Extensions can be loaded at runtime using the `otel.javaagent.extensions` system |
There was a problem hiding this comment.
could mention that OTEL_JAVAAGENT_EXTENSIONS env var also work
| 1. Creates an | ||
| [isolated class loader](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/javaagent-structure.md#extension-class-loader) | ||
| for each extension JAR to prevent conflicts between extensions |
There was a problem hiding this comment.
This is an implementation detail. We could consider giving up on it and loading extensions together with the agent code. This would for example allow agent code that uses ServiceLoader.load without specifying a class loader to discover spis from extensions. Admittedly this is less of an issue now that the sdk seems to always use user specified class loader for looking up spis.
| 3. Automatically applies shading to extension classes at runtime (extensions use | ||
| normal OpenTelemetry imports, and the agent handles compatibility | ||
| automatically) |
There was a problem hiding this comment.
I think the shading is kind of an advanced topic, hopefully most of the extension users don't even realize that something is shaded. If we are going to mention it then I think the goal should be to reduce confusion for the ones who try to debug the extension and notice that things aren't quite as they'd expect.
| #### Dependencies Provided by Agent (use `compileOnly`) | ||
| These APIs are available at runtime from the agent class loader: |
There was a problem hiding this comment.
Not completely true, some of these are in boot loader. Could instead say that these apis are provided by the agent.
| ### Using @AutoService | ||
| The `@AutoService` annotation automatically generates the required |
There was a problem hiding this comment.
for @AutoService to work you also need to configure the annotation processor
| ### AutoConfigurationCustomizerProvider | ||
| The main entry point for customizing SDK configuration. This allows you to: |
There was a problem hiding this comment.
Do we have sdk documentation where we could link for this? Should it be mentioned that these won't work with the declarative configuration?
| ### Accessing the Current Span | ||
| In instrumentation advice classes, use `Java8BytecodeBridge` to access the |
There was a problem hiding this comment.
Should we explain why and when one needs to use Java8BytecodeBridge instead of Span.current() or Context.current()?
Jumping to advice while skipping InstrumentationModule and TypeInstrumentation feels a bit confusing.
| ### Sharing Data via Context | ||
| Use the OpenTelemetry `Context` API to share data throughout the request |
There was a problem hiding this comment.
Imo this is also confusing. Could start with introduction to instrumentation api, context customization is really one of the less used aspects there.
5 participants
Fixes #4910
Fixes #7793
Deploy Preview: https://deploy-preview-8264--opentelemetry.netlify.app/docs/zero-code/java/agent/extensions/