@shalwin04/x404r-sdk 0.1.0

package/dist/metrics.d.ts

@@ -0,0 +1,279 @@
+/**
+ * x404-r Metrics & Observability
+ *
+ * Real-world production metrics for AI agent monitoring
+ * Supports hybrid mode: in-memory tracking + database persistence
+ */
+import type { Pool } from 'pg';
+/**
+ * Database configuration for metrics persistence
+ */
+export interface MetricsDatabaseConfig {
+    pool: Pool;
+    tenantId: string;
+    flushIntervalMs?: number;
+    enabled?: boolean;
+}
+export interface MetricEvent {
+    name: string;
+    value: number;
+    timestamp: Date;
+    tags: Record<string, string>;
+    type: 'counter' | 'gauge' | 'histogram' | 'timer';
+}
+export interface MetricsSummary {
+    execution: ExecutionMetrics;
+    cost: CostMetrics;
+    performance: PerformanceMetrics;
+    reliability: ReliabilityMetrics;
+    ai: AIMetrics;
+    memory: MemoryMetrics;
+}
+export interface ExecutionMetrics {
+    tasksTotal: number;
+    tasksCompleted: number;
+    tasksFailed: number;
+    tasksPending: number;
+    tasksRunning: number;
+    successRate: number;
+    throughput: number;
+    queueDepth: number;
+    activeWorkers: number;
+}
+export interface CostMetrics {
+    totalCostUsd: number;
+    costPerTask: number;
+    costPerWorkflow: number;
+    tokensInput: number;
+    tokensOutput: number;
+    tokensTotal: number;
+    savingsFromCheckpoints: number;
+    projectedMonthlyCost: number;
+}
+export interface PerformanceMetrics {
+    latencyP50Ms: number;
+    latencyP95Ms: number;
+    latencyP99Ms: number;
+    latencyAvgMs: number;
+    throughputPerMinute: number;
+    checkpointLatencyMs: number;
+    aiLatencyMs: number;
+}
+export interface ReliabilityMetrics {
+    uptimePercent: number;
+    mtbfMinutes: number;
+    mttrSeconds: number;
+    crashRecoveries: number;
+    checkpointHitRate: number;
+    failedRecoveries: number;
+}
+export interface AIMetrics {
+    totalGenerations: number;
+    modelBreakdown: Record<string, number>;
+    avgTokensPerGeneration: number;
+    contextUtilization: number;
+    cacheHitRate: number;
+    streamingRatio: number;
+}
+export interface MemoryMetrics {
+    vectorCount: number;
+    avgRetrievalRelevance: number;
+    memoryHitRate: number;
+    learningImprovement: number;
+}
+/**
+ * Recovery Benchmark - The value x404-r provides
+ * Shows "with x404-r" vs "without x404-r" comparison
+ */
+export interface RecoveryBenchmark {
+    actual: {
+        crashes: number;
+        tokensUsed: number;
+        costUsd: number;
+        timeMs: number;
+        tasksCompleted: number;
+    };
+    withoutX404r: {
+        tokensRequired: number;
+        costUsd: number;
+        timeMs: number;
+        tasksRestarted: number;
+    };
+    savings: {
+        tokensSaved: number;
+        costSavedUsd: number;
+        timeSavedMs: number;
+        percentTokensSaved: number;
+        percentCostSaved: number;
+        percentTimeSaved: number;
+    };
+    quality: {
+        recoverySuccessRate: number;
+        avgCheckpointAge: number;
+        avgRecoveryTime: number;
+    };
+}
+/**
+ * Histogram for tracking distributions
+ */
+export declare class Histogram {
+    private values;
+    private maxSize;
+    constructor(maxSize?: number);
+    record(value: number): void;
+    percentile(p: number): number;
+    average(): number;
+    count(): number;
+    reset(): void;
+}
+/**
+ * Rate calculator for throughput metrics
+ */
+export declare class RateCalculator {
+    private events;
+    private windowMs;
+    constructor(windowMs?: number);
+    record(): void;
+    rate(): number;
+    private cleanup;
+}
+/**
+ * Main metrics collector
+ * Supports in-memory tracking with optional database persistence
+ */
+export declare class MetricsCollector {
+    private counters;
+    private gauges;
+    private histograms;
+    private rates;
+    private events;
+    private maxEvents;
+    private listeners;
+    private taskStartTimes;
+    private lastFailureTime;
+    private failureCount;
+    private recoveryTimes;
+    private recoveryEvents;
+    private taskTokenUsage;
+    private taskTimeUsage;
+    private dbConfig;
+    private flushInterval;
+    private lastFlushTime;
+    private flushInProgress;
+    constructor(maxEvents?: number);
+    /**
+     * Subscribe to metric events
+     */
+    subscribe(listener: (event: MetricEvent) => void): () => void;
+    /**
+     * Emit a metric event
+     */
+    private emit;
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    recordHistogram(name: string, value: number, tags?: Record<string, string>): void;
+    startTimer(name: string): () => number;
+    taskStarted(taskId: string, taskType: string, workflowId: string): void;
+    taskCompleted(taskId: string, taskType: string, workflowId: string): void;
+    taskFailed(taskId: string, taskType: string, workflowId: string, error: string): void;
+    taskRecovered(taskId: string, taskType: string, recoveryTimeMs: number): void;
+    /**
+     * Record a crash recovery event with full context
+     * This is used to calculate the "what if" benchmark
+     */
+    recordCrashRecovery(event: {
+        taskId: string;
+        tokensUsedBeforeCrash: number;
+        tokensUsedAfterRecovery: number;
+        timeSpentBeforeCrashMs: number;
+        checkpointAgeMs: number;
+        recoveryTimeMs: number;
+    }): void;
+    /**
+     * Track token usage for a task (used for benchmark calculation)
+     */
+    trackTaskTokens(taskId: string, tokens: number): void;
+    /**
+     * Track time usage for a task (used for benchmark calculation)
+     */
+    trackTaskTime(taskId: string, timeMs: number): void;
+    checkpointCreated(taskId: string, stepNumber: number, dataSize: number): void;
+    checkpointRestored(taskId: string, stepNumber: number): void;
+    aiGenerationStarted(model: string): () => void;
+    aiTokensUsed(model: string, input: number, output: number): void;
+    aiCostIncurred(model: string, costUsd: number): void;
+    memoryStored(taskType: string): void;
+    memoryQueried(taskType: string, resultsCount: number, relevanceScore: number): void;
+    getSummary(): MetricsSummary;
+    /**
+     * Get recent events for streaming
+     */
+    getRecentEvents(limit?: number): MetricEvent[];
+    /**
+     * Get the recovery benchmark - the value x404-r provides
+     * This shows "with x404-r" vs "without x404-r" comparison
+     */
+    getRecoveryBenchmark(): RecoveryBenchmark;
+    /**
+     * Export metrics in Prometheus format
+     */
+    toPrometheus(): string;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Configure database connection for metrics persistence
+     * Call this to enable automatic flushing to CockroachDB
+     */
+    setDatabase(config: MetricsDatabaseConfig): void;
+    /**
+     * Start automatic periodic flushing
+     */
+    private startAutoFlush;
+    /**
+     * Stop automatic flushing
+     */
+    stopAutoFlush(): void;
+    /**
+     * Flush current metrics to the database
+     * @param snapshotType - Type of snapshot: 'periodic', 'flush', 'shutdown'
+     */
+    flush(snapshotType?: 'periodic' | 'flush' | 'shutdown'): Promise<void>;
+    /**
+     * Query historical metrics from database
+     */
+    getHistory(options?: {
+        hours?: number;
+        limit?: number;
+    }): Promise<MetricsSummary[]>;
+    /**
+     * Get aggregated hourly metrics
+     */
+    getHourlyMetrics(hours?: number): Promise<Array<{
+        hour: Date;
+        avgTasksCompleted: number;
+        avgTasksFailed: number;
+        avgSuccessRate: number;
+        totalCost: number;
+        avgLatencyP50: number;
+    }>>;
+    /**
+     * Graceful shutdown - flush final metrics
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check if database persistence is configured
+     */
+    isDatabaseEnabled(): boolean;
+}
+export declare const metrics: MetricsCollector;
+/**
+ * Decorator for automatic metrics collection
+ */
+export declare function observe(name: string): <T extends (...args: unknown[]) => Promise<unknown>>(target: unknown, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+/**
+ * Helper to wrap async functions with metrics
+ */
+export declare function withMetrics<T>(name: string, fn: () => Promise<T>, tags?: Record<string, string>): Promise<T>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}