@dotdo/postgres 0.1.0 → 0.1.2

package/dist/observability/production-metrics.js

@@ -0,0 +1,747 @@
+/**
+ * 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];
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/** Extracts the SQL operation type (SELECT, INSERT, UPDATE, DELETE, OTHER) from a query string */
+function extractOperation(sql) {
+    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) {
+    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, p) {
+    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 {
+    config;
+    startTime;
+    // Query metrics state
+    queries = [];
+    slowQueries = [];
+    digestMap = new Map();
+    totalErrors = 0;
+    totalRowsReturned = 0;
+    // Connection state
+    connections = [];
+    totalConnectionsOpened = 0;
+    peakConnections = 0;
+    connectionErrors = 0;
+    connectionDurations = [];
+    waitTimes = [];
+    idleConnections = 0;
+    // Storage state
+    storageOps = [];
+    tierPromotions = { coldToWarm: 0, warmToHot: 0 };
+    tierDemotions = { hotToWarm: 0, warmToCold: 0 };
+    tierErrors = { hot: 0, warm: 0, cold: 0 };
+    tierUsage = { hot: 0, warm: 0, cold: 0 };
+    tierHealth = { hot: 'healthy', warm: 'healthy', cold: 'healthy' };
+    // Dependencies
+    pgliteInstance = null;
+    storageOrchestrator = null;
+    // Alert state
+    activeAlerts = [];
+    customThresholds = [];
+    constructor(config) {
+        this.config = config;
+        this.startTime = Date.now();
+    }
+    // ===========================================================================
+    // Query Metrics
+    // ===========================================================================
+    /** Records a completed query, updating metrics, digests, slow query log, and alerts */
+    recordQuery(record) {
+        const operation = extractOperation(record.sql);
+        const entry = {
+            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 */
+    trackSlowQuery(record) {
+        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 */
+    updateQueryDigest(record) {
+        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() {
+        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 */
+    getSortedDurationsSample(total) {
+        if (total > RESERVOIR_SAMPLING_THRESHOLD) {
+            const sample = [];
+            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 */
+    computeOperationBreakdown() {
+        const byOperation = {};
+        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() {
+        return [...this.slowQueries];
+    }
+    /** Returns all tracked query digest patterns */
+    getQueryDigests() {
+        return Array.from(this.digestMap.values());
+    }
+    /** Resets all query-related metrics, including digests and slow query log */
+    resetQueryMetrics() {
+        this.queries = [];
+        this.slowQueries = [];
+        this.digestMap.clear();
+        this.totalErrors = 0;
+        this.totalRowsReturned = 0;
+    }
+    // ===========================================================================
+    // Connection Stats
+    // ===========================================================================
+    /** Records a new connection being opened */
+    recordConnectionOpen(options) {
+        const conn = {
+            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) {
+        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) {
+        this.connectionErrors++;
+    }
+    /** Records a connection transitioning to idle state */
+    recordConnectionIdle() {
+        this.idleConnections++;
+    }
+    /** Records a connection being acquired from the pool, with wait time */
+    recordConnectionAcquired(options) {
+        this.waitTimes.push(options.waitTimeMs);
+    }
+    /** Returns a snapshot of connection statistics */
+    getConnectionStats() {
+        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, operation, options) {
+        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, to, _details) {
+        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, to, _details) {
+        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, _message) {
+        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, bytes) {
+        this.tierUsage[tier] = bytes;
+    }
+    /** Records a change in tier health status */
+    recordTierHealthChange(tier, status) {
+        this.tierHealth[tier] = status;
+    }
+    /** Returns a comprehensive snapshot of storage tier statistics including costs */
+    getStorageTierStats() {
+        const getTierStats = (tier) => {
+            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'),
+            };
+        };
+        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) {
+        this.pgliteInstance = pglite;
+    }
+    /** Sets the storage orchestrator for health check tier status */
+    setStorageOrchestrator(orchestrator) {
+        this.storageOrchestrator = orchestrator;
+    }
+    /** Returns a simple liveness probe result (always healthy if the service is running) */
+    liveness() {
+        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) {
+        const startTime = Date.now();
+        const checks = {};
+        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 */
+    async checkPGLiteHealth() {
+        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) => { settled = true; return v; }, (e) => { settled = true; throw e; });
+            const timeoutCheck = new Promise(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 */
+    checkStorageHealth() {
+        if (!this.storageOrchestrator) {
+            return { status: 'healthy', details: { message: 'No orchestrator configured' } };
+        }
+        const tierHealth = this.storageOrchestrator.getTierHealth();
+        const allHealthy = Object.values(tierHealth).every((t) => t.status === 'healthy');
+        const anyDegraded = Object.values(tierHealth).some((t) => t.status === 'degraded');
+        return {
+            status: allHealthy ? 'healthy' : (anyDegraded ? 'degraded' : 'unhealthy'),
+            details: tierHealth,
+        };
+    }
+    /** Determines the worst overall status from all component checks */
+    determineOverallStatus(checks) {
+        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() {
+        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() {
+        const lines = [];
+        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']) {
+            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() {
+        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() {
+        return async (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() {
+        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() {
+        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() {
+        return [...this.activeAlerts];
+    }
+    /** Registers a custom alert threshold for evaluation */
+    registerAlertThreshold(threshold) {
+        this.customThresholds.push(threshold);
+    }
+    // ===========================================================================
+    // Reset
+    // ===========================================================================
+    /** Resets all metrics state (queries, connections, storage, alerts) */
+    resetAll() {
+        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
+    // ===========================================================================
+    getWindowMetrics(sinceTimestamp) {
+        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,
+        };
+    }
+    addAlert(alert) {
+        // 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) {
+    if (!config.serviceName) {
+        throw new Error('ProductionMetrics requires a non-empty serviceName');
+    }
+    return new ProductionMetrics(config);
+}
+//# sourceMappingURL=production-metrics.js.map