@lssm/lib.observability 0.2.2 → 0.3.0

package/src/index.ts

@@ -1,47 +0,0 @@
-export { getTracer, traceAsync, traceSync } from './tracing';
-export {
-  getMeter,
-  createCounter,
-  createUpDownCounter,
-  createHistogram,
-  standardMetrics,
-} from './metrics';
-export { Logger, logger } from './logging';
-export {
-  createTracingMiddleware,
-  type TracingMiddlewareOptions,
-} from './tracing/middleware';
-export {
-  IntentAggregator,
-  type IntentAggregatorSnapshot,
-  type TelemetrySample,
-} from './intent/aggregator';
-export {
-  IntentDetector,
-  type IntentSignal,
-  type IntentSignalType,
-} from './intent/detector';
-export {
-  EvolutionPipeline,
-  type EvolutionPipelineEvent,
-  type EvolutionPipelineOptions,
-} from './pipeline/evolution-pipeline';
-export {
-  LifecycleKpiPipeline,
-  type LifecycleKpiPipelineOptions,
-  type LifecyclePipelineEvent,
-} from './pipeline/lifecycle-pipeline';
-
-export type { LogLevel, LogEntry } from './logging';
-
-export { BaselineCalculator } from './anomaly/baseline-calculator';
-export {
-  AnomalyDetector,
-  type AnomalySignal,
-  type AnomalyThresholds,
-} from './anomaly/anomaly-detector';
-export {
-  RootCauseAnalyzer,
-  type RootCauseAnalysis,
-} from './anomaly/root-cause-analyzer';
-export { AlertManager } from './anomaly/alert-manager';

package/src/intent/aggregator.ts

@@ -1,161 +0,0 @@
-export interface TelemetrySample {
-  operation: { name: string; version: number };
-  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: number };
-  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;
-}
-
-const DEFAULT_WINDOW_MS = 15 * 60 * 1000; // 15 minutes
-
-export class IntentAggregator {
-  private readonly windowMs: number;
-  private readonly sequenceSampleSize: number;
-  private readonly samples: TelemetrySample[] = [];
-
-  constructor(options: IntentAggregatorOptions = {}) {
-    this.windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
-    this.sequenceSampleSize = options.sequenceSampleSize ?? 1000;
-  }
-
-  add(sample: TelemetrySample) {
-    this.samples.push(sample);
-  }
-
-  flush(now = new Date()): IntentAggregatorSnapshot {
-    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,
-    };
-  }
-
-  private aggregateMetrics(samples: TelemetrySample[]) {
-    if (!samples.length) return [] as AggregatedOperationMetrics[];
-    const groups = new Map<string, TelemetrySample[]>();
-    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 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<Record<string, number>>((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: group[0]!.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,
-      } satisfies AggregatedOperationMetrics;
-    });
-  }
-
-  private buildSequences(samples: TelemetrySample[]): OperationSequence[] {
-    const byTrace = new Map<string, TelemetrySample[]>();
-    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: Record<string, OperationSequence> = {};
-    for (const [traceId, events] of byTrace.entries()) {
-      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: number[], ratio: number) {
-  if (!values.length) return 0;
-  if (values.length === 1) return values[0]!;
-  const index = Math.min(values.length - 1, Math.floor(ratio * values.length));
-  return values[index]!;
-}

package/src/intent/detector.ts

@@ -1,187 +0,0 @@
-import { randomUUID } from 'node:crypto';
-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;
-}
-
-const DEFAULTS = {
-  errorRateThreshold: 0.05,
-  latencyP99ThresholdMs: 750,
-  throughputDropThreshold: 0.3,
-  minSequenceLength: 3,
-};
-
-export class IntentDetector {
-  private readonly options: Required<IntentDetectorOptions>;
-
-  constructor(options: IntentDetectorOptions = {}) {
-    this.options = {
-      errorRateThreshold:
-        options.errorRateThreshold ?? DEFAULTS.errorRateThreshold,
-      latencyP99ThresholdMs:
-        options.latencyP99ThresholdMs ?? DEFAULTS.latencyP99ThresholdMs,
-      throughputDropThreshold:
-        options.throughputDropThreshold ?? DEFAULTS.throughputDropThreshold,
-      minSequenceLength:
-        options.minSequenceLength ?? DEFAULTS.minSequenceLength,
-    };
-  }
-
-  detectFromMetrics(
-    current: AggregatedOperationMetrics[],
-    previous?: AggregatedOperationMetrics[]
-  ): IntentSignal[] {
-    const signals: IntentSignal[] = [];
-    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: OperationSequence[]): IntentSignal[] {
-    const signals: IntentSignal[] = [];
-    for (const sequence of sequences) {
-      if (sequence.steps.length < this.options.minSequenceLength) continue;
-      const description = sequence.steps.join(' → ');
-      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;
-  }
-}

package/src/logging/index.ts

@@ -1,56 +0,0 @@
-import { trace, context } from '@opentelemetry/api';
-
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-
-export interface LogEntry {
-  level: LogLevel;
-  message: string;
-  [key: string]: unknown;
-}
-
-export class Logger {
-  constructor(private readonly serviceName: string) {}
-
-  private log(
-    level: LogLevel,
-    message: string,
-    meta: Record<string, unknown> = {}
-  ) {
-    const span = trace.getSpan(context.active());
-    const traceId = span?.spanContext().traceId;
-    const spanId = span?.spanContext().spanId;
-
-    const entry: LogEntry = {
-      timestamp: new Date().toISOString(),
-      service: this.serviceName,
-      level,
-      message,
-      traceId,
-      spanId,
-      ...meta,
-    };
-
-    // structured logging to stdout
-    console.log(JSON.stringify(entry));
-  }
-
-  debug(message: string, meta?: Record<string, unknown>) {
-    this.log('debug', message, meta);
-  }
-
-  info(message: string, meta?: Record<string, unknown>) {
-    this.log('info', message, meta);
-  }
-
-  warn(message: string, meta?: Record<string, unknown>) {
-    this.log('warn', message, meta);
-  }
-
-  error(message: string, meta?: Record<string, unknown>) {
-    this.log('error', message, meta);
-  }
-}
-
-export const logger = new Logger(
-  process.env.OTEL_SERVICE_NAME || 'unknown-service'
-);

package/src/metrics/index.ts

@@ -1,53 +0,0 @@
-import {
-  metrics,
-  type Meter,
-  type Counter,
-  type Histogram,
-  type UpDownCounter,
-} from '@opentelemetry/api';
-
-const DEFAULT_METER_NAME = '@lssm/lib.observability';
-
-export function getMeter(name: string = DEFAULT_METER_NAME): Meter {
-  return metrics.getMeter(name);
-}
-
-export function createCounter(
-  name: string,
-  description?: string,
-  meterName?: string
-): Counter {
-  return getMeter(meterName).createCounter(name, { description });
-}
-
-export function createUpDownCounter(
-  name: string,
-  description?: string,
-  meterName?: string
-): UpDownCounter {
-  return getMeter(meterName).createUpDownCounter(name, { description });
-}
-
-export function createHistogram(
-  name: string,
-  description?: string,
-  meterName?: string
-): Histogram {
-  return getMeter(meterName).createHistogram(name, { description });
-}
-
-export const 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'
-  ),
-};

