@contractspec/lib.observability 1.57.0 → 1.58.0

package/dist/intent/aggregator.d.ts

@@ -0,0 +1,57 @@
+export interface TelemetrySample {
+    operation: {
+        name: string;
+        version: string;
+    };
+    durationMs: number;
+    success: boolean;
+    timestamp: Date;
+    errorCode?: string;
+    tenantId?: string;
+    traceId?: string;
+    actorId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AggregatedOperationMetrics {
+    operation: {
+        name: string;
+        version: string;
+    };
+    totalCalls: number;
+    successRate: number;
+    errorRate: number;
+    averageLatencyMs: number;
+    p95LatencyMs: number;
+    p99LatencyMs: number;
+    maxLatencyMs: number;
+    windowStart: Date;
+    windowEnd: Date;
+    topErrors: Record<string, number>;
+}
+export interface OperationSequence {
+    steps: string[];
+    tenantId?: string;
+    count: number;
+}
+export interface IntentAggregatorSnapshot {
+    metrics: AggregatedOperationMetrics[];
+    sequences: OperationSequence[];
+    sampleCount: number;
+    windowStart?: Date;
+    windowEnd?: Date;
+}
+export interface IntentAggregatorOptions {
+    windowMs?: number;
+    sequenceSampleSize?: number;
+}
+export declare class IntentAggregator {
+    private readonly windowMs;
+    private readonly sequenceSampleSize;
+    private readonly samples;
+    constructor(options?: IntentAggregatorOptions);
+    add(sample: TelemetrySample): void;
+    flush(now?: Date): IntentAggregatorSnapshot;
+    private aggregateMetrics;
+    private buildSequences;
+}
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/intent/aggregator.js

@@ -0,0 +1,110 @@
+// @bun
+// src/intent/aggregator.ts
+var DEFAULT_WINDOW_MS = 15 * 60 * 1000;
+
+class IntentAggregator {
+  windowMs;
+  sequenceSampleSize;
+  samples = [];
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    this.sequenceSampleSize = options.sequenceSampleSize ?? 1000;
+  }
+  add(sample) {
+    this.samples.push(sample);
+  }
+  flush(now = new Date) {
+    const minTimestamp = now.getTime() - this.windowMs;
+    const windowSamples = this.samples.filter((sample) => sample.timestamp.getTime() >= minTimestamp);
+    this.samples.length = 0;
+    const metrics = this.aggregateMetrics(windowSamples);
+    const sequences = this.buildSequences(windowSamples);
+    const timestamps = windowSamples.map((sample) => sample.timestamp.getTime());
+    return {
+      metrics,
+      sequences,
+      sampleCount: windowSamples.length,
+      windowStart: timestamps.length ? new Date(Math.min(...timestamps)) : undefined,
+      windowEnd: timestamps.length ? new Date(Math.max(...timestamps)) : undefined
+    };
+  }
+  aggregateMetrics(samples) {
+    if (!samples.length)
+      return [];
+    const groups = new Map;
+    for (const sample of samples) {
+      const key = `${sample.operation.name}.v${sample.operation.version}`;
+      const arr = groups.get(key) ?? [];
+      arr.push(sample);
+      groups.set(key, arr);
+    }
+    return [...groups.values()].map((group) => {
+      const first = group[0];
+      if (!first)
+        throw new Error("Empty group in aggregation");
+      const durations = group.map((s) => s.durationMs).sort((a, b) => a - b);
+      const errors = group.filter((s) => !s.success);
+      const totalCalls = group.length;
+      const topErrors = errors.reduce((acc, sample) => {
+        if (!sample.errorCode)
+          return acc;
+        acc[sample.errorCode] = (acc[sample.errorCode] ?? 0) + 1;
+        return acc;
+      }, {});
+      const timestamps = group.map((s) => s.timestamp.getTime());
+      return {
+        operation: first.operation,
+        totalCalls,
+        successRate: (totalCalls - errors.length) / totalCalls,
+        errorRate: errors.length / totalCalls,
+        averageLatencyMs: durations.reduce((sum, value) => sum + value, 0) / totalCalls,
+        p95LatencyMs: percentile(durations, 0.95),
+        p99LatencyMs: percentile(durations, 0.99),
+        maxLatencyMs: Math.max(...durations),
+        windowStart: new Date(Math.min(...timestamps)),
+        windowEnd: new Date(Math.max(...timestamps)),
+        topErrors
+      };
+    });
+  }
+  buildSequences(samples) {
+    const byTrace = new Map;
+    for (const sample of samples.slice(-this.sequenceSampleSize)) {
+      if (!sample.traceId)
+        continue;
+      const arr = byTrace.get(sample.traceId) ?? [];
+      arr.push(sample);
+      byTrace.set(sample.traceId, arr);
+    }
+    const sequences = {};
+    for (const events of byTrace.values()) {
+      const ordered = events.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+      const steps = ordered.map((event) => event.operation.name);
+      if (steps.length < 2)
+        continue;
+      const key = `${steps.join(">")}@${ordered[0]?.tenantId ?? "global"}`;
+      const existing = sequences[key];
+      if (existing) {
+        existing.count += 1;
+      } else {
+        sequences[key] = {
+          steps,
+          tenantId: ordered[0]?.tenantId,
+          count: 1
+        };
+      }
+    }
+    return Object.values(sequences).sort((a, b) => b.count - a.count);
+  }
+}
+function percentile(values, ratio) {
+  if (!values.length)
+    return 0;
+  if (values.length === 1)
+    return values[0] ?? 0;
+  const index = Math.min(values.length - 1, Math.floor(ratio * values.length));
+  return values[index] ?? 0;
+}
+export {
+  IntentAggregator
+};

