Some content on the website seems a bit out of date

[steverao]

What happened? Describe the problem that occurred.

I found Suppressing specific agent instrumentation in website is inconsistent with the latest supported-libraries.
There are some problems I think maybe we need to solve them:

1. There are some new libraries such as Alibaba Druid and MyBatis in supported-libraries, but they can't find in Suppressing specific agent instrumentation.
2. Some librarie's name are also inconsistent on both sides. Such as in website, Cassandra's name is Apache Cassandra, but its name is Cassandra Driver in supported-libraries.

What did you expect would happen? Describe the expected result/output.

How to update the website document before? Whether we should come up with a method ensure that both parties can be consistent in a timely so that similar problems will not continue to occur？

[svrnm]

@open-telemetry/java-instrumentation-approvers @open-telemetry/java-approvers please take a look

[breedx-splk]

@open-telemetry/java-instrumentation-approvers did we auto-generate that list once upon a time? I'm guessing it wasn't hand edited.....was it?

[jeanbisutti]

supported-libraries seems hand edited and should probably be migrated to the https://opentelemetry.io/ website.

@steverao Don't hesitate to create PRs to improve the documentation and suggests automatic checks if it would be possible without too much effort.

[steverao]

I think whether we don't provide the table here in the future, and add instrumentation name in supported tables. The final result is similar to the picture below:

In this way, the content is relatively concentrated and easy to maintain. All other places that involve relevant content can be quoted directly. Such as enable-only-specific-instrumentation, suppressing-specific-agent-instrumentation and disabled-instrumentations.
@open-telemetry/java-instrumentation-approvers What do you think or do you have any better suggestions?

[jeanbisutti]

I think whether we don't provide the table here in the future, and add instrumentation name in supported tables. The final result is similar to the picture below: In this way, the content is relatively concentrated and easy to maintain. All other places that involve relevant content can be quoted directly. Such as enable-only-specific-instrumentation, suppressing-specific-agent-instrumentation and disabled-instrumentations. @open-telemetry/java-instrumentation-approvers What do you think or do you have any better suggestions?

@steverao You seem to suggest to add a new column with the automatic instrumentation name to the instrumentation libraries table.

Generally, if a user has configured the OpenTelemetry Java agent, then he does not need instrumentation libraries. So, it may make sense to document the instrumentation of the Java agent and the instrumentation libraries on different pages, and to create a new page for the instrumentation libraries on the https://opentelemetry.io/ website.

All other places that involve relevant content can be quoted directly. Such as enable-only-specific-instrumentation, suppressing-specific-agent-instrumentation and disabled-instrumentations.

disabled-instrumentations does not seem documented on the https://opentelemetry.io/ website. The https://opentelemetry.io/docs/languages/java/automatic/configuration/ should probably be updated.

[jeanbisutti]

In addition, I would sugest to add the framework links and a Semantic Conventions column to the this table.

@steverao and @open-telemetry/java-instrumentation-approvers WDYT?

[steverao]

I think whether we don't provide the table here in the future, and add instrumentation name in supported tables. The final result is similar to the picture below: In this way, the content is relatively concentrated and easy to maintain. All other places that involve relevant content can be quoted directly. Such as enable-only-specific-instrumentation, suppressing-specific-agent-instrumentation and disabled-instrumentations. @open-telemetry/java-instrumentation-approvers What do you think or do you have any better suggestions?

@steverao You seem to suggest to add a new column with the automatic instrumentation name to the instrumentation libraries table.

Generally, if a user has configured the OpenTelemetry Java agent, then he does not need instrumentation libraries. So, it may make sense to document the instrumentation of the Java agent and the instrumentation libraries on different pages, and to create a new page for the instrumentation libraries on the https://opentelemetry.io/ website.

All other places that involve relevant content can be quoted directly. Such as enable-only-specific-instrumentation, suppressing-specific-agent-instrumentation and disabled-instrumentations.

disabled-instrumentations does not seem documented on the https://opentelemetry.io/ website. The https://opentelemetry.io/docs/languages/java/automatic/configuration/ should probably be updated.

Yes, my idea is to add new column in supported tables. Just maintain one table, it won't miss to update information when someone adds a new instrumentation to code repo(Solution 1).
Your thought about to create a new table in website and list the instrumentation of the Java agent and the instrumentation libraries on different pages(Solution 2). I think it's another way to optimize the current situation.
The current approach only lists the [name] table in suppressing-specific-agent-instrumentation, and there is no clear explanation of the context of other places where [name] is mentioned, which is not particularly user-friendly：）
As you mentioned above, If we choose solution 2, maybe we can edit a new table in other places on the website, besides instrumentation [name] and we can add some other columns, such as framework links and semantic conventions. If we choose this way, It will make maintenance a little more complicated, but I think it is acceptable. We can pay attention to it when merging new instrumentation code later.
Finally, for the point of disabled-instrumentations. I think we can just list the framework according the supported tables instead of instrumentation name, and put the [name] table link, users can know how to enable an instrumentation or disable one.

