@dotdo/postgres 0.1.0

package/dist/observability/memory-metrics.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Memory Metrics Collector
+ *
+ * Tracks WASM heap usage and memory pressure for Cloudflare Workers.
+ * Critical for monitoring within the 128MB Worker limit.
+ */
+import type { MetricsCollector } from './types';
+import { WORKER_MEMORY_LIMIT_BYTES, WASM_PAGE_SIZE_BYTES } from '../config/memory';
+/** @deprecated Import from '@dotdo/postgres/config/memory' instead */
+export { WORKER_MEMORY_LIMIT_BYTES, WASM_PAGE_SIZE_BYTES };
+/** Default warning threshold (70% of limit) */
+export declare const DEFAULT_WARNING_THRESHOLD = 0.7;
+/** Default critical threshold (90% of limit) */
+export declare const DEFAULT_CRITICAL_THRESHOLD = 0.9;
+export declare enum MemoryPressureLevel {
+    NORMAL = "normal",
+    WARNING = "warning",
+    CRITICAL = "critical"
+}
+export interface WasmHeapInfo {
+    size: number;
+    used: number;
+}
+export interface MemorySnapshot {
+    heapSizeBytes: number;
+    heapUsedBytes: number;
+    limitBytes: number;
+    usageRatio: number;
+    availableBytes: number;
+    pressureLevel: MemoryPressureLevel;
+    timestamp: number;
+    /** WASM memory pages (64KB each) */
+    wasmPages: number;
+    /** Utilization ratio of WASM heap (used/size) */
+    wasmUtilizationRatio: number;
+    /** Ratio against Worker memory limit (used/128MB) */
+    workerLimitRatio: number;
+    /** Bytes remaining before OOM (128MB - used) */
+    bytesUntilOOM: number;
+}
+export interface MemoryHistory {
+    snapshots: MemorySnapshot[];
+    avgUsageBytes: number;
+    peakUsageBytes: number;
+    trend: number;
+}
+export interface HeapGrowthRate {
+    bytesPerSecond: number;
+    percentageGrowth: number;
+    isGrowing: boolean;
+}
+export interface HeapAllocationHistogram {
+    buckets: {
+        min: number;
+        max: number;
+        count: number;
+    }[];
+    totalSamples: number;
+}
+export interface OOMPrediction {
+    estimatedMs: number;
+    confidence: number;
+    willOOM: boolean;
+}
+export interface MemoryVelocity {
+    bytesPerMs: number;
+    accelerating: boolean;
+}
+export interface MemoryForecast {
+    predictedBytes: number;
+    confidenceInterval: {
+        low: number;
+        high: number;
+    };
+}
+export interface LeakAnalysis {
+    possibleLeak: boolean;
+    growthPattern: 'monotonic' | 'sawtooth' | 'stable' | 'decreasing';
+    confidence: number;
+}
+export interface GrowthPatternAnalysis {
+    pattern: 'monotonic' | 'sawtooth' | 'stable' | 'decreasing';
+    healthStatus: 'normal' | 'concerning' | 'critical';
+}
+export interface PostgresSettingsRecommendation {
+    shared_buffers: string;
+    work_mem: string;
+    maintenance_work_mem: string;
+    temp_buffers: string;
+}
+export interface PostgresConfigAnalysis {
+    issues: string[];
+    recommendations: PostgresSettingsRecommendation;
+}
+export interface MemoryAlert {
+    type: 'memory_warning' | 'memory_critical' | 'memory_oom_predicted';
+    level: 'warning' | 'critical';
+    message: string;
+    snapshot: MemorySnapshot;
+}
+export interface AlertSummary {
+    totalAlerts: number;
+    byLevel: {
+        warning: number;
+        critical: number;
+    };
+    lastAlertTime: number | null;
+}
+export interface MemoryRecommendation {
+    action: 'none' | 'reduce_cache' | 'reduce_result_set' | 'force_gc' | 'restart_do';
+    reason: string;
+    pressureLevel: MemoryPressureLevel;
+    usageRatio: number;
+    /** Worker-specific recommendation */
+    workerSpecific: boolean;
+    /** Maximum safe result set size given current memory */
+    maxSafeResultSetBytes: number;
+    /** Suggested PostgreSQL settings */
+    suggestedPgSettings: PostgresSettingsRecommendation;
+}
+export interface MemoryBudget {
+    totalBytes: number;
+    staticBytes: number;
+    postgresOverheadBytes: number;
+    workMemBytes: number;
+    availableForQueriesBytes: number;
+    maxResultSetBytes: number;
+    /** Whether the budget exceeds the 128MB limit */
+    exceedsLimit: boolean;
+    /** Overage in bytes if exceeds limit */
+    overageBytes: number;
+}
+export interface MemoryMetricsConfig {
+    getWasmHeap?: () => WasmHeapInfo | null;
+    warningThreshold?: number;
+    criticalThreshold?: number;
+    memoryLimitBytes?: number;
+    onPressureChange?: (level: MemoryPressureLevel, snapshot: MemorySnapshot) => void;
+    onSustainedPressure?: (level: MemoryPressureLevel, durationMs: number) => void;
+    onAlert?: (alert: MemoryAlert) => void;
+    sustainedPressureThreshold?: number;
+    alertThresholds?: {
+        critical?: number;
+        oomPrediction?: number;
+    };
+    historySize?: number;
+    metricsCollector?: MetricsCollector;
+}
+export interface MemoryMetricsCollector {
+    getCurrentSnapshot(): MemorySnapshot;
+    record(): MemorySnapshot;
+    getHistory(): MemoryHistory;
+    getPeakUsage(): number;
+    getPressureLevel(): MemoryPressureLevel;
+    isWarning(): boolean;
+    isCritical(): boolean;
+    getRecommendation(): MemoryRecommendation;
+    reset(): void;
+    getHeapGrowthRate(): HeapGrowthRate;
+    getFragmentationRatio(): number;
+    getHeapAllocationHistogram(): HeapAllocationHistogram;
+    getPressureDuration(): Record<MemoryPressureLevel, number>;
+    getPressureScore(): number;
+    predictTimeToOOM(): OOMPrediction;
+    getMemoryVelocity(): MemoryVelocity;
+    forecastMemoryUsage(msAhead: number): MemoryForecast;
+    analyzeForLeaks(): LeakAnalysis;
+    analyzeGrowthPattern(): GrowthPatternAnalysis;
+    getPostgresSettingsRecommendation(): PostgresSettingsRecommendation;
+    analyzePostgresMemoryConfig(config: Record<string, string>): PostgresConfigAnalysis;
+    recordOperationMemory(operation: string, bytes: number): void;
+    getMemoryBreakdownByOperation(): Record<string, number>;
+    getAlertSummary(): AlertSummary;
+}
+export declare class MemoryMetricsCollectorImpl implements MemoryMetricsCollector {
+    private config;
+    private history;
+    private peakUsage;
+    private lastPressureLevel;
+    private pressureStartTimes;
+    private pressureDurations;
+    private consecutivePressureCount;
+    private sustainedPressureEmitted;
+    private operationMemory;
+    private alerts;
+    constructor(config?: MemoryMetricsConfig);
+    getCurrentSnapshot(): MemorySnapshot;
+    record(): MemorySnapshot;
+    getHistory(): MemoryHistory;
+    getPeakUsage(): number;
+    getPressureLevel(): MemoryPressureLevel;
+    isWarning(): boolean;
+    isCritical(): boolean;
+    getRecommendation(): MemoryRecommendation;
+    reset(): void;
+    getHeapGrowthRate(): HeapGrowthRate;
+    getFragmentationRatio(): number;
+    getHeapAllocationHistogram(): HeapAllocationHistogram;
+    getPressureDuration(): Record<MemoryPressureLevel, number>;
+    getPressureScore(): number;
+    predictTimeToOOM(): OOMPrediction;
+    getMemoryVelocity(): MemoryVelocity;
+    forecastMemoryUsage(msAhead: number): MemoryForecast;
+    analyzeForLeaks(): LeakAnalysis;
+    analyzeGrowthPattern(): GrowthPatternAnalysis;
+    getPostgresSettingsRecommendation(): PostgresSettingsRecommendation;
+    analyzePostgresMemoryConfig(config: Record<string, string>): PostgresConfigAnalysis;
+    recordOperationMemory(operation: string, bytes: number): void;
+    getMemoryBreakdownByOperation(): Record<string, number>;
+    getAlertSummary(): AlertSummary;
+}
+export declare function createMemoryMetricsCollector(config?: MemoryMetricsConfig): MemoryMetricsCollector;
+export declare function createPGLiteHeapGetter(getModule: () => {
+    HEAPU8?: Uint8Array;
+} | null): () => WasmHeapInfo | null;
+export declare function createEstimatedHeapGetter(): () => WasmHeapInfo;
+export interface MemoryBudgetOptions {
+    totalBytes?: number;
+    wasmBinaryBytes?: number;
+    dataFileBytes?: number;
+    jsRuntimeBytes?: number;
+    sharedBuffersBytes?: number;
+    workMemBytes?: number;
+    walBuffersBytes?: number;
+}
+export declare function calculateMemoryBudget(options?: MemoryBudgetOptions): MemoryBudget;
+//# sourceMappingURL=memory-metrics.d.ts.map

package/dist/observability/memory-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-metrics.d.ts","sourceRoot":"","sources":["../../src/observability/memory-metrics.ts"],"names":[],"mappings":"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"}