@juspay/neurolink 9.24.0 → 9.25.0

package/dist/lib/observability/metricsAggregator.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Metrics Aggregator
+ * Comprehensive metrics aggregation with latency percentiles, token usage, and cost tracking
+ */
+import type { TokenUsageStats } from "./tokenTracker.js";
+import { TokenTracker } from "./tokenTracker.js";
+import type { SpanData } from "./types/spanTypes.js";
+/**
+ * Latency statistics with percentile calculations
+ */
+export type LatencyStats = {
+    /** Minimum latency in milliseconds */
+    min: number;
+    /** Maximum latency in milliseconds */
+    max: number;
+    /** Mean/average latency in milliseconds */
+    mean: number;
+    /** Median latency (p50) in milliseconds */
+    median: number;
+    /** 50th percentile latency in milliseconds */
+    p50: number;
+    /** 75th percentile latency in milliseconds */
+    p75: number;
+    /** 90th percentile latency in milliseconds */
+    p90: number;
+    /** 95th percentile latency in milliseconds */
+    p95: number;
+    /** 99th percentile latency in milliseconds */
+    p99: number;
+    /** Standard deviation in milliseconds */
+    stdDev: number;
+    /** Total number of samples */
+    count: number;
+};
+/**
+ * Cost breakdown by provider
+ */
+export type ProviderCostStats = {
+    provider: string;
+    totalCost: number;
+    requestCount: number;
+    avgCostPerRequest: number;
+    inputCost: number;
+    outputCost: number;
+};
+/**
+ * Cost breakdown by model
+ */
+export type ModelCostStats = {
+    model: string;
+    provider: string;
+    totalCost: number;
+    requestCount: number;
+    avgCostPerRequest: number;
+    inputTokens: number;
+    outputTokens: number;
+    inputCost: number;
+    outputCost: number;
+};
+/**
+ * Time window statistics
+ */
+export type TimeWindowStats = {
+    windowStart: Date;
+    windowEnd: Date;
+    windowDurationMs: number;
+    requestCount: number;
+    errorCount: number;
+    successRate: number;
+    throughput: number;
+    latency: LatencyStats;
+    tokens: TokenUsageStats;
+    costByProvider: Map<string, ProviderCostStats>;
+    costByModel: Map<string, ModelCostStats>;
+};
+/**
+ * Aggregated metrics summary
+ */
+export type MetricsSummary = {
+    /** Total number of spans tracked */
+    totalSpans: number;
+    /** Number of successful spans */
+    successfulSpans: number;
+    /** Number of failed spans */
+    failedSpans: number;
+    /** Overall success rate (0-1) */
+    successRate: number;
+    /** Latency statistics */
+    latency: LatencyStats;
+    /** Token usage statistics */
+    tokens: TokenUsageStats;
+    /** Cost by provider */
+    costByProvider: ProviderCostStats[];
+    /** Cost by model */
+    costByModel: ModelCostStats[];
+    /** Total cost across all providers */
+    totalCost: number;
+    /** Span count by type */
+    spansByType: Record<string, number>;
+    /** Timestamp of first span */
+    firstSpanTime?: Date;
+    /** Timestamp of last span */
+    lastSpanTime?: Date;
+    /** Tracking duration in milliseconds */
+    trackingDurationMs?: number;
+};
+/**
+ * Hierarchical trace view grouping related spans
+ */
+export type TraceView = {
+    /** Trace identifier shared by all spans in this trace */
+    traceId: string;
+    /** The root/parent span of this trace */
+    rootSpan: SpanData;
+    /** Child spans linked to the root */
+    childSpans: SpanData[];
+    /** Total duration from first to last span */
+    totalDurationMs: number;
+    /** Total number of spans in this trace */
+    spanCount: number;
+    /** Overall trace status */
+    status: "ok" | "error" | "partial";
+};
+/**
+ * Configuration for the metrics aggregator
+ */
+export type MetricsAggregatorConfig = {
+    /** Maximum spans to retain in memory */
+    maxSpansRetained?: number;
+    /** Enable time-window statistics */
+    enableTimeWindows?: boolean;
+    /** Time window size in milliseconds (default: 60000 = 1 minute) */
+    timeWindowMs?: number;
+    /** Maximum time windows to retain */
+    maxTimeWindows?: number;
+};
+/**
+ * Metrics Aggregator for comprehensive telemetry analysis
+ * Provides latency percentiles, token aggregation, and cost tracking
+ */
+export declare class MetricsAggregator {
+    private spans;
+    private latencyValues;
+    private tokenTracker;
+    private timeWindows;
+    private config;
+    private spansByType;
+    private costByProvider;
+    private costByModel;
+    private successCount;
+    private failureCount;
+    private firstSpanTime?;
+    private lastSpanTime?;
+    constructor(config?: MetricsAggregatorConfig);
+    /**
+     * Record a span for metrics aggregation
+     */
+    recordSpan(span: SpanData): void;
+    /**
+     * Track cost aggregations from a span
+     */
+    private trackCosts;
+    /**
+     * Update time window statistics
+     */
+    private updateTimeWindow;
+    /**
+     * Create an empty time window
+     */
+    private createEmptyTimeWindow;
+    /**
+     * Create empty latency stats
+     */
+    private createEmptyLatencyStats;
+    /**
+     * Calculate latency percentile from sorted array
+     */
+    private calculatePercentile;
+    /**
+     * Calculate standard deviation
+     */
+    private calculateStdDev;
+    /**
+     * Get comprehensive latency statistics
+     */
+    getLatencyStats(): LatencyStats;
+    /**
+     * Get token usage statistics
+     */
+    getTokenStats(): TokenUsageStats;
+    /**
+     * Get cost breakdown by provider
+     */
+    getCostByProvider(): ProviderCostStats[];
+    /**
+     * Get cost breakdown by model
+     */
+    getCostByModel(): ModelCostStats[];
+    /**
+     * Get total cost across all providers
+     */
+    getTotalCost(): number;
+    /**
+     * Get time window statistics
+     */
+    getTimeWindows(): TimeWindowStats[];
+    /**
+     * Get statistics for a specific time range
+     */
+    getStatsForTimeRange(startTime: Date, endTime: Date): TimeWindowStats;
+    /**
+     * Record a latency measurement for an operation
+     * Use this for standalone latency tracking without a full span
+     */
+    recordLatency(operation: string, latencyMs: number): void;
+    /**
+     * Get comprehensive metrics summary (alias for getSummary)
+     */
+    getMetrics(): MetricsSummary;
+    /**
+     * Get comprehensive metrics summary
+     */
+    getSummary(): MetricsSummary;
+    /**
+     * Get all recorded spans (returns a copy)
+     */
+    getSpans(): SpanData[];
+    /**
+     * Get spans grouped by traceId as hierarchical trace views
+     */
+    getTraces(): TraceView[];
+    /**
+     * Get the underlying token tracker for custom pricing configuration
+     */
+    getTokenTracker(): TokenTracker;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Export metrics as JSON
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Format cost as currency string
+     */
+    formatCost(cost: number, currency?: string): string;
+    /**
+     * Get a formatted summary string
+     */
+    getFormattedSummary(): string;
+}
+/**
+ * Get the global metrics aggregator instance
+ */
+export declare function getMetricsAggregator(): MetricsAggregator;
+/**
+ * Reset the global metrics aggregator (for testing)
+ */
+export declare function resetMetricsAggregator(): void;