package/dist/intent/detector.d.ts

@@ -0,0 +1,28 @@
+import type { AggregatedOperationMetrics, OperationSequence } from './aggregator';
+export type IntentSignalType = 'latency-regression' | 'error-spike' | 'throughput-drop' | 'missing-workflow-step';
+export interface IntentSignal {
+    id: string;
+    type: IntentSignalType;
+    operation?: AggregatedOperationMetrics['operation'];
+    confidence: number;
+    description: string;
+    metadata?: Record<string, unknown>;
+    evidence: {
+        type: 'metric' | 'sequence' | 'anomaly';
+        description: string;
+        data?: Record<string, unknown>;
+    }[];
+}
+export interface IntentDetectorOptions {
+    errorRateThreshold?: number;
+    latencyP99ThresholdMs?: number;
+    throughputDropThreshold?: number;
+    minSequenceLength?: number;
+}
+export declare class IntentDetector {
+    private readonly options;
+    constructor(options?: IntentDetectorOptions);
+    detectFromMetrics(current: AggregatedOperationMetrics[], previous?: AggregatedOperationMetrics[]): IntentSignal[];
+    detectSequentialIntents(sequences: OperationSequence[]): IntentSignal[];
+}
+//# sourceMappingURL=detector.d.ts.map

package/dist/intent/detector.js

