@lssm/lib.observability 0.0.0-canary-20251120192244 → 0.2.1

package/src/intent/aggregator.ts

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

@@ -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/logging/index.ts

@@ -54,4 +54,3 @@ export class Logger {
 export const logger = new Logger(
   process.env.OTEL_SERVICE_NAME || 'unknown-service'
 );
-

package/src/metrics/index.ts

@@ -51,4 +51,3 @@ export const standardMetrics = {
     'Workflow execution duration'
   ),
 };
-

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/index.ts

@@ -59,4 +59,3 @@ export function traceSync<T>(
     }
   });
 }
-

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,12 +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

@@ -8,3 +8,9 @@
   }
 }
 
+
+
+
+
+
+