research(js): add JavaScript instrumentation metadata research docs#507
Conversation
✅ Deploy Preview for otel-ecosystem-explorer canceled.
|
|
Hey @jaydeluca here's the research doc under projects/ as discussed. The main finding on telemetry is that only 8/47 packages have any structured span or attribute data under a dedicated heading, and all 8 use different heading names. aws-sdk is the only one with a proper markdown table. The rest either mention telemetry in prose or not at all. The 01-metadata-audit doc covers what can be automated today in a Phase 1 watcher, and 02-telemetry-coverage has the full breakdown of what exists and what's missing across all 47 packages. Happy to start on the watcher architecture next, or do a deeper pass on the 8 packages with structured telemetry first if that's more useful. |
jaydeluca
left a comment
jaydeluca
left a comment
There was a problem hiding this comment.
great stuff!
I think we could get started with a watcher that pulls the information thats readily available for now.
After that, or in parallel, I would love to next explore if there is the ability for us to setup a system like we have in java instrumentation, where we run the integration tests for each instrumentation in order to collect and analyze the emitted telemetry to automatically document it. If we can build something like that, it could help us close the gap on the telemetry data.
When you are ready for exploring that piece (and if you are interested), I can provide more context into how we do it in java
| The long-term fix is contributing tooling back to js-contrib that generates READMEs from structured | ||
| metadata files, solving the problem at the source rather than parsing inconsistent documentation | ||
| downstream. |
There was a problem hiding this comment.
👍 the work we are doing with this research should help us put together a plan and proposal we can bring to the javascript SIG, and then we help them implement it.
|
|
||
| ## Open questions | ||
|
|
||
| 1. Should the watcher use a sparse Git clone or GitHub API calls? (Git clone is faster for bulk |
There was a problem hiding this comment.
due to the number of modules, I would probably start with a git clone and then we can walk the directory structure to identify the modules
|
|
||
| 1. Should the watcher use a sparse Git clone or GitHub API calls? (Git clone is faster for bulk | ||
| reads, API is simpler for CI) | ||
| 2. What is the minimum viable schema for Phase 1 - which fields must be present before the Explorer |
There was a problem hiding this comment.
the contents of the "What is machine-readable today" section of the audit file is a great start
| 3. Is there appetite in the js-contrib community to standardize telemetry documentation format or | ||
| add metadata.yaml files? | ||
| 4. How should the Explorer handle the 6 packages with no supported versions heading? | ||
| 5. Should unmaintained packages (empty owner arrays) be included in the registry or excluded? |
| can show a JS package page? | ||
| 3. Is there appetite in the js-contrib community to standardize telemetry documentation format or | ||
| add metadata.yaml files? | ||
| 4. How should the Explorer handle the 6 packages with no supported versions heading? |
There was a problem hiding this comment.
show blank, but let's make sure we followup and figure out why it's the case, whether they are special or if we just need to help update them
| reads, API is simpler for CI) | ||
| 2. What is the minimum viable schema for Phase 1 - which fields must be present before the Explorer | ||
| can show a JS package page? | ||
| 3. Is there appetite in the js-contrib community to standardize telemetry documentation format or |
There was a problem hiding this comment.
I have some things I think we should explore for this before we ask them
Co-authored-by: Jay DeLuca <jaydeluca4@gmail.com>
|
Thanks for the context @jaydeluca ! I'll start on the watcher using a git clone to walk the directory structure and also I'll keep the schema to what's machine-readable today as a first pass. I am definitely interested in exploring the integration test approach for telemetry collection and I would also love to see how it works in Java whenever you're ready to share that. I'll also follow up on the 6 packages with no supported versions to understand if they just need to be updated or if there's a reason they're missing. |
|
Thank you for your contribution @MeloveGupta! 🎉 We would like to hear from you about your experience contributing to OpenTelemetry by taking a few minutes to fill out this survey. |
2 participants
What
Adds the projects/ workspace for issue #9 with findings from the js-contrib repo audit.
Findings
What's machine-readable today without any README parsing:
package.json- name, version, description, source path, node engine.tav.yml- tested version ranges (31/47 packages).github/component_owners.yml- owners per package pathauto-instrumentations-nodedeps - bundle membershipTelemetry coverage across all 47 packages:
instrumentation-aws-sdkis the only package with a proper markdown table for span attributesKey structural difference from Java:
Files added
projects/9-javascript-instrumentation/_index.md- folder landing pageprojects/9-javascript-instrumentation/01-metadata-audit.md- full findings from the js-contrib repo analysisprojects/9-javascript-instrumentation/02-telemetry-coverage.md- telemetry coverage breakdown across all 47 packagesprojects/9-javascript-instrumentation/NEXT-STEPS.md- rolling roadmap and open questionsRelated
Related to #9