@provide-io/telemetry 0.2.2

package/src/slo.ts

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * SLO-oriented telemetry helpers (RED/USE baseline).
+ * Mirrors Python provide.telemetry.slo.
+ */
+
+import {
+  type CounterInstrument,
+  type GaugeInstrument,
+  type HistogramInstrument,
+  counter,
+  gauge,
+  histogram,
+} from './metrics';
+import { getConfig } from './config';
+
+const _counters = new Map<string, CounterInstrument>();
+const _histograms = new Map<string, HistogramInstrument>();
+const _gauges = new Map<string, GaugeInstrument>();
+
+function _lazyCounter(name: string, description: string): CounterInstrument {
+  let c = _counters.get(name);
+  if (!c) {
+    c = counter(name, { description });
+    _counters.set(name, c);
+  }
+  return c;
+}
+
+function _lazyHistogram(name: string, description: string, unit: string): HistogramInstrument {
+  let h = _histograms.get(name);
+  if (!h) {
+    h = histogram(name, { description, unit });
+    _histograms.set(name, h);
+  }
+  return h;
+}
+
+function _lazyGauge(name: string, description: string, unit: string): GaugeInstrument {
+  let g = _gauges.get(name);
+  if (!g) {
+    g = gauge(name, { description, unit });
+    _gauges.set(name, g);
+  }
+  return g;
+}
+
+export function recordRedMetrics(opts: {
+  route: string;
+  method: string;
+  statusCode: number;
+  durationMs: number;
+}): void {
+  if (!getConfig().sloEnableRedMetrics) return;
+  const attrs = {
+    route: opts.route,
+    method: opts.method,
+    status_code: String(opts.statusCode),
+  };
+  _lazyCounter('http.requests.total', 'Total HTTP requests').add(1, attrs);
+  if (opts.statusCode >= 500) {
+    // Stryker disable next-line StringLiteral: error counter description is not tested
+    _lazyCounter('http.errors.total', 'Total HTTP errors').add(1, attrs);
+  }
+  _lazyHistogram('http.request.duration_ms', 'HTTP request latency', 'ms').record(
+    opts.durationMs,
+    attrs,
+  );
+}
+
+export function recordUseMetrics(opts: {
+  resource: string;
+  utilization: number;
+  unit?: string;
+}): void {
+  if (!getConfig().sloEnableUseMetrics) return;
+  const g = _lazyGauge('resource.utilization', 'Resource utilization', opts.unit ?? '%');
+  g.set(opts.utilization, { resource: opts.resource });
+}
+
+export interface ErrorClassification {
+  errorType: 'server' | 'client' | 'timeout' | 'unknown';
+  errorCode: number;
+  errorName: string;
+  category: 'server_error' | 'client_error' | 'timeout' | 'unknown';
+  severity: 'critical' | 'warning' | 'info' | 'unknown';
+  // OTel-aligned keys for cross-language parity with Go/Python
+  'error.type': string;
+  'error.category': string;
+  'error.severity': string;
+  'http.status_code': string;
+}
+
+export function classifyError(excName: string, statusCode: number): ErrorClassification {
+  const isTimeout = statusCode === 0 || excName.toLowerCase().includes('timeout');
+
+  if (isTimeout) {
+    return {
+      errorType: 'timeout',
+      errorCode: statusCode,
+      errorName: excName,
+      category: 'timeout',
+      severity: 'info',
+      'error.type': excName,
+      'error.category': 'timeout',
+      'error.severity': 'info',
+      'http.status_code': String(statusCode),
+    };
+  }
+  if (statusCode >= 500) {
+    return {
+      errorType: 'server',
+      errorCode: statusCode,
+      errorName: excName,
+      category: 'server_error',
+      severity: 'critical',
+      'error.type': excName,
+      'error.category': 'server_error',
+      'error.severity': 'critical',
+      'http.status_code': String(statusCode),
+    };
+  }
+  if (statusCode >= 400) {
+    const sev = statusCode === 429 ? 'critical' : 'warning';
+    return {
+      errorType: 'client',
+      errorCode: statusCode,
+      errorName: excName,
+      category: 'client_error',
+      severity: sev as 'critical' | 'warning',
+      'error.type': excName,
+      'error.category': 'client_error',
+      'error.severity': sev,
+      'http.status_code': String(statusCode),
+    };
+  }
+  return {
+    errorType: 'unknown',
+    errorCode: statusCode,
+    errorName: excName,
+    category: 'unknown',
+    severity: 'unknown',
+    'error.type': excName,
+    'error.category': 'unknown',
+    'error.severity': 'unknown',
+    'http.status_code': String(statusCode),
+  };
+}
+
+export function _resetSloForTests(): void {
+  _counters.clear();
+  _histograms.clear();
+  _gauges.clear();
+}

