research(js): add JavaScript instrumentation metadata research docs #507
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,152 @@ | ||
| --- | ||
| title: "Metadata Audit - JavaScript Instrumentation" | ||
| issue: 9 | ||
| type: audit | ||
| phase: 1 | ||
| status: in-progress | ||
| last_updated: "2026-05-17" | ||
| --- | ||
|
|
||
| Analysis of the `opentelemetry-js-contrib` repository at HEAD `8fe14a9`(2026-05-08). All findings | ||
| are from actual file contents. | ||
|
|
||
| ## Repository overview | ||
|
|
||
| - 47 directories matching `instrumentation-*` under `packages/` | ||
| - 46 active `package.json` files | ||
| - 1 deprecated directory (`instrumentation-redis-4`) - README only, no `package.json` | ||
|
|
||
| ## What is machine-readable today | ||
|
|
||
| Every active `package.json` has: | ||
|
|
||
| | Field | Source | Notes | | ||
| | ---------------------- | ----------------------------------------- | -------------------------------- | | ||
| | `name` | `package.json` | npm package name | | ||
| | `version` | `package.json` | Independent per package | | ||
| | `description` | `package.json` | Consistently worded | | ||
| | `engines.node` | `package.json` | Structured Node.js version range | | ||
| | `repository.directory` | `package.json` | Present in 44/46 packages | | ||
| | `homepage` | `package.json` | Links to package subdirectory | | ||
| | `component_owners` | `.github/component_owners.yml` | Per package path, 46 entries | | ||
| | `bundle_membership` | `auto-instrumentations-node/package.json` | Recoverable from dep list | | ||
| | `package_version` | `.release-please-manifest.json` | Per package | | ||
|
|
||
| ## What exists but is inconsistent | ||
|
|
||
| ### Supported versions | ||
|
|
||
| - 41/47 READMEs have a `### Supported Versions` heading | ||
| - 6 packages have no supported versions heading: browser-navigation, document-load, long-task, | ||
| redis-4, user-interaction, web-exception | ||
| - `.tav.yml` exists for 31/47 packages with tested version ranges | ||
| - README and `.tav.yml` don't always agree - Express README says `>=4.0.0 <6` but `.tav.yml` tests | ||
| `>=4.16.2 <6` | ||
|
|
||
| ### Telemetry data | ||
|
|
||
| All 47 READMEs mention telemetry somewhere but only **8/47** have any structured span or attribute | ||
| section under a dedicated heading: | ||
|
|
||
| - `instrumentation-aws-sdk` | ||
| - `instrumentation-cassandra-driver` | ||
| - `instrumentation-dataloader` | ||
| - `instrumentation-hapi` | ||
| - `instrumentation-kafkajs` | ||
| - `instrumentation-nestjs-core` | ||
| - `instrumentation-pg` | ||
| - `instrumentation-web-exception` | ||
|
|
||
| The remaining 39 packages reference telemetry in prose only, no structured tables or lists that can | ||
| be parsed reliably. | ||
|
|
||
| #### Heading inconsistency | ||
|
|
||
| No standard heading exists across the 8 that do have structured data: | ||
|
|
||
| | Heading used | Count | | ||
| | -------------------------- | ----- | | ||
| | `## Span Attributes` | 1 | | ||
| | `## Emitted Spans` | 1 | | ||
| | `## Semantic Attributes` | 1 | | ||
| | `### Spans Emitted` | 1 | | ||
| | `### Spans created` | 1 | | ||
| | `### Span Types Created` | 1 | | ||
| | `### Attributes Collected` | 1 | | ||
| | `### Attributes collected` | 1 | | ||
|
|
||
| The best example is `instrumentation-aws-sdk` which has a proper markdown table with attribute | ||
| names, types, descriptions, and examples. Most others use bullet lists or prose. | ||
|
|
||
| ### Configuration options | ||
|
|
||
| - 29/47 READMEs have an Options/Configuration section | ||
| - Format varies - markdown tables, bullet lists, prose | ||
| - Types often reference TypeScript interfaces rather than primitives | ||
|
|
||
| ### Semantic conventions | ||
|
|
||
| - 41/47 READMEs mention semantic conventions | ||
| - Usually as a version string or a link - not structured data | ||
|
|
||
| ## What is missing entirely | ||
|
|
||
| - Stability level - not tracked in any structured field | ||
| - Log telemetry - some packages emit logs (e.g. browser-navigation) but there is no structured field | ||
| for this anywhere | ||
| - Unmaintained status - recorded as a YAML comment in `component_owners.yml`, not a field | ||
|
|
||
| ## Proposed registry schema | ||
|
|
||
| Based on what is machine-readable today, a Phase 1 registry entry would look like this: | ||
|
|
||
| ```yaml | ||
| name: instrumentation-express | ||
| npm_package: "@opentelemetry/instrumentation-express" | ||
| version: "0.66.0" | ||
| description: "OpenTelemetry instrumentation for `express` http web application framework" | ||
| source_path: packages/instrumentation-express | ||
| repository: open-telemetry/opentelemetry-js-contrib | ||
| node_engine: "^18.19.0 || >=20.6.0" | ||
| in_auto_instrumentations_node: true | ||
| component_owners: | ||
| - JamieDanielson | ||
| - pkanal | ||
| - raphael-theriault-swi | ||
| supported_versions: | ||
| - package: express | ||
| version_range: ">=4.0.0 <6" | ||
| source: README.md | ||
| tested_versions: | ||
| - package: express | ||
| range: ">=4.16.2 <6" | ||
| mode: latest-minors | ||
| source: .tav.yml | ||
| ``` | ||
|
|
||
| ## What requires upstream work | ||
|
|
||
| For full parity with the Java instrumentation schema, the following would need to be added upstream | ||
| in js-contrib: | ||
|
|
||
| 1. **Structured telemetry data** - spans, metrics, attributes per instrumentation. Only 8/47 | ||
| packages have any structured data today, and none use a consistent format. A standardized heading | ||
| convention or a `metadata.yaml` file per package would be needed. | ||
|
|
||
| 2. **Stability level** - currently undocumented in structured form. | ||
|
|
||
| 3. **Log telemetry** - the current Java schema has no `logs` field. JS packages that emit logs would | ||
| need a schema extension. | ||
|
|
||
| 4. **Configuration options** - 29/47 have some documentation but formats are inconsistent and types | ||
| reference TypeScript interfaces. | ||
|
|
||
| ## Versioning model | ||
|
|
||
| JS packages version independently, there is no single "js agent version" to key the registry off. | ||
| The registry layout should be per package: | ||
|
|
||
| ```text | ||
| ecosystem-registry/javascript/instrumentation-express/v0.66.0/instrumentation.yaml | ||
| ecosystem-registry/javascript/instrumentation-mongoose/v0.64.0.yaml | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| --- | ||
| title: "Telemetry Coverage - JavaScript Instrumentation READMEs" | ||
| issue: 9 | ||
| type: audit | ||
| phase: 1 | ||
| status: in-progress | ||
| last_updated: "2026-05-17" | ||
| --- | ||
|
|
||
| Detailed breakdown of how telemetry data is documented across the 47 instrumentation packages in | ||
| `opentelemetry-js-contrib`. | ||
|
|
||
| ## Summary | ||
|
|
||
| | Coverage level | Count | Packages | | ||
| | --------------------------------- | ----- | --------------------------------------------------------------------------- | | ||
| | Structured table (markdown) | 1 | aws-sdk | | ||
| | Structured headings, list format | 7 | cassandra-driver, dataloader, hapi, kafkajs, nestjs-core, pg, web-exception | | ||
| | Telemetry mentioned in prose only | 39 | All others | | ||
| | No telemetry documentation | 0 | - | | ||
|
|
||
| ## The best case - aws-sdk | ||
|
|
||
| `instrumentation-aws-sdk` has a `## Span Attributes` section with a proper markdown table: | ||
|
|
||
| | Attribute | Type | Description | Example | | ||
| | -------------- | ------ | --------------------------- | ---------------- | | ||
| | `rpc.system` | string | Always equals "aws-api" | | | ||
| | `rpc.method` | string | Name of the operation | `PutObject` | | ||
| | `rpc.service` | string | Name of the service | `S3`, `DynamoDB` | | ||
| | `cloud.region` | string | Region name for the request | `eu-west-1` | | ||
|
|
||
| This is the format that would be parseable. 1 out of 47 packages reaches this standard. | ||
|
|
||
| ## The typical case - mongoose | ||
|
|
||
| `instrumentation-mongoose` mentions telemetry under `## Semantic Conventions` with a link to the | ||
| semconv spec but no list of what attributes are actually emitted. A user cannot determine what spans | ||
| or attributes to expect without reading the source code. | ||
|
|
||
| ## The missing case - express | ||
|
|
||
| `instrumentation-express` has no dedicated telemetry section at all. The README documents | ||
| configuration options and caveats but says nothing about what spans, attributes, or metrics the | ||
| instrumentation produces. | ||
|
|
||
| ## Implication for the watcher | ||
|
|
||
| A Phase 1 watcher can be built today using only structured sources (package.json, .tav.yml, | ||
| component_owners.yml, auto-instrumentations deps). Telemetry data cannot be reliably included in | ||
| Phase 1 without either: | ||
|
|
||
| 1. README parsing with significant error handling for inconsistent formats (fragile) | ||
| 2. A standardized metadata file per package in js-contrib (correct long-term fix, requires upstream | ||
| coordination) | ||
|
|
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| title: "Roadmap - JavaScript Instrumentation Research" | ||
| issue: 9 | ||
| type: roadmap | ||
| phase: meta | ||
| status: in-progress | ||
| last_updated: "2026-05-17" | ||
| --- | ||
|
|
||
| ## Done | ||
|
|
||
| - [x] Cloned js-contrib repo and audited all 47 packages | ||
| - [x] Identified machine-readable fields available today | ||
| - [x] Produced 3 example registry entries (express, mongoose, aws-sdk) | ||
| - [x] Audited telemetry coverage across all READMEs | ||
| - [x] Documented heading inconsistencies across the 8 packages with structured telemetry data | ||
|
|
||
| ## In progress | ||
|
|
||
| - [ ] Deeper pass on the 8 packages with structured telemetry, can their data be parsed reliably | ||
| despite heading differences? | ||
| - [ ] Draft Phase 1 watcher architecture | ||
|
|
||
| ## Open questions | ||
|
|
||
| 1. Should the watcher use a sparse Git clone or GitHub API calls? (Git clone is faster for bulk | ||
|
Member
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 |
||
| reads, API is simpler for CI) | ||
| 2. What is the minimum viable schema for Phase 1 - which fields must be present before the Explorer | ||
|
Member
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 |
||
| can show a JS package page? | ||
| 3. Is there appetite in the js-contrib community to standardize telemetry documentation format or | ||
|
Member
There was a problem hiding this comment. I have some things I think we should explore for this before we ask them |
||
| add metadata.yaml files? | ||
| 4. How should the Explorer handle the 6 packages with no supported versions heading? | ||
|
Member
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 |
||
| 5. Should unmaintained packages (empty owner arrays) be included in the registry or excluded? | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| --- | ||
| title: "Research - JavaScript Instrumentation Metadata" | ||
| issue: 9 | ||
| type: index | ||
| phase: 1 | ||
| status: in-progress | ||
| last_updated: "2026-05-17" | ||
| --- | ||
|
|
||
| Research into how JavaScript instrumentation metadata can be collected and stored in the Ecosystem | ||
| Explorer registry. | ||
|
|
||
| ## What lives here | ||
|
|
||
| - `_index.md` - this file | ||
| - `NEXT-STEPS.md` - rolling roadmap and open questions | ||
| - `01-metadata-audit.md` - findings from the js-contrib repo analysis | ||
| - `02-telemetry-coverage.md` - findings on telemetry data in READMEs | ||
|
|
||
| ## Goal | ||
|
|
||
| Produce a proposal for how to obtain and store JavaScript instrumentation metadata, identifying what | ||
| can be automated today and what requires upstream work. | ||
|
|
||
| ## Related | ||
|
|
||
| - Issue: [#9](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/9) | ||
| - Upstream repo: | ||
| [opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍 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.