@lssm/lib.observability 0.0.0-canary-20251120170226 → 0.2.0

package/src/intent/detector.ts

@@ -0,0 +1,187 @@
+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/pipeline/evolution-pipeline.ts

@@ -0,0 +1,90 @@
+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

@@ -0,0 +1,105 @@
+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);
+  }
+}

package/src/tracing/middleware.ts

@@ -1,7 +1,21 @@
+import type { Span } from '@opentelemetry/api';
 import { traceAsync } from './index';
 import { standardMetrics } from '../metrics';
+import type { TelemetrySample } from '../intent/aggregator';
 
-export function createTracingMiddleware() {
+export interface TracingMiddlewareOptions {
+  resolveOperation?: (input: {
+    req: Request;
+    res?: Response;
+  }) => { name: string; version: number } | undefined;
+  onSample?: (sample: TelemetrySample) => void;
+  tenantResolver?: (req: Request) => string | undefined;
+  actorResolver?: (req: Request) => string | undefined;
+}
+
+export function createTracingMiddleware(
+  options: TracingMiddlewareOptions = {}
+) {
   return async (req: Request, next: () => Promise<Response>) => {
     const method = req.method;
     const url = new URL(req.url);
@@ -25,11 +39,73 @@ export function createTracingMiddleware() {
           status: response.status.toString(),
         });
 
+        emitTelemetrySample({
+          req,
+          res: response,
+          span,
+          success: true,
+          durationMs: duration * 1000,
+          options,
+        });
+
         return response;
       } catch (error) {
         standardMetrics.operationErrors.add(1, { method, path });
+        emitTelemetrySample({
+          req,
+          span,
+          success: false,
+          durationMs: performance.now() - startTime,
+          error,
+          options,
+        });
         throw error;
       }
     });
   };
 }
+
+interface EmitTelemetryArgs {
+  req: Request;
+  res?: Response;
+  span: Span;
+  success: boolean;
+  durationMs: number;
+  error?: unknown;
+  options: TracingMiddlewareOptions;
+}
+
+function emitTelemetrySample({
+  req,
+  res,
+  span,
+  success,
+  durationMs,
+  error,
+  options,
+}: EmitTelemetryArgs) {
+  if (!options.onSample || !options.resolveOperation) return;
+  const operation = options.resolveOperation({ req, res });
+  if (!operation) return;
+  const sample: TelemetrySample = {
+    operation,
+    durationMs,
+    success,
+    timestamp: new Date(),
+    errorCode:
+      !success && error instanceof Error
+        ? error.name
+        : success
+          ? undefined
+          : 'unknown',
+    tenantId: options.tenantResolver?.(req),
+    actorId: options.actorResolver?.(req),
+    traceId: span.spanContext().traceId,
+    metadata: {
+      method: req.method,
+      path: new URL(req.url).pathname,
+      status: res?.status,
+    },
+  };
+  options.onSample(sample);
+}

package/tsconfig.json

@@ -7,3 +7,10 @@
     "outDir": "dist"
   }
 }
+
+
+
+
+
+
+