package/src/testing.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Test utilities — reset all telemetry state between tests.
+ * Mirrors Python provide.telemetry.testing.
+ */
+
+import { _resetConfig } from './config';
+import { _resetContext } from './context';
+import { _resetHealthForTests } from './health';
+import { _resetBackpressureForTests } from './backpressure';
+import { _resetCardinalityForTests } from './cardinality';
+import { _resetSamplingForTests } from './sampling';
+import { _resetResilienceForTests } from './resilience';
+import { resetPiiRulesForTests } from './pii';
+import { _resetSloForTests } from './slo';
+import { _resetPropagationForTests } from './propagation';
+import { _resetRootLogger } from './logger';
+import { _resetOtelLogProviderForTests } from './otel-logs';
+import { _resetTraceContext } from './tracing';
+import { _resetRuntimeForTests } from './runtime';
+
+/** Reset all telemetry state (config, context, PII rules, health, queues, sampling, resilience, SLO). */
+export function resetTelemetryState(): void {
+  _resetConfig();
+  _resetContext();
+  _resetHealthForTests();
+  _resetBackpressureForTests();
+  _resetCardinalityForTests();
+  _resetSamplingForTests();
+  _resetResilienceForTests();
+  resetPiiRulesForTests();
+  _resetSloForTests();
+  _resetPropagationForTests();
+  _resetRootLogger();
+  _resetOtelLogProviderForTests();
+  _resetRuntimeForTests();
+}
+
+/** Clear manual trace context (traceId / spanId set via setTraceContext). */
+export function resetTraceContext(): void {
+  _resetTraceContext();
+}
+
+/** Vitest plugin for automatic per-test telemetry isolation. */
+export const telemetryTestPlugin = {
+  beforeEach(): void {
+    resetTelemetryState();
+    resetTraceContext();
+  },
+  afterEach(): void {
+    resetTelemetryState();
+    resetTraceContext();
+  },
+};

package/src/tracing.ts