@@ -0,0 +1,133 @@
+// @bun
+// src/intent/detector.ts
+import { randomUUID } from "crypto";
+var DEFAULTS = {
+  errorRateThreshold: 0.05,
+  latencyP99ThresholdMs: 750,
+  throughputDropThreshold: 0.3,
+  minSequenceLength: 3
+};
+
+class IntentDetector {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      errorRateThreshold: options.errorRateThreshold ?? DEFAULTS.errorRateThreshold,
+      latencyP99ThresholdMs: options.latencyP99ThresholdMs ?? DEFAULTS.latencyP99ThresholdMs,
+      throughputDropThreshold: options.throughputDropThreshold ?? DEFAULTS.throughputDropThreshold,
+      minSequenceLength: options.minSequenceLength ?? DEFAULTS.minSequenceLength
+    };
+  }
+  detectFromMetrics(current, previous) {
+    const signals = [];
+    const baseline = new Map((previous ?? []).map((metric) => [
+      `${metric.operation.name}.v${metric.operation.version}`,
+      metric
+    ]));
+    for (const metric of current) {
+      if (metric.errorRate >= this.options.errorRateThreshold) {
+        signals.push({
+          id: randomUUID(),
+          type: "error-spike",
+          operation: metric.operation,
+          confidence: Math.min(1, metric.errorRate / this.options.errorRateThreshold),
+          description: `Error rate ${metric.errorRate.toFixed(2)} exceeded threshold`,
+          metadata: {
+            errorRate: metric.errorRate,
+            topErrors: metric.topErrors
+          },
+          evidence: [
+            {
+              type: "metric",
+              description: "error-rate",
+              data: {
+                errorRate: metric.errorRate,
+                threshold: this.options.errorRateThreshold
+              }
+            }
+          ]
+        });
+        continue;
+      }
+      if (metric.p99LatencyMs >= this.options.latencyP99ThresholdMs) {
+        signals.push({
+          id: randomUUID(),
+          type: "latency-regression",
+          operation: metric.operation,
+          confidence: Math.min(1, metric.p99LatencyMs / this.options.latencyP99ThresholdMs),
+          description: `P99 latency ${metric.p99LatencyMs}ms exceeded threshold`,
+          metadata: { p99LatencyMs: metric.p99LatencyMs },
+          evidence: [
+            {
+              type: "metric",
+              description: "p99-latency",
+              data: {
+                p99LatencyMs: metric.p99LatencyMs,
+                threshold: this.options.latencyP99ThresholdMs
+              }
+            }
+          ]
+        });
+        continue;
+      }
+      const base = baseline.get(`${metric.operation.name}.v${metric.operation.version}`);
+      if (base) {
+        const drop = (base.totalCalls - metric.totalCalls) / Math.max(base.totalCalls, 1);
+        if (drop >= this.options.throughputDropThreshold) {
+          signals.push({
+            id: randomUUID(),
+            type: "throughput-drop",
+            operation: metric.operation,
+            confidence: Math.min(1, drop / this.options.throughputDropThreshold),
+            description: `Throughput dropped ${(drop * 100).toFixed(1)}% vs baseline`,
+            metadata: {
+              baselineCalls: base.totalCalls,
+              currentCalls: metric.totalCalls
+            },
+            evidence: [
+              {
+                type: "metric",
+                description: "throughput-drop",
+                data: {
+                  baselineCalls: base.totalCalls,
+                  currentCalls: metric.totalCalls
+                }
+              }
+            ]
+          });
+        }
+      }
+    }
+    return signals;
+  }
+  detectSequentialIntents(sequences) {
+    const signals = [];
+    for (const sequence of sequences) {
+      if (sequence.steps.length < this.options.minSequenceLength)
+        continue;
+      const description = sequence.steps.join(" \u2192 ");
+      signals.push({
+        id: randomUUID(),
+        type: "missing-workflow-step",
+        confidence: 0.6,
+        description: `Repeated workflow detected: ${description}`,
+        metadata: {
+          steps: sequence.steps,
+          tenantId: sequence.tenantId,
+          occurrences: sequence.count
+        },
+        evidence: [
+          {
+            type: "sequence",
+            description: "sequential-calls",
+            data: { steps: sequence.steps, count: sequence.count }
+          }
+        ]
+      });
+    }
+    return signals;
+  }
+}
+export {
+  IntentDetector
+};

package/dist/logging/index.d.ts

