@dotdo/postgres 0.1.0

package/src/observability/query-latency.ts

@@ -0,0 +1,586 @@
+/**
+ * Query Latency Metrics
+ *
+ * Provides comprehensive query latency tracking with:
+ * - P50, P95, P99 percentile calculations
+ * - Slow query detection (configurable threshold)
+ * - Query pattern analysis and anomaly detection
+ * - OpenTelemetry-compatible metrics export
+ */
+
+import type { MetricsCollector } from './types'
+import { normalizeSQL, detectOperation } from './query-performance'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Configuration for the query latency tracker
+ */
+export interface QueryLatencyConfig {
+  /** Threshold in milliseconds for slow query detection (default: 1000) */
+  slowQueryThresholdMs?: number
+  /** Number of samples to keep for percentile calculations (default: 1000) */
+  percentileWindow?: number
+  /** Maximum number of patterns to track (default: 1000) */
+  maxPatternHistory?: number
+  /** Maximum number of slow queries to retain (default: 100) */
+  maxSlowQueries?: number
+  /** Callback invoked when a slow query is detected */
+  onSlowQuery?: (event: SlowQueryEvent) => void
+  /** Enable adaptive slow query detection based on percentiles */
+  adaptiveSlowQueryDetection?: boolean
+  /** Metrics collector for integration */
+  metricsCollector?: MetricsCollector
+}
+
+/**
+ * Input for recording query latency
+ */
+export interface LatencyRecord {
+  /** SQL statement */
+  sql: string
+  /** Duration in milliseconds */
+  durationMs: number
+  /** Optional operation type (SELECT, INSERT, etc.) */
+  operation?: string
+  /** Optional timestamp (defaults to Date.now()) */
+  timestamp?: number
+}
+
+/**
+ * Percentile values returned by getPercentiles()
+ */
+export interface LatencyPercentiles {
+  /** 50th percentile (median) */
+  p50: number
+  /** 90th percentile */
+  p90: number
+  /** 95th percentile */
+  p95: number
+  /** 99th percentile */
+  p99: number
+  /** Minimum latency */
+  min: number
+  /** Maximum latency */
+  max: number
+  /** Mean (average) latency */
+  mean: number
+}
+
+/**
+ * Options for filtering percentile calculations
+ */
+export interface PercentileFilterOptions {
+  /** Filter by operation type */
+  operation?: string
+  /** Start time for filtering (inclusive) */
+  startTime?: number
+  /** End time for filtering (inclusive) */
+  endTime?: number
+}
+
+/**
+ * Severity levels for slow queries
+ */
+export type SlowQuerySeverity = 'slow' | 'very_slow' | 'critical'
+
+/**
+ * Event emitted when a slow query is detected
+ */
+export interface SlowQueryEvent {
+  /** SQL statement */
+  sql: string
+  /** Duration in milliseconds */
+  durationMs: number
+  /** Configured threshold in milliseconds */
+  thresholdMs: number
+  /** Severity classification */
+  severity: SlowQuerySeverity
+  /** Timestamp when the query was executed */
+  timestamp: number
+  /** Operation type */
+  operation?: string
+  /** Normalized pattern */
+  pattern: string
+}
+
+/**
+ * Metrics for a query pattern
+ */
+export interface PatternMetrics {
+  /** Normalized SQL pattern */
+  normalizedPattern: string
+  /** Total execution count */
+  count: number
+  /** Average duration in milliseconds */
+  avgDurationMs: number
+  /** Minimum duration */
+  minDurationMs: number
+  /** Maximum duration */
+  maxDurationMs: number
+  /** P50 duration */
+  p50DurationMs: number
+  /** P95 duration */
+  p95DurationMs: number
+  /** P99 duration */
+  p99DurationMs: number
+  /** Latency variance */
+  latencyVariance: number
+  /** Whether this pattern has high variance */
+  isHighVariance: boolean
+  /** First execution timestamp */
+  firstSeen: number
+  /** Last execution timestamp */
+  lastSeen: number
+  /** Operation type */
+  operation: string
+}
+
+/**
+ * Pattern analysis result
+ */
+export type QueryPatternAnalysis = PatternMetrics
+
+/**
+ * Anomaly type for pattern analysis
+ */
+export type AnomalyType = 'latency_spike' | 'frequency_spike' | 'variance_change'
+
+/**
+ * Pattern anomaly record
+ */
+export interface PatternAnomaly {
+  /** Normalized pattern */
+  pattern: string
+  /** Type of anomaly */
+  anomalyType: AnomalyType
+  /** Expected value */
+  expectedValue: number
+  /** Actual value */
+  actualValue: number
+  /** Timestamp of the anomaly */
+  timestamp: number
+}
+
+/**
+ * OpenTelemetry-compatible metric format
+ */
+export interface OTelMetric {
+  /** Metric name */
+  name: string
+  /** Metric type */
+  type: 'gauge' | 'counter' | 'histogram'
+  /** Metric value */
+  value: number
+  /** Metric labels */
+  labels?: Record<string, string>
+  /** Timestamp */
+  timestamp: number
+}
+
+/**
+ * Summary statistics for the tracker
+ */
+export interface LatencySummary {
+  /** Total number of queries recorded */
+  totalQueries: number
+  /** Total duration in milliseconds */
+  totalDurationMs: number
+  /** Average duration in milliseconds */
+  avgDurationMs: number
+  /** Percentile statistics */
+  percentiles: LatencyPercentiles
+  /** Number of slow queries */
+  slowQueryCount: number
+  /** Number of unique patterns */
+  uniquePatterns: number
+}
+
+/**
+ * Query latency tracker interface
+ */
+export interface QueryLatencyTracker {
+  /** Record a query latency */
+  recordLatency(record: LatencyRecord): void
+  /** Get percentile statistics */
+  getPercentiles(options?: PercentileFilterOptions): LatencyPercentiles
+  /** Get list of slow queries */
+  getSlowQueries(): SlowQueryEvent[]
+  /** Set the slow query threshold dynamically */
+  setSlowQueryThreshold(thresholdMs: number): void
+  /** Get pattern analysis */
+  getPatternAnalysis(): PatternMetrics[]
+  /** Get top N slowest patterns */
+  getTopSlowPatterns(n: number): PatternMetrics[]
+  /** Get top N most frequent patterns */
+  getTopFrequentPatterns(n: number): PatternMetrics[]
+  /** Get pattern anomalies */
+  getPatternAnomalies(): PatternAnomaly[]
+  /** Get patterns grouped by operation type */
+  getPatternsByOperation(): Record<string, PatternMetrics[]>
+  /** Register a slow query callback */
+  onSlowQuery(callback: (event: SlowQueryEvent) => void): void
+  /** Export metrics in OpenTelemetry format */
+  exportOTelMetrics(): OTelMetric[]
+  /** Get summary statistics */
+  getSummary(): LatencySummary
+  /** Reset all tracking data */
+  reset(): void
+}
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+interface LatencyEntry {
+  durationMs: number
+  timestamp: number
+  operation?: string
+}
+
+interface PatternData {
+  pattern: string
+  operation: string
+  durations: number[]
+  timestamps: number[]
+  count: number
+  totalDurationMs: number
+  firstSeen: number
+  lastSeen: number
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Calculate percentile from sorted array
+ */
+function calculatePercentile(sortedValues: number[], percentile: number): number {
+  if (sortedValues.length === 0) return 0
+  const index = Math.ceil((percentile / 100) * sortedValues.length) - 1
+  return sortedValues[Math.max(0, index)]!
+}
+
+/**
+ * Calculate variance of an array
+ */
+function calculateVariance(values: number[]): number {
+  if (values.length === 0) return 0
+  const mean = values.reduce((sum, v) => sum + v, 0) / values.length
+  const squaredDiffs = values.map(v => Math.pow(v - mean, 2))
+  return squaredDiffs.reduce((sum, v) => sum + v, 0) / values.length
+}
+
+/**
+ * Determine slow query severity based on how much it exceeds the threshold
+ */
+function determineSeverity(durationMs: number, thresholdMs: number): SlowQuerySeverity {
+  const ratio = durationMs / thresholdMs
+  if (ratio > 5) return 'critical'
+  if (ratio > 2) return 'very_slow'
+  return 'slow'
+}
+
+/**
+ * Query latency tracker implementation
+ */
+export class QueryLatencyTrackerImpl implements QueryLatencyTracker {
+  private config: Required<Omit<QueryLatencyConfig, 'onSlowQuery' | 'metricsCollector'>> & {
+    onSlowQuery?: (event: SlowQueryEvent) => void
+    metricsCollector?: MetricsCollector
+  }
+
+  private entries: LatencyEntry[] = []
+  private patterns: Map<string, PatternData> = new Map()
+  private slowQueries: SlowQueryEvent[] = []
+  private slowQueryCallbacks: Array<(event: SlowQueryEvent) => void> = []
+  private anomalies: PatternAnomaly[] = []
+
+  constructor(config?: QueryLatencyConfig) {
+    this.config = {
+      slowQueryThresholdMs: config?.slowQueryThresholdMs ?? 1000,
+      percentileWindow: config?.percentileWindow ?? 1000,
+      maxPatternHistory: config?.maxPatternHistory ?? 1000,
+      maxSlowQueries: config?.maxSlowQueries ?? 100,
+      adaptiveSlowQueryDetection: config?.adaptiveSlowQueryDetection ?? false,
+      ...(config?.onSlowQuery !== undefined && { onSlowQuery: config.onSlowQuery }),
+      ...(config?.metricsCollector !== undefined && { metricsCollector: config.metricsCollector }),
+    }
+
+    if (this.config.onSlowQuery) {
+      this.slowQueryCallbacks.push(this.config.onSlowQuery)
+    }
+  }
+
+  recordLatency(record: LatencyRecord): void {
+    const { sql, durationMs, operation, timestamp = Date.now() } = record
+    const op = operation ?? detectOperation(sql)
+    const pattern = normalizeSQL(sql)
+
+    // Add entry
+    const entry: LatencyEntry = { durationMs, timestamp, operation: op }
+    this.entries.push(entry)
+
+    // Enforce percentile window
+    if (this.entries.length > this.config.percentileWindow) {
+      this.entries.shift()
+    }
+
+    // Update pattern data
+    let patternData = this.patterns.get(pattern)
+    if (!patternData) {
+      patternData = {
+        pattern,
+        operation: op,
+        durations: [],
+        timestamps: [],
+        count: 0,
+        totalDurationMs: 0,
+        firstSeen: timestamp,
+        lastSeen: timestamp,
+      }
+      this.patterns.set(pattern, patternData)
+    }
+
+    patternData.durations.push(durationMs)
+    patternData.timestamps.push(timestamp)
+    patternData.count++
+    patternData.totalDurationMs += durationMs
+    patternData.lastSeen = timestamp
+
+    // Enforce max durations per pattern
+    if (patternData.durations.length > this.config.percentileWindow) {
+      patternData.durations.shift()
+      patternData.timestamps.shift()
+    }
+
+    // Check for anomalies (latency spike)
+    if (patternData.durations.length >= 10) {
+      const recentDurations = patternData.durations.slice(0, -1)
+      const avgDuration = recentDurations.reduce((s, d) => s + d, 0) / recentDurations.length
+      const stdDev = Math.sqrt(calculateVariance(recentDurations))
+
+      // If current duration is more than 3 standard deviations above mean
+      if (durationMs > avgDuration + 3 * stdDev && stdDev > 0) {
+        this.anomalies.push({
+          pattern,
+          anomalyType: 'latency_spike',
+          expectedValue: avgDuration,
+          actualValue: durationMs,
+          timestamp,
+        })
+      }
+    }
+
+    // Check for slow query
+    let isSlowQuery = durationMs >= this.config.slowQueryThresholdMs
+
+    // Adaptive detection: also flag queries that are significantly above median
+    if (this.config.adaptiveSlowQueryDetection && !isSlowQuery && this.entries.length >= 10) {
+      const sorted = [...this.entries.map(e => e.durationMs)].sort((a, b) => a - b)
+      const median = calculatePercentile(sorted, 50)
+      // Flag if 10x above median
+      if (median > 0 && durationMs >= median * 10) {
+        isSlowQuery = true
+      }
+    }
+
+    if (isSlowQuery) {
+      const slowQueryEvent: SlowQueryEvent = {
+        sql,
+        durationMs,
+        thresholdMs: this.config.slowQueryThresholdMs,
+        severity: determineSeverity(durationMs, this.config.slowQueryThresholdMs),
+        timestamp,
+        operation: op,
+        pattern,
+      }
+
+      this.slowQueries.push(slowQueryEvent)
+
+      // Enforce max slow queries
+      if (this.slowQueries.length > this.config.maxSlowQueries) {
+        this.slowQueries.shift()
+      }
+
+      // Notify callbacks
+      for (const callback of this.slowQueryCallbacks) {
+        callback(slowQueryEvent)
+      }
+    }
+
+    // Record to metrics collector if available
+    if (this.config.metricsCollector) {
+      this.config.metricsCollector.histogram('postgres.query.duration_ms', durationMs, { operation: op })
+    }
+  }
+
+  getPercentiles(options?: PercentileFilterOptions): LatencyPercentiles {
+    let filteredEntries = this.entries
+
+    if (options?.operation) {
+      filteredEntries = filteredEntries.filter(e => e.operation === options.operation)
+    }
+
+    if (options?.startTime !== undefined) {
+      filteredEntries = filteredEntries.filter(e => e.timestamp >= options.startTime!)
+    }
+
+    if (options?.endTime !== undefined) {
+      filteredEntries = filteredEntries.filter(e => e.timestamp <= options.endTime!)
+    }
+
+    if (filteredEntries.length === 0) {
+      return { p50: 0, p90: 0, p95: 0, p99: 0, min: 0, max: 0, mean: 0 }
+    }
+
+    const durations = filteredEntries.map(e => e.durationMs)
+    const sorted = [...durations].sort((a, b) => a - b)
+    const sum = durations.reduce((s, d) => s + d, 0)
+
+    return {
+      p50: calculatePercentile(sorted, 50),
+      p90: calculatePercentile(sorted, 90),
+      p95: calculatePercentile(sorted, 95),
+      p99: calculatePercentile(sorted, 99),
+      min: sorted[0] ?? 0,
+      max: sorted[sorted.length - 1] ?? 0,
+      mean: sum / durations.length,
+    }
+  }
+
+  getSlowQueries(): SlowQueryEvent[] {
+    return [...this.slowQueries]
+  }
+
+  setSlowQueryThreshold(thresholdMs: number): void {
+    this.config.slowQueryThresholdMs = thresholdMs
+  }
+
+  getPatternAnalysis(): PatternMetrics[] {
+    const results: PatternMetrics[] = []
+
+    for (const data of this.patterns.values()) {
+      results.push(this.computePatternMetrics(data))
+    }
+
+    return results
+  }
+
+  getTopSlowPatterns(n: number): PatternMetrics[] {
+    return this.getPatternAnalysis()
+      .sort((a, b) => b.avgDurationMs - a.avgDurationMs)
+      .slice(0, n)
+  }
+
+  getTopFrequentPatterns(n: number): PatternMetrics[] {
+    return this.getPatternAnalysis()
+      .sort((a, b) => b.count - a.count)
+      .slice(0, n)
+  }
+
+  getPatternAnomalies(): PatternAnomaly[] {
+    return [...this.anomalies]
+  }
+
+  getPatternsByOperation(): Record<string, PatternMetrics[]> {
+    const result: Record<string, PatternMetrics[]> = {}
+
+    for (const data of this.patterns.values()) {
+      const metrics = this.computePatternMetrics(data)
+      if (!result[data.operation]) {
+        result[data.operation] = []
+      }
+      result[data.operation]!.push(metrics)
+    }
+
+    return result
+  }
+
+  onSlowQuery(callback: (event: SlowQueryEvent) => void): void {
+    this.slowQueryCallbacks.push(callback)
+  }
+
+  exportOTelMetrics(): OTelMetric[] {
+    const percentiles = this.getPercentiles()
+    const now = Date.now()
+
+    const metrics: OTelMetric[] = [
+      { name: 'postgres.query.latency.p50', type: 'gauge', value: percentiles.p50, timestamp: now },
+      { name: 'postgres.query.latency.p90', type: 'gauge', value: percentiles.p90, timestamp: now },
+      { name: 'postgres.query.latency.p95', type: 'gauge', value: percentiles.p95, timestamp: now },
+      { name: 'postgres.query.latency.p99', type: 'gauge', value: percentiles.p99, timestamp: now },
+      { name: 'postgres.query.latency.min', type: 'gauge', value: percentiles.min, timestamp: now },
+      { name: 'postgres.query.latency.max', type: 'gauge', value: percentiles.max, timestamp: now },
+      { name: 'postgres.query.latency.mean', type: 'gauge', value: percentiles.mean, timestamp: now },
+      { name: 'postgres.query.slow_query_count', type: 'counter', value: this.slowQueries.length, timestamp: now },
+      { name: 'postgres.query.unique_patterns', type: 'gauge', value: this.patterns.size, timestamp: now },
+    ]
+
+    return metrics
+  }
+
+  getSummary(): LatencySummary {
+    const percentiles = this.getPercentiles()
+
+    let totalQueries = 0
+    let totalDurationMs = 0
+
+    for (const data of this.patterns.values()) {
+      totalQueries += data.count
+      totalDurationMs += data.totalDurationMs
+    }
+
+    return {
+      totalQueries,
+      totalDurationMs,
+      avgDurationMs: totalQueries > 0 ? totalDurationMs / totalQueries : 0,
+      percentiles,
+      slowQueryCount: this.slowQueries.length,
+      uniquePatterns: this.patterns.size,
+    }
+  }
+
+  reset(): void {
+    this.entries = []
+    this.patterns.clear()
+    this.slowQueries = []
+    this.anomalies = []
+  }
+
+  private computePatternMetrics(data: PatternData): PatternMetrics {
+    const sorted = [...data.durations].sort((a, b) => a - b)
+    const variance = calculateVariance(data.durations)
+    const avgDuration = data.count > 0 ? data.totalDurationMs / data.count : 0
+
+    // High variance if standard deviation is > 50% of mean
+    const stdDev = Math.sqrt(variance)
+    const isHighVariance = avgDuration > 0 && stdDev / avgDuration > 0.5
+
+    return {
+      normalizedPattern: data.pattern,
+      count: data.count,
+      avgDurationMs: avgDuration,
+      minDurationMs: sorted.length > 0 ? sorted[0]! : 0,
+      maxDurationMs: sorted.length > 0 ? sorted[sorted.length - 1]! : 0,
+      p50DurationMs: calculatePercentile(sorted, 50),
+      p95DurationMs: calculatePercentile(sorted, 95),
+      p99DurationMs: calculatePercentile(sorted, 99),
+      latencyVariance: variance,
+      isHighVariance,
+      firstSeen: data.firstSeen,
+      lastSeen: data.lastSeen,
+      operation: data.operation,
+    }
+  }
+}
+
+/**
+ * Create a query latency tracker
+ */
+export function createQueryLatencyTracker(config?: QueryLatencyConfig): QueryLatencyTracker {
+  return new QueryLatencyTrackerImpl(config)
+}