@dotdo/postgres 0.1.0

package/dist/observability/cross-do-tracing.js

@@ -0,0 +1,431 @@
+/**
+ * Cross-DO Distributed Tracing
+ *
+ * Provides utilities for propagating trace context across Durable Object calls,
+ * enabling distributed tracing for cross-DO operations using OpenTelemetry-compatible
+ * W3C Trace Context headers.
+ *
+ * ## Overview
+ *
+ * When one Durable Object calls another (via RPC or fetch), trace context needs
+ * to be propagated to maintain a complete trace. This module provides:
+ *
+ * 1. Context propagation for RPC calls between DOs
+ * 2. Automatic span creation for cross-DO operations
+ * 3. Baggage support for passing metadata across boundaries
+ *
+ * ## Usage
+ *
+ * ### Propagating context in RPC calls
+ *
+ * ```typescript
+ * import { TracedDOStub, createTracedDOStub } from '@dotdo/postgres/observability'
+ *
+ * // In your Worker or DO
+ * const stub = env.POSTGRES_DO.get(id)
+ * const tracedStub = createTracedDOStub(stub, tracer, currentSpan.getContext())
+ *
+ * // Calls are automatically traced
+ * const result = await tracedStub.rpcQuery('SELECT * FROM users')
+ * ```
+ *
+ * ### Extracting context in the target DO
+ *
+ * ```typescript
+ * import { extractDORpcContext } from '@dotdo/postgres/observability'
+ *
+ * // In your DO's RPC method
+ * async rpcQuery(sql: string, params?: unknown[], traceContext?: string) {
+ *   const parentContext = extractDORpcContext(traceContext)
+ *   return this.tracer.startActiveSpan('postgres.query', { parent: parentContext }, async (span) => {
+ *     // ... execute query
+ *   })
+ * }
+ * ```
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+import { SpanKind, SpanStatusCode } from './types';
+import { extractSpanContext, injectSpanContext, createChildContext, formatTraceparent, parseTraceparent, } from './propagation';
+/**
+ * Baggage header for passing metadata across service boundaries
+ * @see https://www.w3.org/TR/baggage/
+ */
+export const BAGGAGE_HEADER = 'baggage';
+/**
+ * Serialize a span context for RPC propagation
+ *
+ * Converts a SpanContext into a JSON-serializable format that can be
+ * passed as a parameter in RPC calls between Durable Objects.
+ *
+ * @param context - The span context to serialize
+ * @param baggage - Optional baggage to include
+ * @returns Serialized trace context
+ *
+ * @example
+ * ```typescript
+ * const serialized = serializeTraceContext(span.getContext())
+ * await otherDO.rpcMethod(data, serialized)
+ * ```
+ */
+export function serializeTraceContext(context, baggage) {
+    const serialized = {
+        traceparent: formatTraceparent(context),
+    };
+    if (context.traceState) {
+        serialized.tracestate = context.traceState;
+    }
+    if (baggage && baggage.size > 0) {
+        serialized.baggage = serializeBaggage(baggage);
+    }
+    return serialized;
+}
+/**
+ * Deserialize trace context from RPC parameter
+ *
+ * Parses a serialized trace context back into a SpanContext that can
+ * be used as a parent for child spans.
+ *
+ * @param serialized - The serialized trace context
+ * @returns Span context or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const parentContext = deserializeTraceContext(traceContext)
+ * if (parentContext) {
+ *   // Create child span with this parent
+ * }
+ * ```
+ */
+export function deserializeTraceContext(serialized) {
+    if (!serialized) {
+        return null;
+    }
+    // Handle string input (JSON)
+    if (typeof serialized === 'string') {
+        try {
+            const parsed = JSON.parse(serialized);
+            return deserializeTraceContext(parsed);
+        }
+        catch {
+            // Try parsing as traceparent directly
+            return parseTraceparent(serialized);
+        }
+    }
+    const context = parseTraceparent(serialized.traceparent);
+    if (context && serialized.tracestate) {
+        context.traceState = serialized.tracestate;
+    }
+    return context;
+}
+/**
+ * Serialize baggage to header format
+ *
+ * @see https://www.w3.org/TR/baggage/
+ */
+export function serializeBaggage(baggage) {
+    const entries = [];
+    for (const [key, item] of baggage.entries()) {
+        // Encode the value (URL-safe encoding for special characters)
+        const encodedValue = encodeURIComponent(item.value);
+        let entry = `${key}=${encodedValue}`;
+        // Add metadata properties
+        if (item.metadata) {
+            for (const [metaKey, metaValue] of Object.entries(item.metadata)) {
+                entry += `;${metaKey}=${encodeURIComponent(metaValue)}`;
+            }
+        }
+        entries.push(entry);
+    }
+    return entries.join(',');
+}
+/**
+ * Parse baggage from header format
+ */
+export function parseBaggage(header) {
+    const baggage = new Map();
+    if (!header) {
+        return baggage;
+    }
+    const entries = header.split(',');
+    for (const entry of entries) {
+        const parts = entry.trim().split(';');
+        const [keyValue, ...metadataParts] = parts;
+        if (!keyValue)
+            continue;
+        const [key, ...valueParts] = keyValue.split('=');
+        if (!key)
+            continue;
+        const value = decodeURIComponent(valueParts.join('='));
+        const metadata = {};
+        for (const metaPart of metadataParts) {
+            const [metaKey, ...metaValueParts] = metaPart.split('=');
+            if (metaKey) {
+                metadata[metaKey.trim()] = decodeURIComponent(metaValueParts.join('='));
+            }
+        }
+        const baggageItem = { value };
+        if (Object.keys(metadata).length > 0) {
+            baggageItem.metadata = metadata;
+        }
+        baggage.set(key.trim(), baggageItem);
+    }
+    return baggage;
+}
+/**
+ * Extract trace context from RPC call metadata
+ *
+ * Used by the receiving DO to extract the parent span context
+ * from an incoming RPC call.
+ *
+ * @param traceContext - Serialized trace context from RPC parameter
+ * @returns Span context for creating child spans
+ */
+export function extractDORpcContext(traceContext) {
+    return deserializeTraceContext(traceContext);
+}
+/**
+ * Create a traced wrapper for DO RPC calls
+ *
+ * Wraps RPC method calls to automatically propagate trace context
+ * and create spans for cross-DO operations.
+ *
+ * @param tracer - The tracer instance
+ * @param parentContext - Parent span context to propagate
+ * @param targetDoId - The target DO's ID
+ * @param serviceName - Name of the target service (e.g., 'PostgresDO')
+ *
+ * @example
+ * ```typescript
+ * const traced = createDORpcTracer(tracer, span.getContext(), doId, 'PostgresDO')
+ *
+ * // Wrap your RPC call
+ * const result = await traced.trace('rpcQuery', async (traceContext) => {
+ *   return stub.rpcQuery(sql, params, traceContext)
+ * })
+ * ```
+ */
+export function createDORpcTracer(tracer, parentContext, targetDoId, serviceName = 'DurableObject') {
+    return {
+        /**
+         * Trace an RPC call to another DO
+         *
+         * @param methodName - Name of the RPC method
+         * @param executor - Function that executes the RPC call
+         * @param options - Additional tracing options
+         */
+        async trace(methodName, executor, options) {
+            const spanName = options?.operationName ?? `rpc.${serviceName}.${methodName}`;
+            const spanOptions = {
+                kind: SpanKind.CLIENT,
+                attributes: {
+                    'do.target.id': targetDoId,
+                    'rpc.method': methodName,
+                    'rpc.service': serviceName,
+                    'rpc.role': 'caller',
+                    ...options?.attributes,
+                },
+                parent: parentContext ?? undefined,
+            };
+            return tracer.startActiveSpan(spanName, spanOptions, async (span) => {
+                try {
+                    // Create trace context to propagate
+                    const traceContext = serializeTraceContext(span.getContext(), options?.baggage);
+                    const result = await executor(traceContext);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return result;
+                }
+                catch (error) {
+                    span.recordException(error);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    throw error;
+                }
+            });
+        },
+        /**
+         * Trace a batch of RPC calls
+         *
+         * @param methodName - Name of the RPC method
+         * @param executor - Function that executes the batch RPC call
+         * @param options - Additional tracing options
+         */
+        async traceBatch(methodName, executor, options) {
+            return this.trace(methodName, executor, {
+                ...options,
+                operationName: options?.operationName ?? `rpc.${serviceName}.${methodName}.batch`,
+            });
+        },
+    };
+}
+/**
+ * Create instrumentation for the receiving side of cross-DO RPC
+ *
+ * Used in the target DO to create spans for incoming RPC calls.
+ *
+ * @param tracer - The tracer instance
+ * @param doId - This DO's ID
+ * @param serviceName - Name of this service
+ *
+ * @example
+ * ```typescript
+ * const rpcHandler = createDORpcHandler(tracer, this.ctx.id.toString(), 'PostgresDO')
+ *
+ * // In your RPC method
+ * async rpcQuery(sql: string, params?: unknown[], traceContext?: SerializedTraceContext) {
+ *   return rpcHandler.handle('rpcQuery', traceContext, { sql }, async (span) => {
+ *     // Execute query
+ *     return this.executeQuery({ sql, params })
+ *   })
+ * }
+ * ```
+ */
+export function createDORpcHandler(tracer, doId, serviceName = 'DurableObject') {
+    return {
+        /**
+         * Handle an incoming RPC call with tracing
+         *
+         * @param methodName - Name of the RPC method
+         * @param traceContext - Trace context from caller
+         * @param attributes - Additional span attributes
+         * @param executor - Function to execute the RPC
+         */
+        async handle(methodName, traceContext, attributes, executor) {
+            const parentContext = deserializeTraceContext(traceContext);
+            const spanName = `rpc.${serviceName}.${methodName}`;
+            const spanOptions = {
+                kind: SpanKind.SERVER,
+                attributes: {
+                    'do.id': doId,
+                    'rpc.method': methodName,
+                    'rpc.service': serviceName,
+                    'rpc.role': 'callee',
+                    ...attributes,
+                },
+                parent: parentContext ?? undefined,
+            };
+            return tracer.startActiveSpan(spanName, spanOptions, async (span) => {
+                try {
+                    const result = await executor(span);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return result;
+                }
+                catch (error) {
+                    span.recordException(error);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    throw error;
+                }
+            });
+        },
+    };
+}
+/**
+ * Inject trace context into fetch request headers
+ *
+ * Use this when making fetch calls to other services or DOs
+ * that support W3C Trace Context headers.
+ *
+ * @param context - The span context to inject
+ * @param request - The request to modify
+ * @param baggage - Optional baggage to include
+ * @returns New request with trace headers
+ *
+ * @example
+ * ```typescript
+ * const request = new Request('https://other-service.com/api')
+ * const tracedRequest = injectTraceIntoRequest(span.getContext(), request)
+ * const response = await fetch(tracedRequest)
+ * ```
+ */
+export function injectTraceIntoRequest(context, request, baggage) {
+    const headers = new Headers(request.headers);
+    injectSpanContext(context, headers);
+    if (baggage && baggage.size > 0) {
+        headers.set(BAGGAGE_HEADER, serializeBaggage(baggage));
+    }
+    return new Request(request.url, {
+        method: request.method,
+        headers,
+        body: request.body,
+        redirect: request.redirect,
+        signal: request.signal,
+    });
+}
+/**
+ * Extract trace context and baggage from incoming request
+ *
+ * @param request - The incoming request
+ * @returns Object with span context and baggage
+ */
+export function extractTraceFromRequest(request) {
+    const context = extractSpanContext(request.headers);
+    const baggage = parseBaggage(request.headers.get(BAGGAGE_HEADER));
+    return { context, baggage };
+}
+/**
+ * Create a child span context for cross-DO calls
+ *
+ * Creates a new span ID while preserving the trace ID,
+ * suitable for propagating to child operations.
+ *
+ * @param parent - Parent span context
+ * @returns Child span context
+ */
+export function createCrossDoChildContext(parent) {
+    return createChildContext(parent);
+}
+/**
+ * Create a traced proxy for a DO stub
+ *
+ * Automatically propagates trace context for all RPC method calls.
+ * This is a convenience wrapper for DOs that don't explicitly accept
+ * trace context parameters.
+ *
+ * Note: This works best with DOs that have been instrumented to accept
+ * an optional trace context parameter.
+ *
+ * @param stub - The DO stub
+ * @param tracer - Tracer instance
+ * @param parentContext - Parent span context
+ * @param targetDoId - Target DO ID
+ * @param serviceName - Target service name
+ *
+ * @example
+ * ```typescript
+ * const stub = env.POSTGRES_DO.get(id)
+ * const tracedStub = createTracedDOStubProxy(
+ *   stub,
+ *   tracer,
+ *   currentSpan.getContext(),
+ *   id.toString(),
+ *   'PostgresDO'
+ * )
+ *
+ * // All RPC calls are automatically traced
+ * await tracedStub.rpcQuery('SELECT * FROM users')
+ * ```
+ */
+export function createTracedDOStubProxy(stub, tracer, parentContext, targetDoId, serviceName = 'DurableObject') {
+    const rpcTracer = createDORpcTracer(tracer, parentContext, targetDoId, serviceName);
+    return new Proxy(stub, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            // Only wrap function properties that look like RPC methods
+            if (typeof value === 'function' && typeof prop === 'string' && prop.startsWith('rpc')) {
+                return async (...args) => {
+                    return rpcTracer.trace(prop, async (traceContext) => {
+                        // Add trace context as the last argument
+                        return value.call(target, ...args, traceContext);
+                    });
+                };
+            }
+            return value;
+        },
+    });
+}
+//# sourceMappingURL=cross-do-tracing.js.map