package/src/pipeline/evolution-pipeline.ts

@@ -1,90 +0,0 @@
-import { EventEmitter } from 'node:events';
-import {
-  IntentAggregator,
-  type IntentAggregatorSnapshot,
-  type TelemetrySample,
-} from '../intent/aggregator';
-import { IntentDetector, type IntentSignal } from '../intent/detector';
-
-export type EvolutionPipelineEvent =
-  | { type: 'intent.detected'; payload: IntentSignal }
-  | { type: 'telemetry.window'; payload: { sampleCount: number } };
-
-export interface EvolutionPipelineOptions {
-  detector?: IntentDetector;
-  aggregator?: IntentAggregator;
-  emitter?: EventEmitter;
-  onIntent?: (intent: IntentSignal) => Promise<void> | void;
-  onSnapshot?: (snapshot: IntentAggregatorSnapshot) => Promise<void> | void;
-}
-
-export class EvolutionPipeline {
-  private readonly detector: IntentDetector;
-  private readonly aggregator: IntentAggregator;
-  private readonly emitter: EventEmitter;
-  private readonly onIntent?: (intent: IntentSignal) => Promise<void> | void;
-  private readonly onSnapshot?: (
-    snapshot: IntentAggregatorSnapshot
-  ) => Promise<void> | void;
-  private timer?: NodeJS.Timeout;
-  private previousMetrics?: ReturnType<IntentAggregator['flush']>['metrics'];
-
-  constructor(options: EvolutionPipelineOptions = {}) {
-    this.detector = options.detector ?? new IntentDetector();
-    this.aggregator = options.aggregator ?? new IntentAggregator();
-    this.emitter = options.emitter ?? new EventEmitter();
-    this.onIntent = options.onIntent;
-    this.onSnapshot = options.onSnapshot;
-  }
-
-  ingest(sample: TelemetrySample) {
-    this.aggregator.add(sample);
-  }
-
-  on(listener: (event: EvolutionPipelineEvent) => void) {
-    this.emitter.on('event', listener);
-  }
-
-  start(intervalMs = 5 * 60 * 1000) {
-    this.stop();
-    this.timer = setInterval(() => {
-      void this.run();
-    }, intervalMs);
-  }
-
-  stop() {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = undefined;
-    }
-  }
-
-  async run() {
-    const snapshot = this.aggregator.flush();
-    this.emit({
-      type: 'telemetry.window',
-      payload: { sampleCount: snapshot.sampleCount },
-    });
-    if (this.onSnapshot) await this.onSnapshot(snapshot);
-    if (!snapshot.sampleCount) return;
-
-    const metricSignals = this.detector.detectFromMetrics(
-      snapshot.metrics,
-      this.previousMetrics
-    );
-    const sequenceSignals = this.detector.detectSequentialIntents(
-      snapshot.sequences
-    );
-    this.previousMetrics = snapshot.metrics;
-
-    const signals = [...metricSignals, ...sequenceSignals];
-    for (const signal of signals) {
-      if (this.onIntent) await this.onIntent(signal);
-      this.emit({ type: 'intent.detected', payload: signal });
-    }
-  }
-
-  private emit(event: EvolutionPipelineEvent) {
-    this.emitter.emit('event', event);
-  }
-}

