From 28ad772dd121e91c7743d0ace914aa8c832de402 Mon Sep 17 00:00:00 2001 From: Melove Date: Mon, 18 May 2026 06:03:18 +0530 Subject: [PATCH 1/3] research(js): add JavaScript instrumentation metadata research docs --- .../01-metadata-audit.md | 139 ++++++++++++++++++ .../02-telemetry-coverage.md | 52 +++++++ .../NEXT-STEPS.md | 31 ++++ .../9-javascript-instrumentation/_index.md | 28 ++++ projects/_index.md | 1 + 5 files changed, 251 insertions(+) create mode 100644 projects/9-javascript-instrumentation/01-metadata-audit.md create mode 100644 projects/9-javascript-instrumentation/02-telemetry-coverage.md create mode 100644 projects/9-javascript-instrumentation/NEXT-STEPS.md create mode 100644 projects/9-javascript-instrumentation/_index.md diff --git a/projects/9-javascript-instrumentation/01-metadata-audit.md b/projects/9-javascript-instrumentation/01-metadata-audit.md new file mode 100644 index 00000000..f6aac779 --- /dev/null +++ b/projects/9-javascript-instrumentation/01-metadata-audit.md @@ -0,0 +1,139 @@ +--- +title: "Metadata Audit - JavaScript Instrumentation" +issue: 9 +type: audit +phase: 1 +status: in-progress +last_updated: "2026-05-17" +--- + +# Metadata Audit - JavaScript Instrumentation + +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: +``` +ecosystem-registry/javascript/instrumentation-express/v0.66.0/instrumentation.yaml +ecosystem-registry/javascript/instrumentation-mongoose/v0.64.0/instrumentation.yaml +``` diff --git a/projects/9-javascript-instrumentation/02-telemetry-coverage.md b/projects/9-javascript-instrumentation/02-telemetry-coverage.md new file mode 100644 index 00000000..7d120ad9 --- /dev/null +++ b/projects/9-javascript-instrumentation/02-telemetry-coverage.md @@ -0,0 +1,52 @@ +--- +title: "Telemetry Coverage - JavaScript Instrumentation READMEs" +issue: 9 +type: audit +phase: 1 +status: in-progress +last_updated: "2026-05-17" +--- + +# Telemetry Coverage - JavaScript Instrumentation READMEs + +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. diff --git a/projects/9-javascript-instrumentation/NEXT-STEPS.md b/projects/9-javascript-instrumentation/NEXT-STEPS.md new file mode 100644 index 00000000..0bb4bd6b --- /dev/null +++ b/projects/9-javascript-instrumentation/NEXT-STEPS.md @@ -0,0 +1,31 @@ +--- +title: "Roadmap - JavaScript Instrumentation Research" +issue: 9 +type: roadmap +phase: meta +status: in-progress +last_updated: "2026-05-17" +--- + +# Roadmap - JavaScript Instrumentation Research + +## 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 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 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? diff --git a/projects/9-javascript-instrumentation/_index.md b/projects/9-javascript-instrumentation/_index.md new file mode 100644 index 00000000..991835b8 --- /dev/null +++ b/projects/9-javascript-instrumentation/_index.md @@ -0,0 +1,28 @@ +--- +title: "Research - JavaScript Instrumentation Metadata" +issue: 9 +type: index +phase: 1 +status: in-progress +last_updated: "2026-05-17" +--- + +# Research - JavaScript Instrumentation Metadata + +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) diff --git a/projects/_index.md b/projects/_index.md index 159b38b1..a32dc8e3 100644 --- a/projects/_index.md +++ b/projects/_index.md @@ -30,6 +30,7 @@ projects/ | ------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- | | [`84-ui-ux-design/`](./84-ui-ux-design/) | [#84](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/84) | Explorer UI/UX redesign — visual alignment with opentelemetry.io, phased across five page areas. | planning | | [`154-genai-ecosystem/`](./154-genai-ecosystem/) | [#154](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/154) | Research GenAI ecosystem — survey of GenAI/LLM instrumentation libraries and semantic convention coverage across languages. | in-progress | +| [`9-javascript-instrumentation/`](./9-javascript-instrumentation/) | [#9](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/9) | Research JavaScript instrumentation metadata - survey of js-contrib packages, telemetry coverage, and proposed registry schema. | in-progress | --- From ee16281406be16f3295160af215f5b2142c53ca6 Mon Sep 17 00:00:00 2001 From: Melove Date: Mon, 18 May 2026 06:12:52 +0530 Subject: [PATCH 2/3] fix: apply markdown lint and formatting fixes --- .../01-metadata-audit.md | 85 +++++++++++-------- .../02-telemetry-coverage.md | 49 ++++++----- .../NEXT-STEPS.md | 14 +-- .../9-javascript-instrumentation/_index.md | 11 +-- projects/_index.md | 10 +-- 5 files changed, 96 insertions(+), 73 deletions(-) diff --git a/projects/9-javascript-instrumentation/01-metadata-audit.md b/projects/9-javascript-instrumentation/01-metadata-audit.md index f6aac779..dbfc8415 100644 --- a/projects/9-javascript-instrumentation/01-metadata-audit.md +++ b/projects/9-javascript-instrumentation/01-metadata-audit.md @@ -7,9 +7,8 @@ status: in-progress last_updated: "2026-05-17" --- -# Metadata Audit - JavaScript Instrumentation - -Analysis of the `opentelemetry-js-contrib` repository at HEAD `8fe14a9`(2026-05-08). All findings are from actual file contents. +Analysis of the `opentelemetry-js-contrib` repository at HEAD `8fe14a9`(2026-05-08). All findings +are from actual file contents. ## Repository overview @@ -21,30 +20,33 @@ Analysis of the `opentelemetry-js-contrib` repository at HEAD `8fe14a9`(2026-05- 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 | +| 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 +- 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` +- 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: +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` @@ -55,24 +57,26 @@ All 47 READMEs mention telemetry somewhere but only **8/47** have any structured - `instrumentation-pg` - `instrumentation-web-exception` -The remaining 39 packages reference telemetry in prose only, no structured tables or lists that can be parsed reliably. +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 | +| 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. +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 @@ -88,7 +92,8 @@ The best example is `instrumentation-aws-sdk` which has a proper markdown table ## 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 +- 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 @@ -121,19 +126,27 @@ tested_versions: ## What requires upstream work -For full parity with the Java instrumentation schema, the following would need to be added upstream in js-contrib: +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. +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. +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. +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: -``` + +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/instrumentation.yaml ``` diff --git a/projects/9-javascript-instrumentation/02-telemetry-coverage.md b/projects/9-javascript-instrumentation/02-telemetry-coverage.md index 7d120ad9..803dfce8 100644 --- a/projects/9-javascript-instrumentation/02-telemetry-coverage.md +++ b/projects/9-javascript-instrumentation/02-telemetry-coverage.md @@ -7,46 +7,53 @@ status: in-progress last_updated: "2026-05-17" --- -# Telemetry Coverage - JavaScript Instrumentation READMEs - -Detailed breakdown of how telemetry data is documented across the 47 instrumentation packages in `opentelemetry-js-contrib`. +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 | - | +| 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` | +| 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. +`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. +`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: +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) +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. +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. diff --git a/projects/9-javascript-instrumentation/NEXT-STEPS.md b/projects/9-javascript-instrumentation/NEXT-STEPS.md index 0bb4bd6b..2b3ec23d 100644 --- a/projects/9-javascript-instrumentation/NEXT-STEPS.md +++ b/projects/9-javascript-instrumentation/NEXT-STEPS.md @@ -7,8 +7,6 @@ status: in-progress last_updated: "2026-05-17" --- -# Roadmap - JavaScript Instrumentation Research - ## Done - [x] Cloned js-contrib repo and audited all 47 packages @@ -19,13 +17,17 @@ last_updated: "2026-05-17" ## In progress -- [ ] Deeper pass on the 8 packages with structured telemetry, can their data be parsed reliably despite heading differences? +- [ ] 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 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 add metadata.yaml files? +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 + 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? 5. Should unmaintained packages (empty owner arrays) be included in the registry or excluded? diff --git a/projects/9-javascript-instrumentation/_index.md b/projects/9-javascript-instrumentation/_index.md index 991835b8..2810d40b 100644 --- a/projects/9-javascript-instrumentation/_index.md +++ b/projects/9-javascript-instrumentation/_index.md @@ -7,9 +7,8 @@ status: in-progress last_updated: "2026-05-17" --- -# Research - JavaScript Instrumentation Metadata - -Research into how JavaScript instrumentation metadata can be collected and stored in the Ecosystem Explorer registry. +Research into how JavaScript instrumentation metadata can be collected and stored in the Ecosystem +Explorer registry. ## What lives here @@ -20,9 +19,11 @@ Research into how JavaScript instrumentation metadata can be collected and store ## Goal -Produce a proposal for how to obtain and store JavaScript instrumentation metadata, identifying what can be automated today and what requires upstream work. +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) +- Upstream repo: + [opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib) diff --git a/projects/_index.md b/projects/_index.md index a32dc8e3..d06a0c0e 100644 --- a/projects/_index.md +++ b/projects/_index.md @@ -26,11 +26,11 @@ projects/ ## Current initiatives -| Folder | Issue | Description | Status | -| ------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- | -| [`84-ui-ux-design/`](./84-ui-ux-design/) | [#84](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/84) | Explorer UI/UX redesign — visual alignment with opentelemetry.io, phased across five page areas. | planning | -| [`154-genai-ecosystem/`](./154-genai-ecosystem/) | [#154](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/154) | Research GenAI ecosystem — survey of GenAI/LLM instrumentation libraries and semantic convention coverage across languages. | in-progress | -| [`9-javascript-instrumentation/`](./9-javascript-instrumentation/) | [#9](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/9) | Research JavaScript instrumentation metadata - survey of js-contrib packages, telemetry coverage, and proposed registry schema. | in-progress | +| Folder | Issue | Description | Status | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| [`84-ui-ux-design/`](./84-ui-ux-design/) | [#84](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/84) | Explorer UI/UX redesign — visual alignment with opentelemetry.io, phased across five page areas. | planning | +| [`154-genai-ecosystem/`](./154-genai-ecosystem/) | [#154](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/154) | Research GenAI ecosystem — survey of GenAI/LLM instrumentation libraries and semantic convention coverage across languages. | in-progress | +| [`9-javascript-instrumentation/`](./9-javascript-instrumentation/) | [#9](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/9) | Research JavaScript instrumentation metadata - survey of js-contrib packages, telemetry coverage, and proposed registry schema. | in-progress | --- From 917470abd03d1fd05787d204dd1b65ffc055db86 Mon Sep 17 00:00:00 2001 From: Melove Gupta Date: Tue, 19 May 2026 16:24:40 +0530 Subject: [PATCH 3/3] Update projects/9-javascript-instrumentation/01-metadata-audit.md Co-authored-by: Jay DeLuca --- projects/9-javascript-instrumentation/01-metadata-audit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/9-javascript-instrumentation/01-metadata-audit.md b/projects/9-javascript-instrumentation/01-metadata-audit.md index dbfc8415..8ea262e8 100644 --- a/projects/9-javascript-instrumentation/01-metadata-audit.md +++ b/projects/9-javascript-instrumentation/01-metadata-audit.md @@ -148,5 +148,5 @@ 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/instrumentation.yaml +ecosystem-registry/javascript/instrumentation-mongoose/v0.64.0.yaml ```