# 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.