@dotdo/postgres 0.1.0 → 0.1.1

package/src/observability/production-metrics.ts

@@ -0,0 +1,1054 @@
+/**
+ * Production Observability Metrics for PostgreSQL Durable Objects
+ *
+ * Provides query metrics, connection stats, storage tier monitoring,
+ * health checks, Prometheus export, and alerting capabilities.
+ */
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default threshold for classifying queries as "slow" (milliseconds) */
+const DEFAULT_SLOW_QUERY_THRESHOLD_MS = 100
+
+/** Maximum number of slow queries to retain in the log */
+const MAX_SLOW_QUERY_LOG_SIZE = 100
+
+/** Default maximum number of query digest patterns to track */
+const DEFAULT_MAX_QUERY_DIGESTS = 1000
+
+/** Default error rate alert threshold (percent) */
+const DEFAULT_ERROR_RATE_THRESHOLD_PERCENT = 5
+
+/** Default P99 latency alert threshold (milliseconds) */
+const DEFAULT_P99_LATENCY_THRESHOLD_MS = 1000
+
+/** Reservoir sample size for large dataset percentile calculations */
+const PERCENTILE_SAMPLE_SIZE = 1000
+
+/** Threshold for switching to reservoir sampling */
+const RESERVOIR_SAMPLING_THRESHOLD = 10000
+
+/** Number of microtask yields for the health check timeout */
+const HEALTH_CHECK_TIMEOUT_YIELD_COUNT = 20
+
+/** Default health check timeout (milliseconds) */
+export const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 5000
+
+/** Simulated heap usage in bytes (Workers environment approximation) */
+const SIMULATED_HEAP_USED_BYTES = 50 * 1024 * 1024
+
+/** Cloudflare Workers memory limit in bytes */
+const WORKER_MEMORY_LIMIT_BYTES = 128 * 1024 * 1024
+
+/** Alert evaluation frequency - evaluate every N queries to avoid performance issues */
+const ALERT_EVALUATION_INTERVAL = 100
+
+/** Time window durations for metrics windowing */
+const ONE_MINUTE_MS = 60_000
+const FIVE_MINUTES_MS = 300_000
+const FIFTEEN_MINUTES_MS = 900_000
+
+/** Storage cost estimates per byte (simplified) */
+const COST_PER_BYTE_HOT = 0.000001        // ~$1/MB (DO SQLite blob storage)
+const COST_PER_BYTE_WARM = 0.0000001       // Free (Cloudflare Cache)
+const COST_PER_BYTE_COLD = 0.000000015     // R2 pricing
+
+/** Default Prometheus histogram boundaries (seconds) */
+const DEFAULT_HISTOGRAM_BOUNDARIES = [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0]
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Configuration for the ProductionMetrics collector */
+export interface ProductionMetricsConfig {
+  /** Service name used in metric labels and exports */
+  serviceName: string
+  /** Service version for dashboard display */
+  serviceVersion?: string
+  /** Durable Object identifier */
+  doId: string
+  /** Deployment environment (e.g., 'production', 'staging') */
+  environment?: string
+  /** Collection interval for periodic metrics gathering (milliseconds) */
+  collectIntervalMs?: number
+  /** Custom histogram bucket boundaries for query duration (seconds) */
+  histogramBoundaries?: number[]
+  /** Threshold for classifying queries as slow (milliseconds) */
+  slowQueryThresholdMs?: number
+  /** Maximum number of unique query digest patterns to track */
+  maxQueryDigests?: number
+  /** Whether to collect detailed per-tier storage metrics */
+  enableDetailedStorageMetrics?: boolean
+  /** Alert threshold configuration */
+  alertThresholds?: AlertThresholdConfig
+}
+
+interface AlertThresholdConfig {
+  errorRatePercent?: number
+  p99LatencyMs?: number
+  memoryUsagePercent?: number
+  storageErrorRate?: number
+}
+
+export interface QueryRecord {
+  sql: string
+  durationMs: number
+  rowsReturned: number
+  success: boolean
+  error?: string
+}
+
+export interface QueryMetricsSnapshot {
+  totalQueries: number
+  avgDurationMs: number
+  p50DurationMs: number
+  p95DurationMs: number
+  p99DurationMs: number
+  queriesPerSecond: number
+  errorRate: number
+  totalErrors: number
+  totalRowsReturned: number
+  byOperation: Record<string, { count: number; avgDurationMs: number }>
+  windows: {
+    oneMinute: WindowMetrics
+    fiveMinutes: WindowMetrics
+    fifteenMinutes: WindowMetrics
+  }
+}
+
+interface WindowMetrics {
+  totalQueries: number
+  avgDurationMs: number
+  errorRate: number
+}
+
+export interface ConnectionStats {
+  activeConnections: number
+  totalConnectionsOpened: number
+  peakConnections: number
+  connectionErrors: number
+  avgConnectionDurationMs: number
+  idleConnections: number
+  poolUtilization: number
+  websocketConnections: number
+  httpConnections: number
+  avgWaitTimeMs: number
+  uptimeMs: number
+}
+
+export interface StorageTierSnapshot {
+  hot: TierStats
+  warm: TierStats
+  cold: TierStats
+  promotions: { coldToWarm: number; warmToHot: number }
+  demotions: { hotToWarm: number; warmToCold: number }
+  estimatedCosts: { hot: number; warm: number; cold: number; total: number }
+  tieringEfficiency: number
+}
+
+interface TierStats {
+  hitRate: number
+  bytesRead: number
+  bytesWritten: number
+  totalOperations: number
+  avgLatencyMs: number
+  errors: number
+  usageBytes: number
+  healthStatus: 'healthy' | 'degraded' | 'unhealthy'
+}
+
+export interface HealthCheckResult {
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  service?: string
+  uptimeMs?: number
+  checks: Record<string, ComponentHealth>
+  responseTimeMs?: number
+}
+
+interface ComponentHealth {
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  error?: string
+  details?: any
+}
+
+export interface MetricsDashboard {
+  queries: QueryMetricsSnapshot
+  connections: ConnectionStats
+  storage: StorageTierSnapshot
+  health: HealthCheckResult
+  service: { name: string; doId: string; uptimeMs: number; version?: string }
+  memory: { heapUsedBytes: number; heapTotalBytes: number }
+  alerts: Alert[]
+  timestamp: number
+}
+
+export interface AlertThreshold {
+  name: string
+  type: string
+  threshold: number
+  windowMs?: number
+  severity: 'warning' | 'critical'
+}
+
+interface Alert {
+  name?: string
+  type: string
+  severity: 'warning' | 'critical'
+  message: string
+  triggeredAt: number
+  value?: number
+}
+
+export type MetricsExportFormat = 'prometheus' | 'json'
+
+export interface PrometheusMetric {
+  name: string
+  help: string
+  type: 'counter' | 'gauge' | 'histogram'
+  value?: number
+  labels?: Record<string, string>
+}
+
+export interface QueryDigest {
+  pattern: string
+  count: number
+  avgDurationMs: number
+  totalDurationMs: number
+  lastSeen: number
+}
+
+export interface SlowQueryLog {
+  sql: string
+  durationMs: number
+  rowsReturned: number
+  timestamp: number
+}
+
+// =============================================================================
+// Internal State Types
+// =============================================================================
+
+interface QueryEntry {
+  durationMs: number
+  success: boolean
+  timestamp: number
+  operation: string
+  rowsReturned: number
+}
+
+interface ConnectionEntry {
+  type: 'websocket' | 'http' | 'unknown'
+  openedAt: number
+  idle: boolean
+}
+
+interface StorageOp {
+  tier: 'hot' | 'warm' | 'cold'
+  operation: 'read' | 'write'
+  hit?: boolean
+  bytes: number
+  durationMs?: number
+  timestamp: number
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/** Extracts the SQL operation type (SELECT, INSERT, UPDATE, DELETE, OTHER) from a query string */
+function extractOperation(sql: string): string {
+  const trimmed = sql.trim().toUpperCase()
+  if (trimmed.startsWith('SELECT')) return 'SELECT'
+  if (trimmed.startsWith('INSERT')) return 'INSERT'
+  if (trimmed.startsWith('UPDATE')) return 'UPDATE'
+  if (trimmed.startsWith('DELETE')) return 'DELETE'
+  return 'OTHER'
+}
+
+/** Normalizes a query by replacing numeric literals with placeholders for digest grouping */
+function normalizeQuery(sql: string): string {
+  return sql.replace(/\b\d+\b/g, '$N')
+}
+
+/**
+ * Calculates the p-th percentile from a pre-sorted array using the nearest-rank method.
+ * Returns 0 for empty arrays.
+ */
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0
+  if (sorted.length === 1) return sorted[0]
+  const idx = Math.ceil((p / 100) * sorted.length)
+  return sorted[Math.min(idx, sorted.length - 1)]
+}
+
+// =============================================================================
+// ProductionMetrics Class
+// =============================================================================
+
+/**
+ * Collects and exposes production metrics for PostgreSQL Durable Objects.
+ * Tracks query performance, connection statistics, storage tier operations,
+ * and provides health checks, Prometheus export, and alerting.
+ */
+export class ProductionMetrics {
+  private config: ProductionMetricsConfig
+  private startTime: number
+
+  // Query metrics state
+  private queries: QueryEntry[] = []
+  private slowQueries: SlowQueryLog[] = []
+  private digestMap: Map<string, QueryDigest> = new Map()
+  private totalErrors = 0
+  private totalRowsReturned = 0
+
+  // Connection state
+  private connections: ConnectionEntry[] = []
+  private totalConnectionsOpened = 0
+  private peakConnections = 0
+  private connectionErrors = 0
+  private connectionDurations: number[] = []
+  private waitTimes: number[] = []
+  private idleConnections = 0
+
+  // Storage state
+  private storageOps: StorageOp[] = []
+  private tierPromotions = { coldToWarm: 0, warmToHot: 0 }
+  private tierDemotions = { hotToWarm: 0, warmToCold: 0 }
+  private tierErrors: Record<string, number> = { hot: 0, warm: 0, cold: 0 }
+  private tierUsage: Record<string, number> = { hot: 0, warm: 0, cold: 0 }
+  private tierHealth: Record<string, string> = { hot: 'healthy', warm: 'healthy', cold: 'healthy' }
+
+  // Dependencies
+  private pgliteInstance: any = null
+  private storageOrchestrator: any = null
+
+  // Alert state
+  private activeAlerts: Alert[] = []
+  private customThresholds: AlertThreshold[] = []
+
+  constructor(config: ProductionMetricsConfig) {
+    this.config = config
+    this.startTime = Date.now()
+  }
+
+  // ===========================================================================
+  // Query Metrics
+  // ===========================================================================
+
+  /** Records a completed query, updating metrics, digests, slow query log, and alerts */
+  recordQuery(record: QueryRecord): void {
+    const operation = extractOperation(record.sql)
+    const entry: QueryEntry = {
+      durationMs: Math.max(0, record.durationMs),
+      success: record.success,
+      timestamp: Date.now(),
+      operation,
+      rowsReturned: record.rowsReturned,
+    }
+
+    this.queries.push(entry)
+    this.totalRowsReturned += record.rowsReturned
+
+    if (!record.success) {
+      this.totalErrors++
+    }
+
+    this.trackSlowQuery(record)
+    this.updateQueryDigest(record)
+
+    // Evaluate alerts periodically to avoid performance overhead on high-throughput workloads
+    if (this.queries.length <= ALERT_EVALUATION_INTERVAL || this.queries.length % ALERT_EVALUATION_INTERVAL === 0) {
+      this.evaluateAlerts()
+    }
+  }
+
+  /** Adds a query to the slow query log if it exceeds the configured threshold */
+  private trackSlowQuery(record: QueryRecord): void {
+    const threshold = this.config.slowQueryThresholdMs || DEFAULT_SLOW_QUERY_THRESHOLD_MS
+    if (record.durationMs >= threshold) {
+      this.slowQueries.push({
+        sql: record.sql,
+        durationMs: record.durationMs,
+        rowsReturned: record.rowsReturned,
+        timestamp: Date.now(),
+      })
+      if (this.slowQueries.length > MAX_SLOW_QUERY_LOG_SIZE) {
+        this.slowQueries = this.slowQueries.slice(-MAX_SLOW_QUERY_LOG_SIZE)
+      }
+    }
+  }
+
+  /** Updates the query digest map with a new query record */
+  private updateQueryDigest(record: QueryRecord): void {
+    const pattern = normalizeQuery(record.sql)
+    const existing = this.digestMap.get(pattern)
+    if (existing) {
+      existing.count++
+      existing.totalDurationMs += record.durationMs
+      existing.avgDurationMs = existing.totalDurationMs / existing.count
+      existing.lastSeen = Date.now()
+    } else {
+      const maxDigests = this.config.maxQueryDigests || DEFAULT_MAX_QUERY_DIGESTS
+      if (this.digestMap.size < maxDigests) {
+        this.digestMap.set(pattern, {
+          pattern,
+          count: 1,
+          avgDurationMs: record.durationMs,
+          totalDurationMs: record.durationMs,
+          lastSeen: Date.now(),
+        })
+      }
+    }
+  }
+
+  /** Returns a comprehensive snapshot of query performance metrics */
+  getQueryMetrics(): QueryMetricsSnapshot {
+    const total = this.queries.length
+    const durations = this.getSortedDurationsSample(total)
+    const totalDurationSum = total > 0 ? this.queries.reduce((s, q) => s + q.durationMs, 0) : 0
+    const avgDuration = total > 0 ? totalDurationSum / total : 0
+    const errors = this.queries.filter((q) => !q.success).length
+    const errorRate = total > 0 ? errors / total : 0
+
+    const now = Date.now()
+    const elapsedSeconds = Math.max(1, (now - this.startTime) / 1000)
+    const queriesPerSecond = total / elapsedSeconds
+
+    const byOperation = this.computeOperationBreakdown()
+
+    const windows = {
+      oneMinute: this.getWindowMetrics(now - ONE_MINUTE_MS),
+      fiveMinutes: this.getWindowMetrics(now - FIVE_MINUTES_MS),
+      fifteenMinutes: this.getWindowMetrics(now - FIFTEEN_MINUTES_MS),
+    }
+
+    return {
+      totalQueries: total,
+      avgDurationMs: avgDuration,
+      p50DurationMs: percentile(durations, 50),
+      p95DurationMs: percentile(durations, 95),
+      p99DurationMs: percentile(durations, 99),
+      queriesPerSecond,
+      errorRate,
+      totalErrors: errors,
+      totalRowsReturned: this.totalRowsReturned,
+      byOperation,
+      windows,
+    }
+  }
+
+  /** Returns sorted duration samples, using reservoir sampling for large datasets */
+  private getSortedDurationsSample(total: number): number[] {
+    if (total > RESERVOIR_SAMPLING_THRESHOLD) {
+      const sample: number[] = []
+      for (let i = 0; i < total; i++) {
+        if (i < PERCENTILE_SAMPLE_SIZE) {
+          sample.push(this.queries[i].durationMs)
+        } else {
+          const j = Math.floor(Math.random() * (i + 1))
+          if (j < PERCENTILE_SAMPLE_SIZE) {
+            sample[j] = this.queries[i].durationMs
+          }
+        }
+      }
+      return sample.sort((a, b) => a - b)
+    }
+    return this.queries.map((q) => q.durationMs).sort((a, b) => a - b)
+  }
+
+  /** Computes per-operation count and average duration breakdown */
+  private computeOperationBreakdown(): Record<string, { count: number; avgDurationMs: number }> {
+    const byOperation: Record<string, { count: number; avgDurationMs: number }> = {}
+    for (const q of this.queries) {
+      if (!byOperation[q.operation]) {
+        byOperation[q.operation] = { count: 0, avgDurationMs: 0 }
+      }
+      byOperation[q.operation].count++
+    }
+    for (const op of Object.keys(byOperation)) {
+      const opQueries = this.queries.filter((q) => q.operation === op)
+      const sum = opQueries.reduce((s, q) => s + q.durationMs, 0)
+      byOperation[op].avgDurationMs = opQueries.length > 0 ? sum / opQueries.length : 0
+    }
+    return byOperation
+  }
+
+  /** Returns a copy of the slow query log */
+  getSlowQueryLog(): SlowQueryLog[] {
+    return [...this.slowQueries]
+  }
+
+  /** Returns all tracked query digest patterns */
+  getQueryDigests(): QueryDigest[] {
+    return Array.from(this.digestMap.values())
+  }
+
+  /** Resets all query-related metrics, including digests and slow query log */
+  resetQueryMetrics(): void {
+    this.queries = []
+    this.slowQueries = []
+    this.digestMap.clear()
+    this.totalErrors = 0
+    this.totalRowsReturned = 0
+  }
+
+  // ===========================================================================
+  // Connection Stats
+  // ===========================================================================
+
+  /** Records a new connection being opened */
+  recordConnectionOpen(options?: { type?: 'websocket' | 'http' }): void {
+    const conn: ConnectionEntry = {
+      type: options?.type || 'unknown',
+      openedAt: Date.now(),
+      idle: false,
+    }
+    this.connections.push(conn)
+    this.totalConnectionsOpened++
+    if (this.connections.length > this.peakConnections) {
+      this.peakConnections = this.connections.length
+    }
+  }
+
+  /** Records a connection being closed, optionally with its total duration */
+  recordConnectionClose(options?: { durationMs?: number }): void {
+    if (this.connections.length > 0) {
+      const conn = this.connections.pop()!
+      if (conn.idle) {
+        this.idleConnections = Math.max(0, this.idleConnections - 1)
+      }
+      if (options?.durationMs !== undefined) {
+        this.connectionDurations.push(options.durationMs)
+      }
+    }
+  }
+
+  /** Records a connection error */
+  recordConnectionError(_message: string): void {
+    this.connectionErrors++
+  }
+
+  /** Records a connection transitioning to idle state */
+  recordConnectionIdle(): void {
+    this.idleConnections++
+  }
+
+  /** Records a connection being acquired from the pool, with wait time */
+  recordConnectionAcquired(options: { waitTimeMs: number }): void {
+    this.waitTimes.push(options.waitTimeMs)
+  }
+
+  /** Returns a snapshot of connection statistics */
+  getConnectionStats(): ConnectionStats {
+    const wsCount = this.connections.filter((c) => c.type === 'websocket').length
+    const httpCount = this.connections.filter((c) => c.type === 'http').length
+
+    const avgDuration = this.connectionDurations.length > 0
+      ? this.connectionDurations.reduce((s, d) => s + d, 0) / this.connectionDurations.length
+      : 0
+
+    const avgWait = this.waitTimes.length > 0
+      ? this.waitTimes.reduce((s, w) => s + w, 0) / this.waitTimes.length
+      : 0
+
+    return {
+      activeConnections: this.connections.length,
+      totalConnectionsOpened: this.totalConnectionsOpened,
+      peakConnections: this.peakConnections,
+      connectionErrors: this.connectionErrors,
+      avgConnectionDurationMs: avgDuration,
+      idleConnections: this.idleConnections,
+      poolUtilization: Math.min(1.0, this.connections.length), // max_connections=1 in DO model
+      websocketConnections: wsCount,
+      httpConnections: httpCount,
+      avgWaitTimeMs: avgWait,
+      uptimeMs: Date.now() - this.startTime,
+    }
+  }
+
+  // ===========================================================================
+  // Storage Tier Stats
+  // ===========================================================================
+
+  /** Records a storage tier operation (read/write) with optional hit/miss and timing */
+  recordStorageOperation(
+    tier: 'hot' | 'warm' | 'cold',
+    operation: 'read' | 'write',
+    options: { hit?: boolean; bytes: number; durationMs?: number }
+  ): void {
+    this.storageOps.push({
+      tier,
+      operation,
+      hit: options.hit,
+      bytes: options.bytes,
+      durationMs: options.durationMs,
+      timestamp: Date.now(),
+    })
+  }
+
+  /** Records a data promotion between storage tiers */
+  recordTierPromotion(from: string, to: string, _details: { key: string; bytes: number }): void {
+    if (from === 'cold' && to === 'warm') this.tierPromotions.coldToWarm++
+    if (from === 'warm' && to === 'hot') this.tierPromotions.warmToHot++
+  }
+
+  /** Records a data demotion between storage tiers */
+  recordTierDemotion(from: string, to: string, _details: { key: string; bytes: number }): void {
+    if (from === 'hot' && to === 'warm') this.tierDemotions.hotToWarm++
+    if (from === 'warm' && to === 'cold') this.tierDemotions.warmToCold++
+  }
+
+  /** Records a storage error and triggers alert if threshold is exceeded */
+  recordStorageError(tier: string, _message: string): void {
+    this.tierErrors[tier] = (this.tierErrors[tier] || 0) + 1
+
+    // Check alert threshold
+    const totalStorageErrors = Object.values(this.tierErrors).reduce((s, e) => s + e, 0)
+    const threshold = this.config.alertThresholds?.storageErrorRate
+    if (threshold !== undefined && totalStorageErrors > threshold) {
+      this.addAlert({
+        type: 'storage_error',
+        severity: 'critical',
+        message: `Storage error rate exceeded threshold: ${totalStorageErrors} errors`,
+        triggeredAt: Date.now(),
+        value: totalStorageErrors,
+      })
+    }
+  }
+
+  /** Records the current storage usage for a tier */
+  recordStorageUsage(tier: 'hot' | 'warm' | 'cold', bytes: number): void {
+    this.tierUsage[tier] = bytes
+  }
+
+  /** Records a change in tier health status */
+  recordTierHealthChange(tier: string, status: 'healthy' | 'degraded' | 'unhealthy'): void {
+    this.tierHealth[tier] = status
+  }
+
+  /** Returns a comprehensive snapshot of storage tier statistics including costs */
+  getStorageTierStats(): StorageTierSnapshot {
+    const getTierStats = (tier: 'hot' | 'warm' | 'cold'): TierStats => {
+      const ops = this.storageOps.filter((o) => o.tier === tier)
+      const reads = ops.filter((o) => o.operation === 'read')
+      const hits = reads.filter((o) => o.hit === true).length
+      const hitRate = reads.length > 0 ? hits / reads.length : 0
+
+      const bytesRead = ops.filter((o) => o.operation === 'read').reduce((s, o) => s + o.bytes, 0)
+      const bytesWritten = ops.filter((o) => o.operation === 'write').reduce((s, o) => s + o.bytes, 0)
+
+      const durationsWithValues = ops.filter((o) => o.durationMs !== undefined)
+      const avgLatencyMs = durationsWithValues.length > 0
+        ? durationsWithValues.reduce((s, o) => s + (o.durationMs || 0), 0) / durationsWithValues.length
+        : 0
+
+      return {
+        hitRate,
+        bytesRead,
+        bytesWritten,
+        totalOperations: ops.length,
+        avgLatencyMs,
+        errors: this.tierErrors[tier] || 0,
+        usageBytes: this.tierUsage[tier] || 0,
+        healthStatus: (this.tierHealth[tier] || 'healthy') as 'healthy' | 'degraded' | 'unhealthy',
+      }
+    }
+
+    const hotStats = getTierStats('hot')
+    const warmStats = getTierStats('warm')
+    const coldStats = getTierStats('cold')
+
+    // Estimate costs based on bytes stored
+    const hotCost = (this.tierUsage['hot'] || 0) * COST_PER_BYTE_HOT
+    const warmCost = (this.tierUsage['warm'] || 0) * COST_PER_BYTE_WARM
+    const coldCost = (this.tierUsage['cold'] || 0) * COST_PER_BYTE_COLD
+
+    // Calculate tiering efficiency (hot hit rate as primary metric)
+    const hotReads = this.storageOps.filter((o) => o.tier === 'hot' && o.operation === 'read')
+    const hotHits = hotReads.filter((o) => o.hit === true).length
+    const tieringEfficiency = hotReads.length > 0 ? hotHits / hotReads.length : 0
+
+    return {
+      hot: hotStats,
+      warm: warmStats,
+      cold: coldStats,
+      promotions: { ...this.tierPromotions },
+      demotions: { ...this.tierDemotions },
+      estimatedCosts: {
+        hot: hotCost,
+        warm: warmCost,
+        cold: coldCost,
+        total: hotCost + warmCost + coldCost,
+      },
+      tieringEfficiency,
+    }
+  }
+
+  // ===========================================================================
+  // Health Checks
+  // ===========================================================================
+
+  /** Sets the PGLite instance for health check queries */
+  setPGLiteInstance(pglite: any): void {
+    this.pgliteInstance = pglite
+  }
+
+  /** Sets the storage orchestrator for health check tier status */
+  setStorageOrchestrator(orchestrator: any): void {
+    this.storageOrchestrator = orchestrator
+  }
+
+  /** Returns a simple liveness probe result (always healthy if the service is running) */
+  liveness(): { status: 'healthy'; service: string; uptimeMs: number } {
+    return {
+      status: 'healthy',
+      service: this.config.serviceName,
+      uptimeMs: Date.now() - this.startTime,
+    }
+  }
+
+  /** Performs a readiness check including PGLite, storage, and memory health */
+  async readiness(_options?: { timeoutMs?: number }): Promise<HealthCheckResult> {
+    const startTime = Date.now()
+    const checks: Record<string, ComponentHealth> = {}
+
+    checks.pglite = await this.checkPGLiteHealth()
+    checks.storage = this.checkStorageHealth()
+    checks.memory = {
+      status: 'healthy',
+      details: {
+        heapUsedBytes: SIMULATED_HEAP_USED_BYTES,
+        heapTotalBytes: WORKER_MEMORY_LIMIT_BYTES,
+      },
+    }
+
+    const overallStatus = this.determineOverallStatus(checks)
+
+    return {
+      status: overallStatus,
+      checks,
+      responseTimeMs: Date.now() - startTime,
+    }
+  }
+
+  /** Checks PGLite health with a microtask-based timeout */
+  private async checkPGLiteHealth(): Promise<ComponentHealth> {
+    if (!this.pgliteInstance) {
+      return { status: 'unhealthy', error: 'PGLite not initialized' }
+    }
+
+    try {
+      const queryPromise = this.pgliteInstance.query('SELECT 1 as result')
+      let settled = false
+      const wrappedQuery = queryPromise.then(
+        (v: any) => { settled = true; return v },
+        (e: any) => { settled = true; throw e }
+      )
+      const timeoutCheck = new Promise<never>(async (_, reject) => {
+        for (let i = 0; i < HEALTH_CHECK_TIMEOUT_YIELD_COUNT; i++) {
+          await Promise.resolve()
+          if (settled) return
+        }
+        if (!settled) {
+          reject(new Error('Health check timeout'))
+        }
+      })
+      await Promise.race([wrappedQuery, timeoutCheck])
+      return { status: 'healthy' }
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : 'Unknown health check error'
+      return {
+        status: 'unhealthy',
+        error: errorMsg.includes('timeout') ? 'Health check timeout' : errorMsg,
+      }
+    }
+  }
+
+  /** Checks storage orchestrator health */
+  private checkStorageHealth(): ComponentHealth {
+    if (!this.storageOrchestrator) {
+      return { status: 'healthy', details: { message: 'No orchestrator configured' } }
+    }
+
+    const tierHealth = this.storageOrchestrator.getTierHealth()
+    const allHealthy = Object.values(tierHealth).every((t: any) => t.status === 'healthy')
+    const anyDegraded = Object.values(tierHealth).some((t: any) => t.status === 'degraded')
+
+    return {
+      status: allHealthy ? 'healthy' : (anyDegraded ? 'degraded' : 'unhealthy'),
+      details: tierHealth,
+    }
+  }
+
+  /** Determines the worst overall status from all component checks */
+  private determineOverallStatus(checks: Record<string, ComponentHealth>): 'healthy' | 'degraded' | 'unhealthy' {
+    const statuses = Object.values(checks).map((c) => c.status)
+    if (statuses.includes('unhealthy')) return 'unhealthy'
+    if (statuses.includes('degraded')) return 'degraded'
+    return 'healthy'
+  }
+
+  /** Performs a deep health check including WAL status */
+  async deepCheck(): Promise<HealthCheckResult> {
+    const startTime = Date.now()
+    const readinessResult = await this.readiness()
+
+    // Add WAL check
+    readinessResult.checks.wal = {
+      status: 'healthy',
+      details: { lastArchive: 'N/A' },
+    }
+
+    readinessResult.responseTimeMs = Date.now() - startTime
+    return readinessResult
+  }
+
+  // ===========================================================================
+  // Metrics Export
+  // ===========================================================================
+
+  /** Exports all metrics in Prometheus text exposition format */
+  exportPrometheus(): string {
+    const lines: string[] = []
+    const labels = `service="${this.config.serviceName}",do_id="${this.config.doId}"`
+    const queryMetrics = this.getQueryMetrics()
+
+    // Query total counter
+    lines.push('# HELP postgres_query_total Total number of queries executed')
+    lines.push('# TYPE postgres_query_total counter')
+    lines.push(`postgres_query_total{${labels}} ${queryMetrics.totalQueries}`)
+
+    // Query errors
+    lines.push('# HELP postgres_query_errors_total Total number of query errors')
+    lines.push('# TYPE postgres_query_errors_total counter')
+    lines.push(`postgres_query_errors_total{${labels}} ${queryMetrics.totalErrors}`)
+
+    // Query duration histogram
+    lines.push('# HELP postgres_query_duration_seconds Query execution time in seconds')
+    lines.push('# TYPE postgres_query_duration_seconds histogram')
+
+    const boundaries = this.config.histogramBoundaries || DEFAULT_HISTOGRAM_BOUNDARIES
+    const durations = this.queries.map((q) => q.durationMs / 1000).sort((a, b) => a - b)
+    let sum = 0
+
+    for (const boundary of boundaries) {
+      const count = durations.filter((d) => d <= boundary).length
+      lines.push(`postgres_query_duration_seconds_bucket{${labels},le="${boundary}"} ${count}`)
+    }
+    lines.push(`postgres_query_duration_seconds_bucket{${labels},le="+Inf"} ${durations.length}`)
+
+    sum = durations.reduce((s, d) => s + d, 0)
+    lines.push(`postgres_query_duration_seconds_count{${labels}} ${durations.length}`)
+    lines.push(`postgres_query_duration_seconds_sum{${labels}} ${sum}`)
+
+    // Connections
+    const connStats = this.getConnectionStats()
+    lines.push('# HELP postgres_connections_active Current active connections')
+    lines.push('# TYPE postgres_connections_active gauge')
+    lines.push(`postgres_connections_active{${labels}} ${connStats.activeConnections}`)
+
+    // Storage operations
+    lines.push('# HELP postgres_storage_operations_total Total storage operations')
+    lines.push('# TYPE postgres_storage_operations_total counter')
+    for (const tier of ['hot', 'warm', 'cold'] as const) {
+      const count = this.storageOps.filter((o) => o.tier === tier).length
+      lines.push(`postgres_storage_operations_total{${labels},tier="${tier}"} ${count}`)
+    }
+
+    return lines.join('\n')
+  }
+
+  /** Exports all metrics as a structured JSON object */
+  exportJSON(): { metrics: any; timestamp: number; service: string } {
+    return {
+      metrics: {
+        queries: this.getQueryMetrics(),
+        connections: this.getConnectionStats(),
+        storage: this.getStorageTierStats(),
+      },
+      timestamp: Date.now(),
+      service: this.config.serviceName,
+    }
+  }
+
+  /** Creates an HTTP request handler that serves metrics in Prometheus or JSON format */
+  createMetricsHandler(): (request: Request) => Promise<Response> {
+    return async (request: Request) => {
+      const accept = request.headers.get('Accept') || 'text/plain'
+
+      if (accept.includes('application/json')) {
+        const json = this.exportJSON()
+        return new Response(JSON.stringify(json), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      }
+
+      // Default: Prometheus format
+      const prometheus = this.exportPrometheus()
+      return new Response(prometheus, {
+        status: 200,
+        headers: { 'content-type': 'text/plain; charset=utf-8' },
+      })
+    }
+  }
+
+  // ===========================================================================
+  // Dashboard
+  // ===========================================================================
+
+  /** Returns a complete metrics dashboard snapshot for display */
+  getDashboard(): MetricsDashboard {
+    return {
+      queries: this.getQueryMetrics(),
+      connections: this.getConnectionStats(),
+      storage: this.getStorageTierStats(),
+      health: {
+        status: 'healthy',
+        checks: {},
+      },
+      service: {
+        name: this.config.serviceName,
+        doId: this.config.doId,
+        uptimeMs: Date.now() - this.startTime,
+        version: this.config.serviceVersion,
+      },
+      memory: {
+        heapUsedBytes: SIMULATED_HEAP_USED_BYTES,
+        heapTotalBytes: WORKER_MEMORY_LIMIT_BYTES,
+      },
+      alerts: this.getActiveAlerts(),
+      timestamp: Date.now(),
+    }
+  }
+
+  // ===========================================================================
+  // Alerts
+  // ===========================================================================
+
+  /** Evaluates all alert conditions against current metrics, adding/removing alerts as needed */
+  evaluateAlerts(): void {
+    const queryMetrics = this.getQueryMetrics()
+
+    const errorThreshold = this.config.alertThresholds?.errorRatePercent ?? DEFAULT_ERROR_RATE_THRESHOLD_PERCENT
+    const errorRatePercent = queryMetrics.errorRate * 100
+    if (errorRatePercent > errorThreshold) {
+      this.addAlert({
+        type: 'error_rate',
+        severity: 'critical',
+        message: `Error rate ${errorRatePercent.toFixed(1)}% exceeds threshold ${errorThreshold}%`,
+        triggeredAt: Date.now(),
+        value: errorRatePercent,
+      })
+    } else {
+      // Resolve error rate alerts
+      this.activeAlerts = this.activeAlerts.filter((a) => a.type !== 'error_rate')
+    }
+
+    const p99Threshold = this.config.alertThresholds?.p99LatencyMs ?? DEFAULT_P99_LATENCY_THRESHOLD_MS
+    if (queryMetrics.p99DurationMs > p99Threshold) {
+      this.addAlert({
+        type: 'high_latency',
+        severity: 'warning',
+        message: `P99 latency ${queryMetrics.p99DurationMs}ms exceeds threshold ${p99Threshold}ms`,
+        triggeredAt: Date.now(),
+        value: queryMetrics.p99DurationMs,
+      })
+    } else {
+      this.activeAlerts = this.activeAlerts.filter((a) => a.type !== 'high_latency')
+    }
+
+    // Custom thresholds (e.g. slow query count)
+    for (const threshold of this.customThresholds) {
+      if (threshold.type === 'slow_query_count') {
+        const slowCount = this.slowQueries.length
+        if (slowCount > threshold.threshold) {
+          this.addAlert({
+            name: threshold.name,
+            type: threshold.type,
+            severity: threshold.severity,
+            message: `Slow query count ${slowCount} exceeds threshold ${threshold.threshold}`,
+            triggeredAt: Date.now(),
+            value: slowCount,
+          })
+        }
+      }
+    }
+  }
+
+  /** Returns a copy of all currently active alerts */
+  getActiveAlerts(): Alert[] {
+    return [...this.activeAlerts]
+  }
+
+  /** Registers a custom alert threshold for evaluation */
+  registerAlertThreshold(threshold: AlertThreshold): void {
+    this.customThresholds.push(threshold)
+  }
+
+  // ===========================================================================
+  // Reset
+  // ===========================================================================
+
+  /** Resets all metrics state (queries, connections, storage, alerts) */
+  resetAll(): void {
+    this.resetQueryMetrics()
+    this.connections = []
+    this.totalConnectionsOpened = 0
+    this.peakConnections = 0
+    this.connectionErrors = 0
+    this.connectionDurations = []
+    this.waitTimes = []
+    this.idleConnections = 0
+    this.storageOps = []
+    this.tierPromotions = { coldToWarm: 0, warmToHot: 0 }
+    this.tierDemotions = { hotToWarm: 0, warmToCold: 0 }
+    this.tierErrors = { hot: 0, warm: 0, cold: 0 }
+    this.tierUsage = { hot: 0, warm: 0, cold: 0 }
+    this.activeAlerts = []
+  }
+
+  // ===========================================================================
+  // Private Helpers
+  // ===========================================================================
+
+  private getWindowMetrics(sinceTimestamp: number): WindowMetrics {
+    const windowQueries = this.queries.filter((q) => q.timestamp >= sinceTimestamp)
+    const total = windowQueries.length
+    const errors = windowQueries.filter((q) => !q.success).length
+    const avgDuration = total > 0
+      ? windowQueries.reduce((s, q) => s + q.durationMs, 0) / total
+      : 0
+
+    return {
+      totalQueries: total,
+      avgDurationMs: avgDuration,
+      errorRate: total > 0 ? errors / total : 0,
+    }
+  }
+
+  private addAlert(alert: Alert): void {
+    // Don't add duplicate alerts of same type
+    const existing = this.activeAlerts.find((a) =>
+      a.type === alert.type && (alert.name ? a.name === alert.name : true)
+    )
+    if (!existing) {
+      this.activeAlerts.push(alert)
+    }
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/** Creates a ProductionMetrics instance, validating required configuration */
+export function createProductionMetrics(config: ProductionMetricsConfig): ProductionMetrics {
+  if (!config.serviceName) {
+    throw new Error('ProductionMetrics requires a non-empty serviceName')
+  }
+  return new ProductionMetrics(config)
+}