@push.rocks/smartproxy/ts/proxies/smart-proxy/models/metrics-types.ts

A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.

/**
 * Interface for throughput sample data
 */
export interface IThroughputSample {
  timestamp: number;
  bytesIn: number;
  bytesOut: number;
  tags?: {
    route?: string;
    ip?: string;
    [key: string]: string | undefined;
  };
}

/**
 * Interface for throughput data
 */
export interface IThroughputData {
  in: number;
  out: number;
}

/**
 * Interface for time-series throughput data
 */
export interface IThroughputHistoryPoint {
  timestamp: number;
  in: number;
  out: number;
}

/**
 * Main metrics interface with clean, grouped API
 */
export interface IMetrics {
  // Connection metrics
  connections: {
    active(): number;
    total(): number;
    byRoute(): Map<string, number>;
    byIP(): Map<string, number>;
    topIPs(limit?: number): Array<{ ip: string; count: number }>;
  };
  
  // Throughput metrics (bytes per second)
  throughput: {
    instant(): IThroughputData;      // Last 1 second
    recent(): IThroughputData;       // Last 10 seconds  
    average(): IThroughputData;      // Last 60 seconds
    custom(seconds: number): IThroughputData;
    history(seconds: number): Array<IThroughputHistoryPoint>;
    byRoute(windowSeconds?: number): Map<string, IThroughputData>;  // Default: 1 second
    byIP(windowSeconds?: number): Map<string, IThroughputData>;     // Default: 1 second
  };
  
  // Request metrics
  requests: {
    perSecond(): number;
    perMinute(): number;
    total(): number;
  };
  
  // Cumulative totals
  totals: {
    bytesIn(): number;
    bytesOut(): number;
    connections(): number;
  };
  
  // Performance metrics
  percentiles: {
    connectionDuration(): { p50: number; p95: number; p99: number };
    bytesTransferred(): { 
      in: { p50: number; p95: number; p99: number };
      out: { p50: number; p95: number; p99: number };
    };
  };
}

/**
 * Configuration for metrics collection
 */
export interface IMetricsConfig {
  enabled: boolean;
  
  // Sampling configuration
  sampleIntervalMs: number;        // Default: 1000 (1 second)
  retentionSeconds: number;        // Default: 3600 (1 hour)
  
  // Performance tuning
  enableDetailedTracking: boolean; // Per-connection byte history
  enablePercentiles: boolean;      // Calculate percentiles
  cacheResultsMs: number;          // Cache expensive calculations
  
  // Export configuration
  prometheusEnabled: boolean;
  prometheusPath: string;          // Default: /metrics
  prometheusPrefix: string;        // Default: smartproxy_
}

/**
 * Internal interface for connection byte tracking
 */
export interface IByteTracker {
  connectionId: string;
  routeName: string;
  remoteIP: string;
  bytesIn: number;
  bytesOut: number;
  startTime: number;
  lastUpdate: number;
}