2.4 KiB
Capability Spec: opentelemetry
Package: @suaveplan/opentelemetry
Version: 0.0.0 (genesis)
Status: ADDED
ADDED Requirements
OT-01 — Identifier generation
generateTraceId() MUST return a 32-character lowercase hex string (128 bits). generateSpanId() MUST return a 16-character lowercase hex string (64 bits). Both MUST be cryptographically random and MUST NOT produce the all-zero IDs defined in INVALID_TRACE_ID / INVALID_SPAN_ID.
OT-02 — W3C traceparent
serializeTraceparent({ version, traceId, spanId, flags }) MUST emit <version>-<traceId>-<spanId>-<flags> with TRACE_VERSION as version and lowercase hex flags. parseTraceparent(str) MUST round-trip cleanly; invalid input MUST throw OTEL.INVALID_TRACE_ID or OTEL.INVALID_SPAN_ID.
OT-03 — Baggage
W3CBaggagePropagator MUST inject a baggage: … header comma-separated list of key=value pairs. parseBaggage(header) MUST tolerate percent-encoding and strip entries beyond MAX_BAGGAGE_ENTRIES (8192 by spec).
OT-04 — Span limits
A span MUST enforce MAX_SPAN_ATTRIBUTES, MAX_SPAN_EVENTS, MAX_SPAN_LINKS. Exceeding any MUST emit OTEL.LIMIT_EXCEEDED (dropped attribute counter) and silently drop further entries.
OT-05 — Meter contract
Counter.add(value, attrs?), Histogram.record(value, attrs?), Gauge.set(value, attrs?) MUST accept numeric values; negative values on Counter MUST be rejected per spec.
OT-06 — Error bridge
installSuaveplanErrorInterceptor() MUST subscribe to the @suaveplan/error global interceptor and, for every error thrown inside an active span, add a span event { name: 'exception', attributes: { 'exception.type', 'exception.message', 'exception.stacktrace', 'exception.code' } } and set SpanStatus.ERROR.
OT-07 — Exporters
ConsoleSpanExporter.export(spans) MUST emit one line per span to the configured logger. InMemorySpanExporter.export(spans) MUST append spans to an array available via getFinishedSpans() for tests. Both MUST return ExportResult { code: ExportResultCode.SUCCESS } on success.
OT-08 — @opentelemetry/api compatibility
Importing the package MUST register its TracerProvider and MeterProvider as the globals through @opentelemetry/api when no other provider is registered. Consumers using trace.getTracer(…) from @opentelemetry/api MUST receive the Suaveplan tracer.