Skip to content

Commit 50fcba6

Browse files
MeloveGuptajaydeluca
MeloveGupta
and
jaydeluca
authored
research(js): add JavaScript instrumentation metadata research docs (#507)
Co-authored-by: Jay DeLuca <jaydeluca4@gmail.com>
1 parent c0502bf commit 50fcba6

5 files changed

Lines changed: 278 additions & 4 deletions

File tree

‎projects/9-javascript-instrumentation/01-metadata-audit.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: "Metadata Audit - JavaScript Instrumentation"
3+
issue: 9
4+
type: audit
5+
phase: 1
6+
status: in-progress
7+
last_updated: "2026-05-17"
8+
---
9+
10+
Analysis of the `opentelemetry-js-contrib` repository at HEAD `8fe14a9`(2026-05-08). All findings
11+
are from actual file contents.
12+
13+
## Repository overview
14+
15+
- 47 directories matching `instrumentation-*` under `packages/`
16+
- 46 active `package.json` files
17+
- 1 deprecated directory (`instrumentation-redis-4`) - README only, no `package.json`
18+
19+
## What is machine-readable today
20+
21+
Every active `package.json` has:
22+
23+
| Field | Source | Notes |
24+
| ---------------------- | ----------------------------------------- | -------------------------------- |
25+
| `name` | `package.json` | npm package name |
26+
| `version` | `package.json` | Independent per package |
27+
| `description` | `package.json` | Consistently worded |
28+
| `engines.node` | `package.json` | Structured Node.js version range |
29+
| `repository.directory` | `package.json` | Present in 44/46 packages |
30+
| `homepage` | `package.json` | Links to package subdirectory |
31+
| `component_owners` | `.github/component_owners.yml` | Per package path, 46 entries |
32+
| `bundle_membership` | `auto-instrumentations-node/package.json` | Recoverable from dep list |
33+
| `package_version` | `.release-please-manifest.json` | Per package |
34+
35+
## What exists but is inconsistent
36+
37+
### Supported versions
38+
39+
- 41/47 READMEs have a `### Supported Versions` heading
40+
- 6 packages have no supported versions heading: browser-navigation, document-load, long-task,
41+
redis-4, user-interaction, web-exception
42+
- `.tav.yml` exists for 31/47 packages with tested version ranges
43+
- README and `.tav.yml` don't always agree - Express README says `>=4.0.0 <6` but `.tav.yml` tests
44+
`>=4.16.2 <6`
45+
46+
### Telemetry data
47+
48+
All 47 READMEs mention telemetry somewhere but only **8/47** have any structured span or attribute
49+
section under a dedicated heading:
50+
51+
- `instrumentation-aws-sdk`
52+
- `instrumentation-cassandra-driver`
53+
- `instrumentation-dataloader`
54+
- `instrumentation-hapi`
55+
- `instrumentation-kafkajs`
56+
- `instrumentation-nestjs-core`
57+
- `instrumentation-pg`
58+
- `instrumentation-web-exception`
59+
60+
The remaining 39 packages reference telemetry in prose only, no structured tables or lists that can
61+
be parsed reliably.
62+
63+
#### Heading inconsistency
64+
65+
No standard heading exists across the 8 that do have structured data:
66+
67+
| Heading used | Count |
68+
| -------------------------- | ----- |
69+
| `## Span Attributes` | 1 |
70+
| `## Emitted Spans` | 1 |
71+
| `## Semantic Attributes` | 1 |
72+
| `### Spans Emitted` | 1 |
73+
| `### Spans created` | 1 |
74+
| `### Span Types Created` | 1 |
75+
| `### Attributes Collected` | 1 |
76+
| `### Attributes collected` | 1 |
77+
78+
The best example is `instrumentation-aws-sdk` which has a proper markdown table with attribute
79+
names, types, descriptions, and examples. Most others use bullet lists or prose.
80+
81+
### Configuration options
82+
83+
- 29/47 READMEs have an Options/Configuration section
84+
- Format varies - markdown tables, bullet lists, prose
85+
- Types often reference TypeScript interfaces rather than primitives
86+
87+
### Semantic conventions
88+
89+
- 41/47 READMEs mention semantic conventions
90+
- Usually as a version string or a link - not structured data
91+
92+
## What is missing entirely
93+
94+
- Stability level - not tracked in any structured field
95+
- Log telemetry - some packages emit logs (e.g. browser-navigation) but there is no structured field
96+
for this anywhere
97+
- Unmaintained status - recorded as a YAML comment in `component_owners.yml`, not a field
98+
99+
## Proposed registry schema
100+
101+
Based on what is machine-readable today, a Phase 1 registry entry would look like this:
102+
103+
```yaml
104+
name: instrumentation-express
105+
npm_package: "@opentelemetry/instrumentation-express"
106+
version: "0.66.0"
107+
description: "OpenTelemetry instrumentation for `express` http web application framework"
108+
source_path: packages/instrumentation-express
109+
repository: open-telemetry/opentelemetry-js-contrib
110+
node_engine: "^18.19.0 || >=20.6.0"
111+
in_auto_instrumentations_node: true
112+
component_owners:
113+
- JamieDanielson
114+
- pkanal
115+
- raphael-theriault-swi
116+
supported_versions:
117+
- package: express
118+
version_range: ">=4.0.0 <6"
119+
source: README.md
120+
tested_versions:
121+
- package: express
122+
range: ">=4.16.2 <6"
123+
mode: latest-minors
124+
source: .tav.yml
125+
```
126+
127+
## What requires upstream work
128+
129+
For full parity with the Java instrumentation schema, the following would need to be added upstream
130+
in js-contrib:
131+
132+
1. **Structured telemetry data** - spans, metrics, attributes per instrumentation. Only 8/47
133+
packages have any structured data today, and none use a consistent format. A standardized heading
134+
convention or a `metadata.yaml` file per package would be needed.
135+
136+
2. **Stability level** - currently undocumented in structured form.
137+
138+
3. **Log telemetry** - the current Java schema has no `logs` field. JS packages that emit logs would
139+
need a schema extension.
140+
141+
4. **Configuration options** - 29/47 have some documentation but formats are inconsistent and types
142+
reference TypeScript interfaces.
143+
144+
## Versioning model
145+
146+
JS packages version independently, there is no single "js agent version" to key the registry off.
147+
The registry layout should be per package:
148+
149+
```text
150+
ecosystem-registry/javascript/instrumentation-express/v0.66.0/instrumentation.yaml
151+
ecosystem-registry/javascript/instrumentation-mongoose/v0.64.0.yaml
152+
```

‎projects/9-javascript-instrumentation/02-telemetry-coverage.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Telemetry Coverage - JavaScript Instrumentation READMEs"
3+
issue: 9
4+
type: audit
5+
phase: 1
6+
status: in-progress
7+
last_updated: "2026-05-17"
8+
---
9+
10+
Detailed breakdown of how telemetry data is documented across the 47 instrumentation packages in
11+
`opentelemetry-js-contrib`.
12+
13+
## Summary
14+
15+
| Coverage level | Count | Packages |
16+
| --------------------------------- | ----- | --------------------------------------------------------------------------- |
17+
| Structured table (markdown) | 1 | aws-sdk |
18+
| Structured headings, list format | 7 | cassandra-driver, dataloader, hapi, kafkajs, nestjs-core, pg, web-exception |
19+
| Telemetry mentioned in prose only | 39 | All others |
20+
| No telemetry documentation | 0 | - |
21+
22+
## The best case - aws-sdk
23+
24+
`instrumentation-aws-sdk` has a `## Span Attributes` section with a proper markdown table:
25+
26+
| Attribute | Type | Description | Example |
27+
| -------------- | ------ | --------------------------- | ---------------- |
28+
| `rpc.system` | string | Always equals "aws-api" | |
29+
| `rpc.method` | string | Name of the operation | `PutObject` |
30+
| `rpc.service` | string | Name of the service | `S3`, `DynamoDB` |
31+
| `cloud.region` | string | Region name for the request | `eu-west-1` |
32+
33+
This is the format that would be parseable. 1 out of 47 packages reaches this standard.
34+
35+
## The typical case - mongoose
36+
37+
`instrumentation-mongoose` mentions telemetry under `## Semantic Conventions` with a link to the
38+
semconv spec but no list of what attributes are actually emitted. A user cannot determine what spans
39+
or attributes to expect without reading the source code.
40+
41+
## The missing case - express
42+
43+
`instrumentation-express` has no dedicated telemetry section at all. The README documents
44+
configuration options and caveats but says nothing about what spans, attributes, or metrics the
45+
instrumentation produces.
46+
47+
## Implication for the watcher
48+
49+
A Phase 1 watcher can be built today using only structured sources (package.json, .tav.yml,
50+
component_owners.yml, auto-instrumentations deps). Telemetry data cannot be reliably included in
51+
Phase 1 without either:
52+
53+
1. README parsing with significant error handling for inconsistent formats (fragile)
54+
2. A standardized metadata file per package in js-contrib (correct long-term fix, requires upstream
55+
coordination)
56+
57+
The long-term fix is contributing tooling back to js-contrib that generates READMEs from structured
58+
metadata files, solving the problem at the source rather than parsing inconsistent documentation
59+
downstream.

‎projects/9-javascript-instrumentation/NEXT-STEPS.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Roadmap - JavaScript Instrumentation Research"
3+
issue: 9
4+
type: roadmap
5+
phase: meta
6+
status: in-progress
7+
last_updated: "2026-05-17"
8+
---
9+
10+
## Done
11+
12+
- [x] Cloned js-contrib repo and audited all 47 packages
13+
- [x] Identified machine-readable fields available today
14+
- [x] Produced 3 example registry entries (express, mongoose, aws-sdk)
15+
- [x] Audited telemetry coverage across all READMEs
16+
- [x] Documented heading inconsistencies across the 8 packages with structured telemetry data
17+
18+
## In progress
19+
20+
- [ ] Deeper pass on the 8 packages with structured telemetry, can their data be parsed reliably
21+
despite heading differences?
22+
- [ ] Draft Phase 1 watcher architecture
23+
24+
## Open questions
25+
26+
1. Should the watcher use a sparse Git clone or GitHub API calls? (Git clone is faster for bulk
27+
reads, API is simpler for CI)
28+
2. What is the minimum viable schema for Phase 1 - which fields must be present before the Explorer
29+
can show a JS package page?
30+
3. Is there appetite in the js-contrib community to standardize telemetry documentation format or
31+
add metadata.yaml files?
32+
4. How should the Explorer handle the 6 packages with no supported versions heading?
33+
5. Should unmaintained packages (empty owner arrays) be included in the registry or excluded?

‎projects/9-javascript-instrumentation/_index.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "Research - JavaScript Instrumentation Metadata"
3+
issue: 9
4+
type: index
5+
phase: 1
6+
status: in-progress
7+
last_updated: "2026-05-17"
8+
---
9+
10+
Research into how JavaScript instrumentation metadata can be collected and stored in the Ecosystem
11+
Explorer registry.
12+
13+
## What lives here
14+
15+
- `_index.md` - this file
16+
- `NEXT-STEPS.md` - rolling roadmap and open questions
17+
- `01-metadata-audit.md` - findings from the js-contrib repo analysis
18+
- `02-telemetry-coverage.md` - findings on telemetry data in READMEs
19+
20+
## Goal
21+
22+
Produce a proposal for how to obtain and store JavaScript instrumentation metadata, identifying what
23+
can be automated today and what requires upstream work.
24+
25+
## Related
26+
27+
- Issue: [#9](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/9)
28+
- Upstream repo:
29+
[opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib)

‎projects/_index.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,11 @@ projects/
2626

2727
## Current initiatives
2828

29-
| Folder | Issue | Description | Status |
30-
| ------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- |
31-
| [`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 |
32-
| [`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 |
29+
| Folder | Issue | Description | Status |
30+
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- |
31+
| [`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 |
32+
| [`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 |
33+
| [`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 |
3334

3435
---
3536

0 commit comments

Comments
 (0)