telemetry: schema-first event registry (typed catalog + generated docs)
- Vorherrschende Sprache
- TypeScript
- Sterne
- 130
- Forks
- 48
- Ø Merge
- 3 T. 3 Std.
- Gemergte PRs (30 T.)
- 15
Beschreibung
## Problem
Telemetry events, properties, and value unions are declared per-domain in `src/instrumentation/*` and documented by hand in `src/instrumentation/EVENTS.md`. Nothing structurally prevents:
- emitting an event name that isn't cataloged anywhere,
- adding/renaming a property without updating the docs,
- drifting from the conventions in `src/instrumentation/CONVENTIONS.md` (a recent audit found camelCase keys, kebab-case enum values, and caller-set `result` that review missed).
## Proposal
Adopt a schema-first registry as the single source of truth for the telemetry surface, the way OTel itself defines semantic conventions in a registry and generates code + docs from it (Weaver).
TS-native sketch:
- A central `TelemetryEventMap` interface declaring every event with its properties and measurements (value unions spelled out).
- `TelemetryService.trace`/`log`/`logError` constrained to `keyof TelemetryEventMap`; `Span` becomes generic (`Span`) so `setProperty`/`setMeasurement` keys and values are type-checked per event. An undeclared event or attribute key becomes a compile error.
- `EVENTS.md` generated from the registry (script walking the interface + JSDoc), with a CI `--check` mode so the doc can never go stale.
## Known costs / open questions
- Every instrumentation class and its tests are touched by the `Span` generic.
- Phase names compose at runtime (`parent.child`), so child phases need registry entries or looser typing.
- The registry partially duplicates per-domain unions the instrumentation classes already export; decide whether the registry imports those types or replaces them.
## Cheaper interim guards (could land independently)
- Type the event-name parameter of `TelemetryService.trace`/`log` as a union of registered names (names are already top-level string literals; near-zero churn).
- ESLint restriction banning raw `telemetry.trace(`/`.log(` outside `src/instrumentation` (the layering rule from CONVENTIONS.md).
- Golden event catalog aggregated from the test suite's sinks, checked like the existing OTLP goldens.
Beitragsleitfaden
Rechercherichtung
Beginne mit dem Lesen von src/instrumentation/CONVENTIONS.md, den domänenspezifischen Dateien unter src/instrumentation/* und src/instrumentation/EVENTS.md. Verfolge TelemetryService.trace/log/logError, Span und ihre Tests, um die aktuelle Typisierung von Ereignissen und Eigenschaften zu verstehen. Die Arbeit ist abgeschlossen, wenn das ausgewählte Registry-Design implementiert, die Instrumentierung und die Tests aktualisiert wurden und die generierte EVENTS.md ihre CI-Aktualitätsprüfung besteht.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- typescript
- Bereich
- observability-sre
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Ruhig
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 32/100