open-telemetry / opentelemetry.io

The OpenTelemetry website and documentation
https://opentelemetry.io
Creative Commons Attribution 4.0 International
548 stars 1.21k forks source link

Add more detail to the Java Agent Extension docs #4910

Open jaydeluca opened 3 months ago

jaydeluca commented 3 months ago

Desired feature or idea:

As a user of the java agent, I want documentation that lays out everything I need to know in order to understand use cases for extensions, how to leverage an existing extension, and how to approach writing my own. The existing page provides context for use cases but doesn't have any of the technical details in order to get started.

There is a lot of good information in the example section of the instrumentation repo and elsewhere that I think would be worth unifying and porting over.

Additional context:

Here is what I am thinking for the updated page structure:

## Introduction
all the current information around use cases will remain here.

## Loading an extension at runtime
detail using the `-Dotel.javaagent.extensions` startup command.

## Embedding extensions in the Agent
detail the `extendedAgent` gradle task approach from the example repo

## Writing an extension
provide example code for an extension, and the steps needed to use it with an agent

## Extension examples
keep this existing section with a link to the example section of the instrumentation library

I would be happy to work on contributing this.

svrnm commented 3 months ago

Thanks @jaydeluca, this would be a great addition indeed!

@open-telemetry/java-approvers please take a look as well, is this something the SIG would like to see as well?

KarstenSchnitter commented 2 months ago

Some ideas, what could be documented: