@dotdo/postgres 0.1.0

package/dist/observability/index.js

@@ -0,0 +1,455 @@
+/**
+ * @module @dotdo/postgres/observability
+ *
+ * Observability Module for postgres.do
+ *
+ * A comprehensive, OpenTelemetry-compatible observability solution for PostgreSQL
+ * operations in Cloudflare Workers. Provides unified tracing, metrics, alerting,
+ * health checks, and cost tracking designed specifically for the 128MB Worker limit.
+ *
+ * ## Key Features
+ *
+ * - **Tracing**: W3C Trace Context compliant distributed tracing
+ * - **Metrics**: Counter, gauge, and histogram metrics with Prometheus export
+ * - **Health Checks**: Kubernetes-style liveness and readiness probes
+ * - **Alerting**: Threshold-based alerting with webhook integration
+ * - **Memory Tracking**: WASM heap monitoring for Workers memory limits
+ * - **Storage Tiers**: Hot/Warm/Cold tier metrics for tiered storage
+ * - **Cost Tracking**: Cloudflare pricing-aware cost estimation
+ * - **Cross-DO Tracing**: Distributed tracing across Durable Object calls
+ *
+ * ## Quick Start
+ *
+ * @example Basic Setup with createObservability (Recommended)
+ * ```typescript
+ * import { createObservability } from '@dotdo/postgres/observability'
+ *
+ * // Create a complete observability toolkit with one call
+ * const obs = createObservability({
+ *   serviceName: 'postgres-do',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ * })
+ *
+ * // Use query instrumentation
+ * const result = await obs.query(
+ *   { sql: 'SELECT * FROM users WHERE id = $1', params: [1] },
+ *   async (sql, params) => pglite.query(sql, params)
+ * )
+ *
+ * // Track cache operations
+ * const { value, hit } = await obs.cache.get('user:123', 'cache', async () => {
+ *   return cache.get('user:123')
+ * })
+ *
+ * // Track Durable Object lifecycle
+ * await obs.do.trackActivation({ id: doId.toString() }, async () => {
+ *   await this.initializePGLite()
+ * })
+ *
+ * // Get metrics snapshot
+ * const metrics = obs.metrics.getMetrics()
+ * ```
+ *
+ * @example Advanced Setup with Individual Components
+ * ```typescript
+ * import {
+ *   createTracer,
+ *   createMetricsCollector,
+ *   createConsoleExporter,
+ *   createQueryInstrumentation,
+ *   createHealthCheckManager,
+ *   createPGLiteChecker,
+ *   createMemoryChecker,
+ *   createAlertManager,
+ *   DEFAULT_ALERT_RULES,
+ * } from '@dotdo/postgres/observability'
+ *
+ * // Create tracer with console exporter
+ * const exporter = createConsoleExporter({ prettyPrint: true })
+ * const tracer = createTracer({
+ *   serviceName: 'postgres-do',
+ *   serviceVersion: '1.0.0',
+ * }, exporter)
+ *
+ * // Create metrics collector
+ * const metrics = createMetricsCollector()
+ *
+ * // Set up health checks
+ * const healthManager = createHealthCheckManager({
+ *   serviceName: 'postgres-do',
+ *   checkers: {
+ *     pglite: createPGLiteChecker(() => this.pglite),
+ *     memory: createMemoryChecker({
+ *       warningThreshold: 0.7,
+ *       criticalThreshold: 0.9,
+ *       getMemoryUsage: () => this.getHeapUsage(),
+ *       memoryLimitBytes: 128 * 1024 * 1024,
+ *     }),
+ *   },
+ *   metricsCollector: metrics,
+ * })
+ *
+ * // Set up alerting with default rules
+ * const alertManager = createAlertManager({
+ *   metricsCollector: metrics,
+ *   rules: DEFAULT_ALERT_RULES,
+ * })
+ * alertManager.start()
+ * ```
+ *
+ * @example Distributed Tracing Across Durable Objects
+ * ```typescript
+ * import {
+ *   extractSpanContext,
+ *   injectSpanContext,
+ *   createDORpcTracer,
+ *   createDORpcHandler,
+ * } from '@dotdo/postgres/observability'
+ *
+ * // In your Worker fetch handler
+ * async fetch(request: Request) {
+ *   const parentContext = extractSpanContext(request.headers)
+ *
+ *   // Call another DO with trace context
+ *   const rpcTracer = createDORpcTracer(tracer, parentContext, doId, 'PostgresDO')
+ *   const result = await rpcTracer.trace('rpcQuery', async (traceContext) => {
+ *     return stub.rpcQuery(sql, params, traceContext)
+ *   })
+ *
+ *   // Inject trace context into response
+ *   const response = new Response(JSON.stringify(result))
+ *   injectSpanContext(span.getContext(), response.headers)
+ *   return response
+ * }
+ *
+ * // In the target DO's RPC method
+ * async rpcQuery(sql: string, params?: unknown[], traceContext?: string) {
+ *   const rpcHandler = createDORpcHandler(tracer, this.id, 'PostgresDO')
+ *   return rpcHandler.handle('rpcQuery', traceContext, { sql }, async (span) => {
+ *     return this.executeQuery(sql, params)
+ *   })
+ * }
+ * ```
+ *
+ * @example HTTP Endpoints for Metrics and Health
+ * ```typescript
+ * import {
+ *   createMetricsEndpoint,
+ *   createHealthHandler,
+ * } from '@dotdo/postgres/observability'
+ *
+ * const metricsHandler = createMetricsEndpoint(metrics, {
+ *   path: '/metrics',
+ *   defaultFormat: 'prometheus',
+ *   enableCors: true,
+ * })
+ *
+ * const healthHandler = createHealthHandler(healthManager, {
+ *   basePath: '/health',
+ * })
+ *
+ * export default {
+ *   async fetch(request: Request) {
+ *     // Try metrics endpoint (supports content negotiation)
+ *     const metricsResponse = await metricsHandler(request)
+ *     if (metricsResponse) return metricsResponse
+ *
+ *     // Try health endpoints (/health/live, /health/ready)
+ *     const healthResponse = await healthHandler(request)
+ *     if (healthResponse) return healthResponse
+ *
+ *     // ... handle other routes
+ *   }
+ * }
+ * ```
+ *
+ * @example Cost Tracking for Cloudflare Resources
+ * ```typescript
+ * import { createCostMetricsCollector } from '@dotdo/postgres/observability'
+ *
+ * const costCollector = createCostMetricsCollector()
+ *
+ * // Track DO storage operations
+ * costCollector.trackDOOperation('write', 1, 1024) // 1 write, 1KB
+ * costCollector.trackDOOperation('read', 10) // 10 reads
+ *
+ * // Track R2 operations
+ * costCollector.trackR2Operation('put', 1, 5 * 1024 * 1024) // 1 PUT, 5MB
+ * costCollector.trackR2Operation('get', 100) // 100 GETs
+ *
+ * // Track cache usage
+ * costCollector.trackCacheOperation('get', true) // cache hit
+ * costCollector.trackCacheOperation('get', false) // cache miss
+ *
+ * // Get cost breakdown
+ * const costs = costCollector.getCostBreakdown()
+ * console.log(`Total estimated cost: $${costs.totalCost.toFixed(4)}`)
+ * console.log(`Cache saved: $${costs.cache.savedCost.toFixed(4)}`)
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { SpanStatusCode, SpanKind } from './types';
+// ============================================================================
+// Tracer
+// ============================================================================
+export { 
+// Tracer creation
+createTracer, createNoOpTracer, TracerImpl, NoOpTracer, 
+// Sampled tracer with integrated sampling
+createSampledTracer, SampledTracer, 
+// ID generation
+generateTraceId, generateSpanId, createSpanContext, } from './tracer';
+// ============================================================================
+// Metrics
+// ============================================================================
+export { 
+// Metrics collector creation
+createMetricsCollector, createNoOpMetricsCollector, MetricsCollectorImpl, NoOpMetricsCollector, 
+// Pre-defined metric names
+MetricNames, } from './metrics';
+// ============================================================================
+// Propagation
+// ============================================================================
+export { 
+// Header names
+TRACEPARENT_HEADER, TRACESTATE_HEADER, 
+// Flags
+SAMPLED_FLAG, 
+// Parsing functions
+parseTraceparent, formatTraceparent, parseTracestate, formatTracestate, 
+// Context extraction/injection
+extractSpanContext, injectSpanContext, 
+// Context creation
+createChildContext, createRootContext, isSampled, 
+// Propagator
+W3CTraceContextPropagator, createPropagator, } from './propagation';
+// ============================================================================
+// Exporters
+// ============================================================================
+export { 
+// Console exporter
+ConsoleExporter, createConsoleExporter, 
+// Structured exporter
+StructuredExporter, createStructuredExporter, 
+// Batch exporter
+BatchExporter, createBatchExporter, 
+// Multi-exporter
+MultiExporter, createMultiExporter, 
+// No-op exporter
+NoOpExporter, createNoOpExporter, 
+// Resilient exporter with circuit breaker
+ResilientExporter, createResilientExporter, } from './exporters';
+// ============================================================================
+// Instrumentation
+// ============================================================================
+export { 
+// Query instrumentation
+createQueryInstrumentation, 
+// Cache instrumentation
+createCacheInstrumentation, 
+// DO instrumentation
+createDOInstrumentation, 
+// Error instrumentation
+createErrorInstrumentation, 
+// Request instrumentation
+createRequestInstrumentation, } from './instrumentation';
+import { createTracer, createNoOpTracer } from './tracer';
+import { createMetricsCollector, createNoOpMetricsCollector } from './metrics';
+import { createStructuredExporter, createNoOpExporter } from './exporters';
+import { createQueryInstrumentation, createCacheInstrumentation, createDOInstrumentation, createErrorInstrumentation, } from './instrumentation';
+/**
+ * Create a complete observability toolkit
+ *
+ * This is the recommended way to set up observability for the postgres package.
+ *
+ * @example
+ * ```typescript
+ * const obs = createObservability({
+ *   serviceName: 'postgres-do',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ * })
+ *
+ * // Use query instrumentation
+ * const result = await obs.query(
+ *   { sql: 'SELECT * FROM users' },
+ *   async (sql) => pglite.query(sql)
+ * )
+ *
+ * // Track cache operations
+ * const cached = await obs.cache.get('page-123', 'cache', async () => {
+ *   return cacheLayer.get('page-123')
+ * })
+ *
+ * // Track DO lifecycle
+ * await obs.do.trackActivation({ id: doId.toString() }, async () => {
+ *   await this.initPGlite()
+ * })
+ *
+ * // Get metrics snapshot
+ * const metrics = obs.metrics.getMetrics()
+ * ```
+ */
+export function createObservability(config) {
+    const enabled = config.enabled ?? true;
+    // Create tracer and metrics
+    const exporter = enabled
+        ? config.exporter ?? createStructuredExporter()
+        : createNoOpExporter();
+    const tracer = enabled
+        ? createTracer(config, exporter)
+        : createNoOpTracer();
+    const metrics = enabled
+        ? createMetricsCollector(config.histogramBoundaries)
+        : createNoOpMetricsCollector();
+    // Create instrumentation helpers
+    const query = createQueryInstrumentation(tracer, metrics);
+    const cache = createCacheInstrumentation(tracer, metrics);
+    const doInst = createDOInstrumentation(tracer, metrics);
+    const error = createErrorInstrumentation(tracer, metrics);
+    return {
+        tracer,
+        metrics,
+        query,
+        cache,
+        do: doInst,
+        error,
+    };
+}
+// ============================================================================
+// Cross-DO Distributed Tracing
+// ============================================================================
+export { serializeTraceContext, deserializeTraceContext, extractDORpcContext, serializeBaggage, parseBaggage, BAGGAGE_HEADER, createDORpcTracer, createDORpcHandler, injectTraceIntoRequest, extractTraceFromRequest, createCrossDoChildContext, createTracedDOStubProxy, } from './cross-do-tracing';
+// ============================================================================
+// Health Check System
+// ============================================================================
+export { 
+// Health check manager
+HealthStatus, createHealthCheckManager, HealthCheckManagerImpl, 
+// Built-in health checkers
+createPGLiteChecker, createMemoryChecker, createStorageTierChecker, 
+// HTTP handler
+createHealthHandler, } from './health-check';
+// ============================================================================
+// Query Performance Tracking
+// ============================================================================
+export { 
+// Query performance tracker
+createQueryPerformanceTracker, QueryPerformanceTrackerImpl, 
+// SQL utilities
+normalizeSQL, detectOperation, 
+// Tracked query executor
+createTrackedQueryExecutor, } from './query-performance';
+// ============================================================================
+// Error Rate Collector
+// ============================================================================
+export { 
+// Error rate collector
+createErrorRateCollector, ErrorRateCollectorImpl, } from './error-rate-collector';
+// ============================================================================
+// Memory Metrics Collector
+// ============================================================================
+export { 
+// Constants
+WORKER_MEMORY_LIMIT_BYTES, DEFAULT_WARNING_THRESHOLD, DEFAULT_CRITICAL_THRESHOLD, 
+// Enums
+MemoryPressureLevel, 
+// Memory metrics collector
+createMemoryMetricsCollector, MemoryMetricsCollectorImpl, 
+// Heap getters
+createPGLiteHeapGetter, createEstimatedHeapGetter, 
+// Memory budget calculator
+calculateMemoryBudget, } from './memory-metrics';
+// ============================================================================
+// Storage Tier Metrics
+// ============================================================================
+export { 
+// Storage tier metrics collector
+createStorageTierMetricsCollector, StorageTierMetricsCollectorImpl, } from './storage-tier-metrics';
+// ============================================================================
+// Alerting System
+// ============================================================================
+export { 
+// Enums
+AlertSeverity, AlertState, 
+// Alert manager
+createAlertManager, AlertManagerImpl, 
+// Built-in handlers
+createConsoleAlertHandler, createWebhookAlertHandler, createMetricsAlertHandler, 
+// Default rules
+DEFAULT_ALERT_RULES, } from './alerting';
+// ============================================================================
+// Prometheus Exporter
+// ============================================================================
+export { 
+// Prometheus exporter
+createPrometheusExporter, PrometheusExporterImpl, 
+// Default metadata
+DEFAULT_METRIC_META, 
+// Legacy HTTP handler (prometheus-only)
+createMetricsHandler as createPrometheusMetricsHandler, } from './prometheus';
+// ============================================================================
+// Metrics Endpoint (with content negotiation)
+// ============================================================================
+export { 
+// Metrics endpoint handler
+createMetricsEndpoint, createMetricsHandler, 
+// Content negotiation
+negotiateFormat, 
+// JSON export
+exportMetricsToJson, } from './metrics-endpoint';
+// ============================================================================
+// Query Latency Metrics
+// ============================================================================
+export { 
+// Query latency tracker
+createQueryLatencyTracker, QueryLatencyTrackerImpl, } from './query-latency';
+// ============================================================================
+// Cost Metrics Collector
+// ============================================================================
+export { 
+// Cloudflare pricing constants
+CloudflarePricing, 
+// Cost metrics collector
+createCostMetricsCollector, CostMetricsCollectorImpl, 
+// No-op collector
+createNoOpCostMetricsCollector, NoOpCostMetricsCollector, 
+// Pre-defined metric names
+CostMetricNames, } from './cost-metrics';
+// ============================================================================
+// Production Observability Features
+// ============================================================================
+export { 
+// Log Aggregation
+createLogAggregator, LogAggregatorImpl, 
+// OTLP Span Exporter
+createOTLPSpanExporter, OTLPSpanExporterImpl, 
+// Span Sampling Strategies
+createProbabilitySampler, createRateLimitingSampler, createAdaptiveSampler, ProbabilitySampler, RateLimitingSampler, AdaptiveSampler, 
+// Compound Alert Rules
+createCompoundAlertManager, CompoundAlertManagerImpl, 
+// Distributed Metrics Aggregation
+createDistributedMetricsAggregator, DistributedMetricsAggregatorImpl, 
+// Observability Overhead Metrics
+createObservabilityOverheadCollector, ObservabilityOverheadCollectorImpl, } from './observability-features';
+// ============================================================================
+// Cloudflare Analytics Engine Integration
+// ============================================================================
+export { 
+// Span exporter
+createAnalyticsEngineExporter, AnalyticsEngineSpanExporterImpl, 
+// Metrics exporter
+createAnalyticsEngineMetricsExporter, AnalyticsEngineMetricsExporterImpl, 
+// DO lifecycle writer
+createDOLifecycleWriter, DOLifecycleWriterImpl, 
+// No-op implementations
+createNoOpAnalyticsEngineExporter, NoOpAnalyticsEngineExporter, createNoOpDOLifecycleWriter, NoOpDOLifecycleWriter, } from './analytics-engine';
+// ============================================================================
+// Tier Cost Optimizer
+// ============================================================================
+export { 
+// Tier cost optimizer
+createTierCostOptimizer, TierCostOptimizerImpl, } from './tier-cost-optimizer';
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+LG;AAiCH,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAElD,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO;AACL,kBAAkB;AAClB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,UAAU;AACV,0CAA0C;AAC1C,mBAAmB,EACnB,aAAa;AACb,gBAAgB;AAChB,eAAe,EACf,cAAc,EACd,iBAAiB,GAClB,MAAM,UAAU,CAAA;AAIjB,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,OAAO;AACL,6BAA6B;AAC7B,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB;AACpB,2BAA2B;AAC3B,WAAW,GACZ,MAAM,WAAW,CAAA;AAIlB,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E,OAAO;AACL,eAAe;AACf,kBAAkB,EAClB,iBAAiB;AACjB,QAAQ;AACR,YAAY;AACZ,oBAAoB;AACpB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB;AAChB,+BAA+B;AAC/B,kBAAkB,EAClB,iBAAiB;AACjB,mBAAmB;AACnB,kBAAkB,EAClB,iBAAiB,EACjB,SAAS;AACT,aAAa;AACb,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,eAAe,CAAA;AAItB,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,OAAO;AACL,mBAAmB;AACnB,eAAe,EACf,qBAAqB;AACrB,sBAAsB;AACtB,kBAAkB,EAClB,wBAAwB;AACxB,iBAAiB;AACjB,aAAa,EACb,mBAAmB;AACnB,iBAAiB;AACjB,aAAa,EACb,mBAAmB;AACnB,iBAAiB;AACjB,YAAY,EACZ,kBAAkB;AAClB,0CAA0C;AAC1C,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,aAAa,CAAA;AASpB,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E,OAAO;AACL,wBAAwB;AACxB,0BAA0B;AAC1B,wBAAwB;AACxB,0BAA0B;AAC1B,qBAAqB;AACrB,uBAAuB;AACvB,wBAAwB;AACxB,0BAA0B;AAC1B,0BAA0B;AAC1B,4BAA4B,GAC7B,MAAM,mBAAmB,CAAA;AAsB1B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAA;AAC9E,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAC1E,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAA;AAgC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA2B;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAA;IAEtC,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,OAAO;QACtB,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,wBAAwB,EAAE;QAC/C,CAAC,CAAC,kBAAkB,EAAE,CAAA;IAExB,MAAM,MAAM,GAAG,OAAO;QACpB,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC;QAChC,CAAC,CAAC,gBAAgB,EAAE,CAAA;IAEtB,MAAM,OAAO,GAAG,OAAO;QACrB,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,mBAAmB,CAAC;QACpD,CAAC,CAAC,0BAA0B,EAAE,CAAA;IAEhC,iCAAiC;IACjC,MAAM,KAAK,GAAG,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvD,MAAM,KAAK,GAAG,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEzD,OAAO;QACL,MAAM;QACN,OAAO;QACP,KAAK;QACL,KAAK;QACL,EAAE,EAAE,MAAM;QACV,KAAK;KACN,CAAA;AACH,CAAC;AAED,+EAA+E;AAC/E,+BAA+B;AAC/B,+EAA+E;AAE/E,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA;AAW3B,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO;AACL,uBAAuB;AACvB,YAAY,EACZ,wBAAwB,EACxB,sBAAsB;AACtB,2BAA2B;AAC3B,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB;AACxB,eAAe;AACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AAWvB,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E,OAAO;AACL,4BAA4B;AAC5B,6BAA6B,EAC7B,2BAA2B;AAC3B,gBAAgB;AAChB,YAAY,EACZ,eAAe;AACf,yBAAyB;AACzB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAY5B,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,OAAO;AACL,uBAAuB;AACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,wBAAwB,CAAA;AA4B/B,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E,OAAO;AACL,YAAY;AACZ,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B;AAC1B,QAAQ;AACR,mBAAmB;AACnB,2BAA2B;AAC3B,4BAA4B,EAC5B,0BAA0B;AAC1B,eAAe;AACf,sBAAsB,EACtB,yBAAyB;AACzB,2BAA2B;AAC3B,qBAAqB,GACtB,MAAM,kBAAkB,CAAA;AAazB,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,OAAO;AACL,iCAAiC;AACjC,iCAAiC,EACjC,+BAA+B,GAChC,MAAM,wBAAwB,CAAA;AAe/B,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E,OAAO;AACL,QAAQ;AACR,aAAa,EACb,UAAU;AACV,gBAAgB;AAChB,kBAAkB,EAClB,gBAAgB;AAChB,oBAAoB;AACpB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB;AACzB,gBAAgB;AAChB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAanB,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO;AACL,sBAAsB;AACtB,wBAAwB,EACxB,sBAAsB;AACtB,mBAAmB;AACnB,mBAAmB;AACnB,wCAAwC;AACxC,oBAAoB,IAAI,8BAA8B,GACvD,MAAM,cAAc,CAAA;AASrB,+EAA+E;AAC/E,8CAA8C;AAC9C,+EAA+E;AAE/E,OAAO;AACL,2BAA2B;AAC3B,qBAAqB,EACrB,oBAAoB;AACpB,sBAAsB;AACtB,eAAe;AACf,cAAc;AACd,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAS3B,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,OAAO;AACL,wBAAwB;AACxB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,iBAAiB,CAAA;AAkBxB,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E,OAAO;AACL,+BAA+B;AAC/B,iBAAiB;AACjB,yBAAyB;AACzB,0BAA0B,EAC1B,wBAAwB;AACxB,kBAAkB;AAClB,8BAA8B,EAC9B,wBAAwB;AACxB,2BAA2B;AAC3B,eAAe,GAChB,MAAM,gBAAgB,CAAA;AAiBvB,+EAA+E;AAC/E,oCAAoC;AACpC,+EAA+E;AAE/E,OAAO;AACL,kBAAkB;AAClB,mBAAmB,EACnB,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB,EACtB,oBAAoB;AACpB,2BAA2B;AAC3B,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe;AACf,uBAAuB;AACvB,0BAA0B,EAC1B,wBAAwB;AACxB,kCAAkC;AAClC,kCAAkC,EAClC,gCAAgC;AAChC,iCAAiC;AACjC,oCAAoC,EACpC,kCAAkC,GACnC,MAAM,0BAA0B,CAAA;AAkCjC,+EAA+E;AAC/E,0CAA0C;AAC1C,+EAA+E;AAE/E,OAAO;AACL,gBAAgB;AAChB,6BAA6B,EAC7B,+BAA+B;AAC/B,mBAAmB;AACnB,oCAAoC,EACpC,kCAAkC;AAClC,sBAAsB;AACtB,uBAAuB,EACvB,qBAAqB;AACrB,wBAAwB;AACxB,iCAAiC,EACjC,2BAA2B,EAC3B,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,oBAAoB,CAAA;AAmB3B,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO;AACL,sBAAsB;AACtB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,uBAAuB,CAAA"}

package/dist/observability/instrumentation.d.ts

@@ -0,0 +1,222 @@
+/**
+ * PostgreSQL Instrumentation
+ *
+ * Provides instrumented wrappers for PostgreSQL operations in Cloudflare Workers.
+ * Implements tracing for queries, cache operations, DO lifecycle, and errors.
+ */
+import type { Tracer, SpanContext, MetricsCollector } from './types';
+export type { ActiveSpan } from './types';
+export { createChildContext } from './propagation';
+/**
+ * Query execution options for instrumentation
+ */
+export interface QueryOptions {
+    /** The SQL statement */
+    sql: string;
+    /** Query parameters */
+    params?: unknown[];
+    /** Database name */
+    database?: string;
+    /** Whether result is from cache */
+    cached?: boolean;
+    /** Parent span context */
+    parentContext?: SpanContext;
+}
+/**
+ * Query result for instrumentation
+ */
+export interface QueryResult<T = unknown> {
+    /** Result rows */
+    rows: T[];
+    /** Number of rows returned */
+    rowCount: number;
+    /** Number of rows affected (for mutations) */
+    affectedRows?: number;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Instrumented query executor
+ *
+ * Wraps a query execution function with tracing and metrics.
+ *
+ * @example
+ * ```typescript
+ * const instrumentedQuery = createQueryInstrumentation(tracer, metrics)
+ *
+ * const result = await instrumentedQuery(
+ *   { sql: 'SELECT * FROM users WHERE id = $1', params: [1] },
+ *   async (sql, params) => pglite.query(sql, params)
+ * )
+ * ```
+ */
+export declare function createQueryInstrumentation(tracer: Tracer, metrics: MetricsCollector): <T>(options: QueryOptions, executor: (sql: string, params?: unknown[]) => Promise<QueryResult<T>>) => Promise<QueryResult<T>>;
+/**
+ * Cache operation type
+ */
+export type CacheOperation = 'get' | 'put' | 'delete' | 'has';
+/**
+ * Cache tier
+ */
+export type CacheTier = 'cache' | 'do' | 'r2';
+/**
+ * Cache operation result
+ */
+export interface CacheOperationResult {
+    /** Whether the operation was a hit (for get/has) */
+    hit?: boolean;
+    /** Bytes read or written */
+    bytes?: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Instrumented cache operations
+ *
+ * Wraps cache operations with tracing and metrics.
+ *
+ * @example
+ * ```typescript
+ * const instrumentedCache = createCacheInstrumentation(tracer, metrics)
+ *
+ * const data = await instrumentedCache.get('page-123', 'cache', async () => {
+ *   return cacheLayer.get('page-123')
+ * })
+ * ```
+ */
+export declare function createCacheInstrumentation(tracer: Tracer, metrics: MetricsCollector): {
+    get<T>(key: string, tier: CacheTier, executor: () => Promise<T | null>, parentContext?: SpanContext): Promise<{
+        value: T | null;
+        hit: boolean;
+        durationMs: number;
+    }>;
+    put(key: string, tier: CacheTier, bytes: number, executor: () => Promise<void>, parentContext?: SpanContext): Promise<{
+        durationMs: number;
+    }>;
+    delete(key: string, tier: CacheTier, executor: () => Promise<boolean>, parentContext?: SpanContext): Promise<{
+        deleted: boolean;
+        durationMs: number;
+    }>;
+};
+/**
+ * DO lifecycle operation
+ */
+export type DOOperation = 'activation' | 'hibernation' | 'fetch' | 'alarm';
+/**
+ * DO lifecycle options
+ */
+export interface DOLifecycleOptions {
+    /** DO ID */
+    id: string;
+    /** DO name (optional) */
+    name?: string;
+    /** Storage used in bytes (optional) */
+    storageUsed?: number;
+    /** Parent span context */
+    parentContext?: SpanContext;
+}
+/**
+ * Instrumented Durable Object lifecycle tracking
+ *
+ * @example
+ * ```typescript
+ * const doInstrumentation = createDOInstrumentation(tracer, metrics)
+ *
+ * await doInstrumentation.trackActivation({ id: doId.toString() }, async () => {
+ *   await this.initPGlite()
+ * })
+ * ```
+ */
+export declare function createDOInstrumentation(tracer: Tracer, metrics: MetricsCollector): {
+    /**
+     * Track DO activation
+     */
+    trackActivation<T>(options: DOLifecycleOptions, executor: () => Promise<T>): Promise<T>;
+    /**
+     * Track DO hibernation
+     */
+    trackHibernation<T>(options: DOLifecycleOptions, executor: () => Promise<T>): Promise<T>;
+    /**
+     * Track DO fetch request
+     */
+    trackFetch<T>(options: DOLifecycleOptions, executor: () => Promise<T>): Promise<T>;
+    /**
+     * Track DO alarm
+     */
+    trackAlarm<T>(options: DOLifecycleOptions, executor: () => Promise<T>): Promise<T>;
+    /**
+     * Update storage usage gauge
+     */
+    updateStorageUsage(bytes: number): void;
+};
+/**
+ * Error category for classification
+ */
+export type ErrorCategory = 'query' | 'connection' | 'cache' | 'storage' | 'timeout' | 'validation' | 'unknown';
+/**
+ * Error tracking options
+ */
+export interface ErrorTrackingOptions {
+    /** Error category */
+    category: ErrorCategory;
+    /** Whether the error is recoverable */
+    recoverable?: boolean;
+    /** Error code (e.g., SQL error code) */
+    code?: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+    /** Parent span context */
+    parentContext?: SpanContext;
+}
+/**
+ * Instrumented error tracking
+ *
+ * @example
+ * ```typescript
+ * const errorTracker = createErrorInstrumentation(tracer, metrics)
+ *
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   errorTracker.recordError(error, { category: 'query' })
+ *   throw error
+ * }
+ * ```
+ */
+export declare function createErrorInstrumentation(tracer: Tracer, metrics: MetricsCollector): {
+    /**
+     * Record an error with tracing and metrics
+     */
+    recordError(error: Error | string, options: ErrorTrackingOptions): void;
+    /**
+     * Wrap an async function with error tracking
+     */
+    withErrorTracking<T>(category: ErrorCategory, executor: () => Promise<T>, parentContext?: SpanContext): Promise<T>;
+};
+/**
+ * Options for request instrumentation
+ */
+export interface RequestInstrumentationOptions {
+    /** Service name */
+    serviceName: string;
+    /** Extract user-defined attributes from request */
+    extractAttributes?: (request: Request) => Record<string, string>;
+}
+/**
+ * Create an instrumented fetch handler wrapper
+ *
+ * @example
+ * ```typescript
+ * const instrumentedFetch = createRequestInstrumentation(tracer, metrics, {
+ *   serviceName: 'postgres-do',
+ * })
+ *
+ * export default {
+ *   fetch: instrumentedFetch(async (request, env, ctx) => {
+ *     // Your handler logic
+ *   }),
+ * }
+ * ```
+ */
+export declare function createRequestInstrumentation(tracer: Tracer, metrics: MetricsCollector, options: RequestInstrumentationOptions): <Env>(handler: (request: Request, env: Env, ctx: ExecutionContext) => Promise<Response>) => (request: Request, env: Env, ctx: ExecutionContext) => Promise<Response>;
+//# sourceMappingURL=instrumentation.d.ts.map