42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
# 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.
|