OpenSpec Change: enterprise-opentelemetry

Change ID: enterprise-opentelemetry
Package: @suaveplan/opentelemetry
Category: universal
Target path: universal/platform/opentelemetry
Status: PROPOSED
Date: 2026-04-19
Reference spec: /mnt/s/web/suaveplan/enterprise/opentelemetry.md

Summary

Zero-dependency, spec-compliant implementation of the OpenTelemetry tracing + metrics data model. Suaveplan's own tracer, meter, context, propagation, and exporter primitives — used as the default tracer when no third-party OTel SDK is wired. Includes a SuaveplanError interceptor that auto-records errors as span events.

Current-state audit (genesis)

Package does not exist yet — fresh build. Genesis currently uses the upstream @opentelemetry/api directly; this package lands the vendor-neutral runtime substrate that makes @opentelemetry/api a no-op until an exporter is registered.

Dependencies

Workspace: @suaveplan/error, @suaveplan/types
External (via catalog): @opentelemetry/api → catalog:observability; zod → catalog:forms; tslib → catalog:build
Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

Core – context + propagation

Context, ContextManager, getSpanFromContext, setSpanInContext
TextMapCarrier, TextMapGetter, TextMapPropagator, TextMapSetter, defaultTextMapGetter, defaultTextMapSetter

Core – tracer + span

Tracer, TracerProvider, TracerProviderConfig, TracerProviderOptions, ITracer, ITracerProvider
Span, SpanConfig, WritableSpan

Core – meter

Meter, MeterProvider, Counter, Gauge, Histogram
ICounter, IGauge, IHistogram, IMeter, IMeterProvider

Propagation

Baggage: Baggage, BaggageEntry, W3CBaggagePropagator, getBaggageFromContext, parseBaggage, serializeBaggage, setBaggageInContext
W3C Trace Context: W3CTraceContextPropagator, getRemoteSpanContext, parseTraceparent, parseTraceState, serializeTraceparent, serializeTraceState

Exporters

ConsoleSpanExporter, ConsoleExporterOptions, InMemorySpanExporter

Error bridge

installSuaveplanErrorInterceptor, isSuaveplanErrorInterceptorInstalled, InstallSuaveplanErrorInterceptorOptions, UninstallSuaveplanErrorInterceptor

Constants / utils

BAGGAGE_HEADER, INVALID_SPAN_ID, INVALID_TRACE_ID, MAX_BAGGAGE_ENTRIES, MAX_SPAN_ATTRIBUTES, MAX_SPAN_EVENTS, MAX_SPAN_LINKS, SPAN_ID_HEX_LENGTH, TRACE_ID_HEX_LENGTH, TRACE_VERSION, TRACEPARENT_HEADER, TRACESTATE_HEADER
generateSpanId, generateTraceId, hrTimeMs, isValidSpanId, isValidTraceId

Types

Attributes, AttributeValue, ExportResult, ExportResultCode, HistogramDataPoint, HistogramOptions, InstrumentationScope, MetricDataPoint, MetricOptions, MetricValueType, ReadableSpan, Resource, SpanContext, SpanEvent, SpanExporter, SpanKind, SpanLink, SpanOptions, SpanStatus, SpanStatusCode, TraceFlags.

New genesis additions

Codes: OTEL.INVALID_TRACE_ID, OTEL.INVALID_SPAN_ID, OTEL.EXPORT_FAILED, OTEL.LIMIT_EXCEEDED.
Zod schemas for every constant-limit-bearing type.
Compatibility layer tests that verify @opentelemetry/api defers to the package's global tracer provider when set.
Property tests: parseTraceparent ∘ serializeTraceparent round-trip, valid sample-flag combinations preserved.

Impact

Adds one new package: universal/platform/opentelemetry
Adds one new spec capability: opentelemetry

3.6 KiB Raw Blame History Unescape Escape