[svrnm]

Yes, my idea is to add new column in supported tables. Just maintain one table, it won't miss to update information when someone adds a new instrumentation to code repo(Solution 1).

Just to throw this in as a perspective from docs: We should aim to have material on opentelemetry.io to be the source of truth, and (if possible) not the repositories, especially for those end-user facing details. We have way to many documentation fragmented across the individual repositories making it really hard for end-users to find the things they need.

If this is a workflow issues ("it won't miss to update information when someone adds a new instrumentation to code repo"), we should address this as such and collaborate on a solution. This can reach from a metadata file stored in the repository that we pull from OR (my preferred solution) this details become part of the registry entries per instrumentation library (see https://github.com/open-telemetry/opentelemetry.io/blob/main/data/registry/instrumentation-java-apache-httpclient.yml and https://opentelemetry.io/ecosystem/registry/?language=java&component=instrumentation), which eventually would us even allow to make this data searchable via the Registry.

[cartermp]

Yep, I think there's a technical solution we can employ to keep stuff always up to date. Copying data from the repos got us pretty far for now but for stuff like this we should use a path that's largely automated by the bots.

[jeanbisutti]

Just to throw this in as a perspective from docs: We should aim to have material on opentelemetry.io to be the source of truth, and (if possible) not the repositories

So, it seems also to make sense for the doc approvers to move the list of instrumentation libraries to the website. It could be done with one PR. The documentation of each instrumenation libraries could perhaps be moved with other PRs.

The next question seems to be: should we have one table for the instrumentations of the Java agent and another one for the instrumentation libraries, or only one table?

As I mentioned before, I would prefer two tables from a user perspective:

Generally, if a user has configured the OpenTelemetry Java agent, then he does not need instrumentation libraries. So, it may make sense to document the instrumentation of the Java agent and the instrumentation libraries on different pages, and to create a new page for the instrumentation libraries on the https://opentelemetry.io/ website.

I will add the question about one or two tables to the agenda of the OTel Java SIG today.

Today, the Java agent has many instrumentations ar there are many instrumentation libraries. It seems to have became not frequent to add a new instrumentation to the Java agent or a new instrumentation library. So, about the documentation maintenance, I would suggest to fix the current inconsistencies (see #4092 (comment)), and and to see over time if other inconsistencies are frequently introduced.

[jeanbisutti]

@steverao The topic has been discussed in the last Java SIG. It has been suggested to:

• Move the documentation of the Java instrumentation libraries to https://opentelemetry.io/
• Don't mix the automatic instrumentations of the OpenTelemetry Java agent with the Java instrumentation libraries
• Use metadata files in the long term

@open-telemetry/docs-approvers Where would you recommend placing the table of the Java instrumentation libraries on the website?

[jeanbisutti]

To sum up the shorty-term improvements discussed:

• There are some new libraries such as Alibaba Druid and MyBatis in supported-libraries, but they can't find in Suppressing specific agent instrumentation.

• Some librarie's name are also inconsistent on both sides. Such as in website, Cassandra's name is Apache Cassandra, but its name is Cassandra Driver in supported-libraries.

• Table of the automatic instrumentations:

add some other columns, such as framework links and semantic conventions

• Move the table of the Java instrumentation libraries to the website (waiting for a response to Some content on the website seems a bit out of date #4092 (comment))

@steverao If you would be interested in creating doc PRs to address these points, that would be great contributions useful for the OpenTelemetry users.

[steverao]

To sum up the shorty-term improvements discussed:

• There are some new libraries such as Alibaba Druid and MyBatis in supported-libraries, but they can't find in Suppressing specific agent instrumentation.

• Some librarie's name are also inconsistent on both sides. Such as in website, Cassandra's name is Apache Cassandra, but its name is Cassandra Driver in supported-libraries.

• Table of the automatic instrumentations:

add some other columns, such as framework links and semantic conventions

• Move the table of the Java instrumentation libraries to the website (waiting for a response to Some content on the website seems a bit out of date #4092 (comment))

@steverao If you would be interested in creating doc PRs to address these points, that would be great contributions useful for the OpenTelemetry users.

The time of Java SIG meeting starts at one o'clock in the morning in my country, so It's hard for me to attend the last meeting：( I saw the replay and agree with that decision. Please assign the issue to me, I will finish it in this week.

[jeanbisutti]

@steverao Indeed, it's very late for you. Thank you for your help!

[svrnm]

Where would you recommend placing the table of the Java instrumentation libraries on the website?

There are 2 pieces for me:

• Have them all in the registry (I have a semi automatic process to crawl them, see https://github.com/open-telemetry/opentelemetry.io/tree/main/scripts/registry-scanner), so I can run this once again to see what we are missing
• We can build from that details a list on https://opentelemetry.io/docs/languages/java/libraries/, or we start with something manual and I can see how much I can get this automated.

[theletterf]

A related suggestion: open-telemetry/opentelemetry-collector-contrib#24189