Java Instrumentation Documentation

[jaydeluca]

Context

This issue is a followup from the Comms SIG on September 3, 2025 (Recording: discussion is from 17:30 until 46:00), and is intended to continue the discussion about how we would like to proceed to move this forward.

Note: There is an existing proof of concept that demonstrates the functionality laid out in this issue.

Desired feature or idea:

As a user of the java agent or standalone java library instrumentation, I want documentation that allows me to answer the following questions:

• What technologies and libraries are instrumented by the agent? Which versions of those libraries?
• The library I use is supposed to be supported, what telemetry will be emitted? What attributes will the spans and metrics have?
• Are there any configurations I can enable to get additional attributes on my metrics or spans?
• Are there any configurations I can enable to get more/less metrics or spans for the libraries I use?
• I’m about to upgrade my auto-instrumentation from version x to version y, what telemetry or attributes changed?

I would like to propose that we build a standalone "Instrumentation Explorer" as a part of the opentelemetry.io documentation suite.

The following information should be included for each instrumentation:

• A description of what it does
• A summary of semantic conventions it follows (ex: database client metrics, consumer messaging spans etc)
• The type(s) of instrumentation it is
  • Metric producer
  • Span producer
  • Context Propagator
  • HTTP Route Enricher
  • Library domain Enricher
• Information about the libraries it instruments, what are the packages and versions
• What configuration options are available and what they do
• The emitted telemetry
  • A list of metrics with their types, units, descriptions, and attributes
  • A list of Spans grouped by SpanKind with a superset of all attributes per SpanKind

This information should be available and explorable by agent version. The following features should be supported:

• List and search a catalog of all available instrumentations.
  • Searchable / filterable by instrumentation type (library vs agent), semantic conventions, functionality type (metrics, spans, context propagators, enrichers)
• For an instrumentation, you should be able to view the associated telemetry and attributes emitted for each configuration option
• Able to compare telemetry between two different versions of the agent to get migration/upgrade guides

Additional Context:

There are currently existing docs that provide some of this information - see the Supported libraries page in the instrumentation repo. Howevever, github readme's are not indexed by google and therefore are not easily discoverable by users.

I would like to move this general list to the documentation site as part of this effort, and link from that page to the instrumentation explorer site for those that want to dig deeper.

Related Issues:

• Project proposal: Registry Data Quality Improvements community#2246
• Expose Collector component metadata in registry  #4921
• Move Java Libraries / Frameworks to the website #3040
• Instrumentation Metadata System opentelemetry-java-instrumentation#13468

[svrnm]

As discussed during the SIG call I am very open to this idea, however I would like this to be expanded to other languages + the collector as well to eventually supersede the current registry.

This would also make the proposal of this project void: open-telemetry/community#2246

Of course, to make rapid progress here, focusing on only a subset is what we should be doing, we just need to consider that we might want to expand this into other languages.

A few comments on next steps:

• I think it would be great to prototype an addition of another language (Go, Node.JS, Python) and the collector and see what it might look like if we add them (cc @mx-psi)
• Besides the registry a larger project exists: Artifact Hub, I would be curious if/how these projects could interact
• We need at least 2 people, ideally 3 that are willing to contribute to this project consistently. Not sure if forming a dedicated SIG is what we should be doing, but we need to be sure about resourcing, because this was the main blocker so far for making such a project a reality.
• Having those resources we can raise a project proposal on the community repo and make it official.

Thanks!

---

On a tangential note, the existing Supported libraries page could (or should) live on the opentelemetry.io website for better discoverability, but that might not be necessary anymore if we make progress with this project.

[Tharanishwaran]

Hi @jaydeluca @svrnm,
I'd like to work on this issue.I have recent Java tooling and CNCF contribution experience.Please let me know if I can be assigned.

[jaydeluca]

hey @Tharanishwaran, thank you for your interest! This issue is more of a placeholder as we work out the next steps and project plan for this initiative. We will keep this issue updated as we make some decisions and hash out the body of work to be done, so stay tuned.

In the meantime, if you are interested in contributing to some of the work being done to enable this in java, you can take a look at this project board in the java instrumentation repo. Feel free to reach out on any of those issues if you have interest in helping or have any questions.

[Tharanishwaran]

Thanks @jaydeluca! I'll check out the project board and look for ways to contribute to the foundational work. Looking forward to updates on the main project as it develops.

[jaydeluca]

I am closing this issue now that we have officially launched the Ecosystem explorer project.

@Tharanishwaran feel free keep an eye on the issues in that repo in case you see anything of interest to you, we're looking for contributors! We're still fleshing out the backlog, but there will be a lot more added soon