package/src/pipeline/lifecycle-pipeline.ts

@@ -1,105 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { LifecycleAssessment, LifecycleStage } from '@lssm/lib.lifecycle';
-import { getStageLabel } from '@lssm/lib.lifecycle';
-import {
-  createCounter,
-  createHistogram,
-  createUpDownCounter,
-} from '../metrics';
-
-export type LifecyclePipelineEvent =
-  | {
-      type: 'assessment.recorded';
-      payload: { tenantId?: string; stage: LifecycleStage };
-    }
-  | {
-      type: 'stage.changed';
-      payload: {
-        tenantId?: string;
-        previousStage?: LifecycleStage;
-        nextStage: LifecycleStage;
-      };
-    }
-  | {
-      type: 'confidence.low';
-      payload: { tenantId?: string; confidence: number };
-    };
-
-export interface LifecycleKpiPipelineOptions {
-  meterName?: string;
-  emitter?: EventEmitter;
-  lowConfidenceThreshold?: number;
-}
-
-export class LifecycleKpiPipeline {
-  private readonly assessmentCounter;
-  private readonly confidenceHistogram;
-  private readonly stageUpDownCounter;
-  private readonly emitter: EventEmitter;
-  private readonly lowConfidenceThreshold: number;
-  private readonly currentStageByTenant = new Map<string, LifecycleStage>();
-
-  constructor(options: LifecycleKpiPipelineOptions = {}) {
-    const meterName = options.meterName ?? '@lssm/lib.lifecycle-kpi';
-    this.assessmentCounter = createCounter(
-      'lifecycle_assessments_total',
-      'Total lifecycle assessments',
-      meterName
-    );
-    this.confidenceHistogram = createHistogram(
-      'lifecycle_assessment_confidence',
-      'Lifecycle assessment confidence distribution',
-      meterName
-    );
-    this.stageUpDownCounter = createUpDownCounter(
-      'lifecycle_stage_tenants',
-      'Current tenants per lifecycle stage',
-      meterName
-    );
-    this.emitter = options.emitter ?? new EventEmitter();
-    this.lowConfidenceThreshold = options.lowConfidenceThreshold ?? 0.4;
-  }
-
-  recordAssessment(assessment: LifecycleAssessment, tenantId?: string) {
-    const stageLabel = getStageLabel(assessment.stage);
-    const attributes = { stage: stageLabel, tenantId };
-    this.assessmentCounter.add(1, attributes);
-    this.confidenceHistogram.record(assessment.confidence, attributes);
-
-    this.ensureStageCounters(assessment.stage, tenantId);
-    this.emitter.emit('event', {
-      type: 'assessment.recorded',
-      payload: { tenantId, stage: assessment.stage },
-    } satisfies LifecyclePipelineEvent);
-
-    if (assessment.confidence < this.lowConfidenceThreshold) {
-      this.emitter.emit('event', {
-        type: 'confidence.low',
-        payload: { tenantId, confidence: assessment.confidence },
-      } satisfies LifecyclePipelineEvent);
-    }
-  }
-
-  on(listener: (event: LifecyclePipelineEvent) => void) {
-    this.emitter.on('event', listener);
-  }
-
-  private ensureStageCounters(stage: LifecycleStage, tenantId?: string) {
-    if (!tenantId) return;
-    const previous = this.currentStageByTenant.get(tenantId);
-    if (previous === stage) return;
-
-    if (previous !== undefined) {
-      this.stageUpDownCounter.add(-1, {
-        stage: getStageLabel(previous),
-        tenantId,
-      });
-    }
-    this.stageUpDownCounter.add(1, { stage: getStageLabel(stage), tenantId });
-    this.currentStageByTenant.set(tenantId, stage);
-    this.emitter.emit('event', {
-      type: 'stage.changed',
-      payload: { tenantId, previousStage: previous, nextStage: stage },
-    } satisfies LifecyclePipelineEvent);
-  }
-}