75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# 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`
|