coder / coder/vscode-coder

telemetry: schema-first event registry (typed catalog + generated docs)

Offen
#999 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
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

Beitragsleitfaden öffnen

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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.