[Page feedback]: Adding extensions is poorly documented

[sydneyosbornagility]

URL

https://opentelemetry.io/docs/zero-code/java/agent/extensions/

Description

It has been extremely difficult to figure out how to wire up BaggageSpanProcessor extension. We have pretty much given up.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[tiffany76]

Hi @sydneyosbornagility, thank you for reporting your issue and we're sorry you're having so much trouble.

I'm going to ask the @open-telemetry/java-instrumentation-approvers to see if they can help fill in the gap.

[jaydeluca]

@sydneyosbornagility the page you are referencing is for building extensions, which is an approach to extending the java agent by packaging code in a jar you can inject with -Dotel.javaagent.extensions=... is that what you are looking for assistance with?

If so, we do have an open issue to improve the extensions page here, which unfortunately we just haven't gotten around to yet. If this is indeed what you are looking for help with, could you see if the topics covered in that issue would address your needs? If not, could you provide more details in where you got stuck or had issues?

Or when you say extensions are you referring to the Baggage processor contrib component? If so, I just want to make sure you were able to find the readme? Is that the piece you found lacking?

If you could provide some additional details of your specific troubles/confusion you had, and what you were trying, it would help us greatly in knowing what we can do to improve.

[sydneyosbornagility]

@jaydeluca yes, as noted in the open issue, the existing page is a bit of a tease as to why you want to do it but short on information as to how. The Baggage Processor readme also was pretty unclear - it leaves one with the impression that you just need to add some configuration and voila! without also explicitly deploying the extension in some way.

We did end up building a javaagent jar with the extension embedded that finally worked, but the instructions for that are minimal, and there was a lot of trial and error before things were in the right place. The gradle example was pretty much Greek to me.

So if "detail the extendedAgent gradle task approach from the example repo" means explain exactly what is going on there, then yes, I agree with that suggestion.

[sydneyosbornagility]

fwiw, here is an issue I am currently having - answers to these questions would be helpful open-telemetry/opentelemetry-java-instrumentation#2763 (comment)

…

On Fri, Sep 26, 2025 at 11:35 AM Jay DeLuca ***@***.***> wrote: *jaydeluca* left a comment (open-telemetry/opentelemetry.io#7793) <#7793 (comment)> @sydneyosbornagility <https://github.com/sydneyosbornagility> the page <https://opentelemetry.io/docs/zero-code/java/agent/extensions/> you are referencing is for building extensions, which is an approach to extending the java agent by packaging code in a jar you can inject with -Dotel.javaagent.extensions=... is that what you are looking for assistance with? If so, we do have an open issue to improve the extensions page here <#4910>, which unfortunately we just haven't gotten around to yet. If this is indeed what you are looking for help with, could you see if the topics covered in that issue would address your needs? If not, could you provide more details in where you got stuck or had issues? Or when you say extensions are you referring to the Baggage processor contrib component <https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/baggage-processor>? If so, I just want to make sure you were able to find the readme? Is that the piece you found lacking? If you could provide some additional details of your specific troubles/confusion you had, and what you were trying, it would help us greatly in knowing what we can do to improve. — Reply to this email directly, view it on GitHub <#7793 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BMVIAEGRXW5JM5X6GCNOARL3UWBNDAVCNFSM6AAAAACG2LZDQ6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGMZZHE3TEMJRGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[svrnm]

@open-telemetry/java-approvers PTAL

[breedx-splk]

Yeah I think this is a reasonable request -- and I agree that the current page is more "why" than "how". The page DOES link to the examples repo, which I think has a LOT more details on how, including concrete code examples. There's a balance about how much or how little code to put in the docs repo tho huh?

[svrnm]

@breedx-splk indeed our answer how to manage code in the docs repo is still not satisfying, but in general having more concrete code examples is always helpful. I will mark this as "help wanted" except someone already in this conversation wants to pick it up

[jaydeluca]

@sydneyosbornagility I have a PR up where I have rewritten the page, making sure to try and take your experience and comments in mind. It still needs to be reviewed by the Java SIG (so it might change), but if you are interested in taking a look and providing any feedback on the content, it would be appreciated. Either way, your input on this issue and the linked discussion has been very helpful, thank you for raising this.