Comments (16)
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.
from opentelemetry.io.
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.
from opentelemetry.io.
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.
from opentelemetry.io.
@open-telemetry/java-instrumentation-approvers @open-telemetry/java-approvers please take a look
from opentelemetry.io.
@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?
from opentelemetry.io.
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?
from opentelemetry.io.
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.
from opentelemetry.io.
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?
from opentelemetry.io.
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.
from opentelemetry.io.
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.
from opentelemetry.io.
@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?
from opentelemetry.io.
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 #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.
from opentelemetry.io.
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.
from opentelemetry.io.
@steverao Indeed, it's very late for you. Thank you for your help!
from opentelemetry.io.
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.
from opentelemetry.io.
A related suggestion: open-telemetry/opentelemetry-collector-contrib#24189
from opentelemetry.io.
Related Issues (20)
- Python Benchmark page layout is not in a proper format HOT 5
- NodeJS auto instrumentation does not generate metrics (docs/languages/js/automatic) HOT 3
- [Traces Documentation] Clarification on events vs span attributes HOT 4
- Missing Java Resource Detectors from OpenTelemetry Registry
- I Tried to Pull Request this issue #4565 but got spelling error: 'Warning: Unknown word (Chronosphere)' HOT 3
- Missing "Next Steps" section in Java resources page
- Gateway documentation
- Incorrect display of "<" and ">" characters HOT 4
- Using Metrics and Traces to diagnose a memory leak: recommendationCache -> recommendationServiceCacheFailure HOT 1
- [CI] GH actions warning: EBADENGINE Unsupported engine
- Automatic Instrumentation HOT 4
- Add GitHub Star counter to Website HOT 8
- incorrect component.Type tutorial guidance since OTEL v0.97.0 HOT 5
- How to access Feature Flag UI in Demo Screenshots HOT 3
- Embed source code snippets from example repos HOT 6
- Add list of metrics by level to Collector's internal telemetry docs HOT 3
- Add a new persona: My Persona
- Add note to Contribution Guide that it's for docs and link to community guidelines HOT 1
- Permission denied issue for file exporter HOT 1
- Highlight OCB in the Collector docs HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from opentelemetry.io.