@@ -0,0 +1,211 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Tracing helpers — mirrors Python provide.telemetry @trace decorator and tracer access.
+ *
+ * Uses @opentelemetry/api which provides no-op implementations when no SDK is registered.
+ * withTrace() / @trace work safely without any OTEL setup; they just don't export spans.
+ */
+
+import {
+  type Tracer,
+  type Span,
+  SpanStatusCode,
+  trace,
+  context as otelContext,
+} from '@opentelemetry/api';
+import { getActiveOtelContext } from './propagation';
+import { randomHex } from './hash';
+
+// Stryker disable next-line StringLiteral: tracer name is not observable without a real SDK
+const TRACER_NAME = '@provide-io/telemetry';
+
+// ── Manual trace context (injected without an active OTEL span) ───────────────
+let _manualTraceId: string | undefined;
+let _manualSpanId: string | undefined;
+
+/**
+ * Manually inject trace/span IDs (e.g. from an incoming request header).
+ * Returned by getTraceContext(); cleared by _resetTraceContext().
+ */
+export function setTraceContext(traceId: string, spanId: string): void {
+  _manualTraceId = traceId;
+  _manualSpanId = spanId;
+}
+
+/**
+ * Return the current trace context: manual injection first, then active OTEL span.
+ */
+export function getTraceContext(): { trace_id?: string; span_id?: string } {
+  // Stryker disable next-line ConditionalExpression,LogicalOperator: setTraceContext always sets both; partial state not reachable via public API
+  if (_manualTraceId !== undefined || _manualSpanId !== undefined) {
+    return {
+      // Stryker disable next-line ConditionalExpression: _manualTraceId is always defined here (both set together)
+      ...(_manualTraceId !== undefined && { trace_id: _manualTraceId }),
+      // Stryker disable next-line ConditionalExpression: _manualSpanId is always defined here (both set together)
+      ...(_manualSpanId !== undefined && { span_id: _manualSpanId }),
+    };
+  }
+  const ids = getActiveTraceIds();
+  return {
+    ...(ids.trace_id !== undefined && { trace_id: ids.trace_id }),
+    ...(ids.span_id !== undefined && { span_id: ids.span_id }),
+  };
+}
+
+/** Reset manually injected trace context (used in tests). */
+export function _resetTraceContext(): void {
+  _manualTraceId = undefined;
+  _manualSpanId = undefined;
+}
+
+/** Return the tracer for the telemetry library. Noop when no SDK is registered. */
+export function getTracer(): Tracer {
+  return trace.getTracer(TRACER_NAME);
+}
+
+/** Module-level lazy singleton tracer — resolves provider at call time. */
+export const tracer: Tracer = trace.getTracer(TRACER_NAME);
+
+/**
+ * Return trace_id and span_id from the currently active OTEL span.
+ * Returns an empty object when no span is active or OTEL is not configured.
+ */
+export function getActiveTraceIds(): { trace_id?: string; span_id?: string } {
+  const span = trace.getActiveSpan();
+  if (!span) return {};
+  const ctx = span.spanContext();
+  // OTEL no-op spans have all-zero IDs — treat as no active span.
+  if (ctx.traceId === '00000000000000000000000000000000') return {};
+  return { trace_id: ctx.traceId, span_id: ctx.spanId };
+}
+
+const NOOP_TRACE_ID = '00000000000000000000000000000000';
+
+/**
+ * Return true if the given span is a no-op (all-zero trace ID).
+ * Used to decide whether to inject synthetic random IDs.
+ */
+function _isNoopSpan(span: Span): boolean {
+  return span.spanContext().traceId === NOOP_TRACE_ID;
+}
+
+/**
+ * Execute fn with random synthetic trace/span IDs set as manual context,
+ * then restore the previous manual context when done.
+ * Handles both sync and async results.
+ */
+function _withSyntheticIds<T>(fn: () => T): T {
+  const prevTraceId = _manualTraceId;
+  const prevSpanId = _manualSpanId;
+  // Stryker disable next-line StringLiteral: random IDs are non-deterministic — exact value not observable in mutations
+  setTraceContext(randomHex(16), randomHex(8));
+  const result = fn();
+  if (result instanceof Promise) {
+    return result.then(
+      (value) => {
+        _manualTraceId = prevTraceId;
+        _manualSpanId = prevSpanId;
+        return value;
+      },
+      (err: unknown) => {
+        _manualTraceId = prevTraceId;
+        _manualSpanId = prevSpanId;
+        throw err;
+      },
+    ) as T;
+  }
+  _manualTraceId = prevTraceId;
+  _manualSpanId = prevSpanId;
+  return result;
+}
+
+/** Shared span handler for withTrace — records exceptions and sets ERROR status. */
+function _spanHandler<T>(fn: () => T, span: Span): T {
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => {
+          span.end();
+          return value;
+        },
+        (err: unknown) => {
+          span.recordException(err instanceof Error ? err : new Error(String(err)));
+          span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+          span.end();
+          throw err;
+        },
+      ) as T;
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.recordException(err instanceof Error ? err : new Error(String(err)));
+    span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+    span.end();
+    throw err;
+  }
+}
+
+/**
+ * Execute fn inside a new span named `name`.
+ * Works for both sync and async functions.
+ * Mirrors Python @trace decorator behaviour: records exceptions, sets ERROR status.
+ */
+export function withTrace<T>(name: string, fn: () => T): T {
+  const tracer = trace.getTracer(TRACER_NAME);
+
+  // If an OTel context was extracted from propagation headers, use it as parent.
+  try {
+    const activeCtx = getActiveOtelContext();
+    if (activeCtx) {
+      return otelContext.with(activeCtx as ReturnType<typeof otelContext.active>, () =>
+        tracer.startActiveSpan(name, (span: Span) => {
+          // Stryker disable next-line ConditionalExpression: noop detection is not observable without SDK — branch outcome equivalent under mutation
+          /* v8 ignore start: noop-span false branch + real-span return are unreachable without a registered OTel provider */
+          if (_isNoopSpan(span)) return _withSyntheticIds(() => _spanHandler(fn, span));
+          return _spanHandler(fn, span);
+          /* v8 ignore stop */
+        }),
+      );
+    }
+  } catch {
+    // Graceful degradation — fall through to default behaviour.
+  }
+
+  return tracer.startActiveSpan(name, (span: Span) => {
+    // Stryker disable next-line ConditionalExpression: noop detection is not observable without SDK — branch outcome equivalent under mutation
+    if (_isNoopSpan(span)) return _withSyntheticIds(() => _spanHandler(fn, span));
+    return _spanHandler(fn, span);
+  });
+}
+
+/**
+ * Method/function decorator that wraps the target in withTrace().
+ * Span name defaults to the decorated method name.
+ *
+ * Usage (requires experimentalDecorators: true):
+ *   class Foo {
+ *     @trace('my.operation')
+ *     doWork() { ... }
+ *   }
+ */
+// Stryker disable BlockStatement: outer and inner decorator fns returning undefined leave descriptors unchanged — equivalent
+export function traceDecorator(name?: string) {
+  return function (
+    _target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    // Stryker enable BlockStatement
+    // Stryker disable next-line LogicalOperator: span name not observable with no-op tracer
+    const spanName = name ?? String(propertyKey);
+    const original = descriptor.value as (...args: unknown[]) => unknown;
+    descriptor.value = function (this: unknown, ...args: unknown[]) {
+      return withTrace(spanName, () => original.apply(this, args));
+    };
+    return descriptor;
+  };
+}