@@ -0,0 +1,17 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    [key: string]: unknown;
+}
+export declare class Logger {
+    private readonly serviceName;
+    constructor(serviceName: string);
+    private log;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export declare const logger: Logger;
+//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.js

@@ -0,0 +1,42 @@
+// @bun
+// src/logging/index.ts
+import { trace, context } from "@opentelemetry/api";
+
+class Logger {
+  serviceName;
+  constructor(serviceName) {
+    this.serviceName = serviceName;
+  }
+  log(level, message, meta = {}) {
+    const span = trace.getSpan(context.active());
+    const traceId = span?.spanContext().traceId;
+    const spanId = span?.spanContext().spanId;
+    const entry = {
+      timestamp: new Date().toISOString(),
+      service: this.serviceName,
+      level,
+      message,
+      traceId,
+      spanId,
+      ...meta
+    };
+    console.log(JSON.stringify(entry));
+  }
+  debug(message, meta) {
+    this.log("debug", message, meta);
+  }
+  info(message, meta) {
+    this.log("info", message, meta);
+  }
+  warn(message, meta) {
+    this.log("warn", message, meta);
+  }
+  error(message, meta) {
+    this.log("error", message, meta);
+  }
+}
+var logger = new Logger(process.env.OTEL_SERVICE_NAME || "unknown-service");
+export {
+  logger,
+  Logger
+};

package/dist/metrics/index.d.ts

@@ -0,0 +1,12 @@
+import { type Meter, type Counter, type Histogram, type UpDownCounter } from '@opentelemetry/api';
+export declare function getMeter(name?: string): Meter;
+export declare function createCounter(name: string, description?: string, meterName?: string): Counter;
+export declare function createUpDownCounter(name: string, description?: string, meterName?: string): UpDownCounter;
+export declare function createHistogram(name: string, description?: string, meterName?: string): Histogram;
+export declare const standardMetrics: {
+    httpRequests: Counter<import("@opentelemetry/api").Attributes>;
+    httpDuration: Histogram<import("@opentelemetry/api").Attributes>;
+    operationErrors: Counter<import("@opentelemetry/api").Attributes>;
+    workflowDuration: Histogram<import("@opentelemetry/api").Attributes>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.js

@@ -0,0 +1,31 @@
+// @bun
+// src/metrics/index.ts
+import {
+  metrics
+} from "@opentelemetry/api";
+var DEFAULT_METER_NAME = "@contractspec/lib.observability";
+function getMeter(name = DEFAULT_METER_NAME) {
+  return metrics.getMeter(name);
+}
+function createCounter(name, description, meterName) {
+  return getMeter(meterName).createCounter(name, { description });
+}
+function createUpDownCounter(name, description, meterName) {
+  return getMeter(meterName).createUpDownCounter(name, { description });
+}
+function createHistogram(name, description, meterName) {
+  return getMeter(meterName).createHistogram(name, { description });
+}
+var standardMetrics = {
+  httpRequests: createCounter("http_requests_total", "Total HTTP requests"),
+  httpDuration: createHistogram("http_request_duration_seconds", "HTTP request duration"),
+  operationErrors: createCounter("operation_errors_total", "Total operation errors"),
+  workflowDuration: createHistogram("workflow_duration_seconds", "Workflow execution duration")
+};
+export {
+  standardMetrics,
+  getMeter,
+  createUpDownCounter,
+  createHistogram,
+  createCounter
+};

package/dist/node/anomaly/alert-manager.js

@@ -0,0 +1,23 @@
+// src/anomaly/alert-manager.ts
+class AlertManager {
+  options;
+  cooldownMs;
+  lastAlert = new Map;
+  constructor(options) {
+    this.options = options;
+    this.cooldownMs = options.cooldownMs ?? 60000;
+  }
+  async notify(signal, analysis) {
+    const key = `${signal.type}:${analysis.culprit?.id ?? "none"}`;
+    const now = Date.now();
+    const last = this.lastAlert.get(key) ?? 0;
+    if (now - last < this.cooldownMs) {
+      return;
+    }
+    await this.options.transport({ signal, analysis });
+    this.lastAlert.set(key, now);
+  }
+}
+export {
+  AlertManager
+};

package/dist/node/anomaly/anomaly-detector.js

@@ -0,0 +1,101 @@
+// src/anomaly/baseline-calculator.ts
+class BaselineCalculator {
+  alpha;
+  snapshot = {
+    latencyP99: 0,
+    latencyP95: 0,
+    errorRate: 0,
+    throughput: 0,
+    sampleCount: 0
+  };
+  constructor(alpha = 0.2) {
+    this.alpha = alpha;
+  }
+  update(point) {
+    const { sampleCount } = this.snapshot;
+    const nextCount = sampleCount + 1;
+    const weight = sampleCount === 0 ? 1 : this.alpha;
+    this.snapshot = {
+      latencyP99: this.mix(this.snapshot.latencyP99, point.latencyP99, weight),
+      latencyP95: this.mix(this.snapshot.latencyP95, point.latencyP95, weight),
+      errorRate: this.mix(this.snapshot.errorRate, point.errorRate, weight),
+      throughput: this.mix(this.snapshot.throughput, point.throughput, weight),
+      sampleCount: nextCount
+    };
+    return this.snapshot;
+  }
+  getSnapshot() {
+    return this.snapshot;
+  }
+  mix(current, next, weight) {
+    if (this.snapshot.sampleCount === 0) {
+      return next;
+    }
+    return current * (1 - weight) + next * weight;
+  }
+}
+
+// src/anomaly/anomaly-detector.ts
+class AnomalyDetector {
+  baseline;
+  thresholds = {
+    errorRateDelta: 0.5,
+    latencyDelta: 0.35,
+    throughputDrop: 0.4,
+    minSamples: 10
+  };
+  constructor(options = {}) {
+    this.baseline = new BaselineCalculator;
+    this.thresholds = { ...this.thresholds, ...options };
+  }
+  evaluate(point) {
+    const baselineSnapshot = this.baseline.update(point);
+    if (baselineSnapshot.sampleCount < this.thresholds.minSamples) {
+      return [];
+    }
+    const signals = [];
+    const errorDelta = this.relativeDelta(point.errorRate, baselineSnapshot.errorRate);
+    if (errorDelta > this.thresholds.errorRateDelta) {
+      signals.push({
+        type: "error_rate_spike",
+        delta: errorDelta,
+        point,
+        baseline: baselineSnapshot
+      });
+    }
+    const latencyDelta = this.relativeDelta(point.latencyP99, baselineSnapshot.latencyP99);
+    if (latencyDelta > this.thresholds.latencyDelta) {
+      signals.push({
+        type: "latency_regression",
+        delta: latencyDelta,
+        point,
+        baseline: baselineSnapshot
+      });
+    }
+    const throughputDelta = this.relativeDrop(point.throughput, baselineSnapshot.throughput);
+    if (throughputDelta > this.thresholds.throughputDrop) {
+      signals.push({
+        type: "throughput_drop",
+        delta: throughputDelta,
+        point,
+        baseline: baselineSnapshot
+      });
+    }
+    return signals;
+  }
+  relativeDelta(value, baseline) {
+    if (baseline === 0) {
+      return 0;
+    }
+    return (value - baseline) / baseline;
+  }
+  relativeDrop(value, baseline) {
+    if (baseline === 0) {
+      return 0;
+    }
+    return (baseline - value) / baseline;
+  }
+}
+export {
+  AnomalyDetector
+};

package/dist/node/anomaly/baseline-calculator.js

@@ -0,0 +1,39 @@
+// src/anomaly/baseline-calculator.ts
+class BaselineCalculator {
+  alpha;
+  snapshot = {
+    latencyP99: 0,
+    latencyP95: 0,
+    errorRate: 0,
+    throughput: 0,
+    sampleCount: 0
+  };
+  constructor(alpha = 0.2) {
+    this.alpha = alpha;
+  }
+  update(point) {
+    const { sampleCount } = this.snapshot;
+    const nextCount = sampleCount + 1;
+    const weight = sampleCount === 0 ? 1 : this.alpha;
+    this.snapshot = {
+      latencyP99: this.mix(this.snapshot.latencyP99, point.latencyP99, weight),
+      latencyP95: this.mix(this.snapshot.latencyP95, point.latencyP95, weight),
+      errorRate: this.mix(this.snapshot.errorRate, point.errorRate, weight),
+      throughput: this.mix(this.snapshot.throughput, point.throughput, weight),
+      sampleCount: nextCount
+    };
+    return this.snapshot;
+  }
+  getSnapshot() {
+    return this.snapshot;
+  }
+  mix(current, next, weight) {
+    if (this.snapshot.sampleCount === 0) {
+      return next;
+    }
+    return current * (1 - weight) + next * weight;
+  }
+}
+export {
+  BaselineCalculator
+};

package/dist/node/anomaly/root-cause-analyzer.js

@@ -0,0 +1,31 @@
+// src/anomaly/root-cause-analyzer.ts
+class RootCauseAnalyzer {
+  lookbackMs;
+  constructor(lookbackMs = 15 * 60 * 1000) {
+    this.lookbackMs = lookbackMs;
+  }
+  analyze(signal, deployments) {
+    const windowStart = new Date(signal.point.timestamp.getTime() - this.lookbackMs);
+    const candidates = deployments.filter((deployment) => deployment.deployedAt >= windowStart).sort((a, b) => b.deployedAt.getTime() - a.deployedAt.getTime());
+    const notes = [];
+    let culprit;
+    if (candidates.length > 0) {
+      culprit = candidates[0];
+      if (culprit) {
+        notes.push(`Closest deployment ${culprit.id} (${culprit.operation}) at ${culprit.deployedAt.toISOString()}`);
+      }
+    } else {
+      notes.push("No deployments found within lookback window.");
+    }
+    if (signal.type === "latency_regression") {
+      notes.push("Verify recent schema changes and external dependency latency.");
+    }
+    if (signal.type === "error_rate_spike") {
+      notes.push("Check SLO monitor for correlated incidents.");
+    }
+    return { signal, culprit, notes };
+  }
+}
+export {
+  RootCauseAnalyzer
+};