Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#999 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
32/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
typescript
Lĩnh vực
observability-sre

Hướng nghiên cứu

Bắt đầu bằng cách đọc src/instrumentation/CONVENTIONS.md, các tệp theo từng domain bên dưới src/instrumentation/* và src/instrumentation/EVENTS.md. Theo dõi TelemetryService.trace/log/logError, Span và các bài kiểm thử của chúng để hiểu cách định kiểu hiện tại của event và property. Công việc hoàn tất khi thiết kế registry được chọn đã được triển khai, instrumentation và các bài kiểm thử đã được cập nhật, và EVENTS.md được tạo đã vượt qua bước kiểm tra tính cập nhật của CI.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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<E>) 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<E> 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.
Ngôn ngữ chính
TypeScript
Star
131
Fork
48
Merge trung bình
2 ngày 56 phút
Pull request đã merge (30 ngày)
12

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của coder/vscode-coder

Tất cả issue của coder/vscode-coder

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.