package/dist/observability/cross-do-tracing.js.map

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

package/dist/observability/error-rate-collector.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Error Rate Collector
+ *
+ * Tracks error rates with time-windowed sliding window calculations,
+ * error categorization, and trend analysis.
+ */
+import type { MetricsCollector } from './types';
+export type ErrorCategory = 'query' | 'connection' | 'cache' | 'storage' | 'timeout' | 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'internal' | 'unknown';
+export type ErrorSeverity = 'debug' | 'info' | 'warning' | 'error' | 'critical';
+export interface ErrorEvent {
+    category: ErrorCategory;
+    message: string;
+    timestamp?: number;
+    code?: string;
+    severity?: ErrorSeverity;
+    tags?: Record<string, string>;
+}
+export interface ErrorRateSnapshot {
+    count: number;
+    windowMs: number;
+    ratePerSecond: number;
+    ratePerMinute: number;
+    ratePerHour: number;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface ErrorBucket {
+    startTimestamp: number;
+    endTimestamp: number;
+    count: number;
+}
+export type TrendDirection = 'increasing' | 'decreasing' | 'stable';
+export interface ErrorTrend {
+    direction: TrendDirection;
+    changePercent: number;
+    avgRate: number;
+    periodRates: number[];
+}
+export interface ErrorSpike {
+    timestamp: number;
+    count: number;
+    multiplier: number;
+}
+export interface RateChange {
+    currentRate: number;
+    previousRate: number;
+    percentChange: number;
+}
+export interface ErrorAnomaly {
+    category: ErrorCategory;
+    severity: 'low' | 'medium' | 'high';
+    expectedRate: number;
+    actualRate: number;
+    deviationFactor: number;
+}
+export interface HistoricalComparison {
+    currentRate: number;
+    historicalAverage: number;
+    ratio: number;
+}
+export interface CategoryStats {
+    count: number;
+    ratePerMinute: number;
+}
+export interface ErrorCollectorSnapshot {
+    totalErrors: number;
+    byCategory: Record<ErrorCategory, CategoryStats>;
+    bySeverity: Record<ErrorSeverity, CategoryStats>;
+    recentRate: ErrorRateSnapshot;
+    timestamp: number;
+}
+export interface ErrorRateFilter {
+    windowMs?: number;
+    category?: ErrorCategory;
+    severity?: ErrorSeverity;
+    tags?: Record<string, string>;
+}
+export interface ErrorBucketOptions {
+    windowMs: number;
+    bucketSizeMs: number;
+}
+export interface TrendAnalysisOptions {
+    windowMs: number;
+    periods: number;
+}
+export interface SpikeDetectionOptions {
+    windowMs: number;
+    threshold: number;
+}
+export interface AnomalyDetectionOptions {
+    windowMs: number;
+    baselineWindowMs: number;
+    sensitivity: number;
+}
+export interface RateChangeOptions {
+    currentWindowMs: number;
+    previousWindowMs: number;
+}
+export interface MovingAverageOptions {
+    windowMs: number;
+    periods: number;
+}
+export interface HistoricalComparisonOptions {
+    currentWindowMs: number;
+    historicalWindowMs: number;
+}
+export interface ErrorRateCollectorConfig {
+    defaultWindowMs?: number;
+    retentionMs?: number;
+    metricsCollector?: MetricsCollector;
+}
+export interface ErrorRateCollector {
+    recordError(event: ErrorEvent): void;
+    getErrorRate(filter?: ErrorRateFilter): ErrorRateSnapshot;
+    getErrorBuckets(options: ErrorBucketOptions): ErrorBucket[];
+    getErrorsByCategory(filter?: ErrorRateFilter): Record<ErrorCategory, CategoryStats>;
+    getErrorsByCode(): Record<string, CategoryStats>;
+    getErrorsBySeverity(): Record<ErrorSeverity, CategoryStats>;
+    getTopErrorCodes(options?: {
+        limit?: number;
+    }): Array<{
+        code: string;
+        count: number;
+    }>;
+    analyzeTrend(options: TrendAnalysisOptions): ErrorTrend;
+    detectSpikes(options: SpikeDetectionOptions): ErrorSpike[];
+    detectAnomalies(options: AnomalyDetectionOptions): ErrorAnomaly[];
+    getRateChange(options: RateChangeOptions): RateChange;
+    getMovingAverage(options: MovingAverageOptions): number;
+    compareToHistorical(options: HistoricalComparisonOptions): HistoricalComparison;
+    getSnapshot(): ErrorCollectorSnapshot;
+    cleanup(): void;
+    reset(): void;
+}
+export declare class ErrorRateCollectorImpl implements ErrorRateCollector {
+    private config;
+    private errors;
+    constructor(config?: ErrorRateCollectorConfig);
+    recordError(event: ErrorEvent): void;
+    getErrorRate(filter?: ErrorRateFilter): ErrorRateSnapshot;
+    getErrorBuckets(options: ErrorBucketOptions): ErrorBucket[];
+    getErrorsByCategory(filter?: ErrorRateFilter): Record<ErrorCategory, CategoryStats>;
+    getErrorsByCode(): Record<string, CategoryStats>;
+    getErrorsBySeverity(): Record<ErrorSeverity, CategoryStats>;
+    getTopErrorCodes(options?: {
+        limit?: number;
+    }): Array<{
+        code: string;
+        count: number;
+    }>;
+    analyzeTrend(options: TrendAnalysisOptions): ErrorTrend;
+    detectSpikes(options: SpikeDetectionOptions): ErrorSpike[];
+    detectAnomalies(options: AnomalyDetectionOptions): ErrorAnomaly[];
+    getRateChange(options: RateChangeOptions): RateChange;
+    getMovingAverage(options: MovingAverageOptions): number;
+    compareToHistorical(options: HistoricalComparisonOptions): HistoricalComparison;
+    getSnapshot(): ErrorCollectorSnapshot;
+    cleanup(): void;
+    reset(): void;
+    private filterErrors;
+}
+export declare function createErrorRateCollector(config?: ErrorRateCollectorConfig): ErrorRateCollector;
+//# sourceMappingURL=error-rate-collector.d.ts.map

package/dist/observability/error-rate-collector.d.ts.map

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