@dotdo/postgres 0.1.0

package/src/observability/cost-metrics.ts

@@ -0,0 +1,804 @@
+/**
+ * Cost Metrics Collector
+ *
+ * Tracks Cloudflare Workers costs including:
+ * - Durable Object storage reads/writes
+ * - R2 operations (Class A/B)
+ * - Cache API usage (free but tracked for optimization)
+ * - CPU time consumption
+ * - Subrequest counts
+ *
+ * Provides cost estimation based on current Cloudflare pricing.
+ */
+
+import type { MetricSnapshot } from './types'
+
+// ============================================================================
+// Cloudflare Pricing Constants (as of 2024)
+// ============================================================================
+
+/**
+ * Cloudflare pricing constants
+ * These are the standard pay-as-you-go prices
+ */
+export const CloudflarePricing = {
+  /**
+   * Durable Object storage pricing
+   * - Storage: $0.20/GB-month
+   * - Reads: $0.20/million
+   * - Writes: $1.00/million
+   * - Deletes: $1.00/million
+   */
+  DO_STORAGE_PER_GB_MONTH: 0.20,
+  DO_READ_PER_MILLION: 0.20,
+  DO_WRITE_PER_MILLION: 1.00,
+  DO_DELETE_PER_MILLION: 1.00,
+
+  /**
+   * R2 storage pricing
+   * - Storage: $0.015/GB-month
+   * - Class A operations (mutate): $4.50/million
+   * - Class B operations (read): $0.36/million
+   * - Egress: Free
+   */
+  R2_STORAGE_PER_GB_MONTH: 0.015,
+  R2_CLASS_A_PER_MILLION: 4.50,
+  R2_CLASS_B_PER_MILLION: 0.36,
+
+  /**
+   * Workers pricing
+   * - Requests: $0.50/million (after free tier of 10M)
+   * - CPU time: $0.02/million ms (after free tier)
+   * - Duration: Based on plan
+   */
+  WORKERS_REQUESTS_PER_MILLION: 0.50,
+  WORKERS_CPU_PER_MILLION_MS: 0.02,
+
+  /**
+   * Free tier limits (per month)
+   */
+  FREE_TIER: {
+    WORKERS_REQUESTS: 10_000_000,
+    DO_STORAGE_GB: 1,
+    DO_READS: 1_000_000,
+    DO_WRITES: 1_000_000,
+    R2_STORAGE_GB: 10,
+    R2_CLASS_A: 1_000_000,
+    R2_CLASS_B: 10_000_000,
+  },
+} as const
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Operation types for Durable Object storage
+ */
+export type DOStorageOperation = 'read' | 'write' | 'delete' | 'list'
+
+/**
+ * R2 operation classes
+ * Class A: PUT, POST, COPY, LIST, CREATE_MULTIPART, UPLOAD_PART, COMPLETE_MULTIPART, ABORT_MULTIPART
+ * Class B: GET, HEAD
+ */
+export type R2OperationClass = 'A' | 'B'
+
+/**
+ * R2 operation types
+ */
+export type R2Operation =
+  | 'put'
+  | 'get'
+  | 'delete'
+  | 'list'
+  | 'head'
+  | 'copy'
+  | 'multipartUpload'
+  | 'multipartComplete'
+  | 'multipartAbort'
+
+/**
+ * Cache operation types
+ */
+export type CacheOperation = 'get' | 'put' | 'delete' | 'match'
+
+/**
+ * Subrequest types
+ */
+export type SubrequestType = 'fetch' | 'kv' | 'do' | 'r2' | 'cache' | 'other'
+
+/**
+ * Cost breakdown by service
+ */
+export interface CostBreakdown {
+  /** Durable Object costs */
+  durableObjects: {
+    storage: number
+    reads: number
+    writes: number
+    deletes: number
+    total: number
+  }
+  /** R2 costs */
+  r2: {
+    storage: number
+    classA: number
+    classB: number
+    total: number
+  }
+  /** Workers costs */
+  workers: {
+    requests: number
+    cpuTime: number
+    total: number
+  }
+  /** Cache API usage (always 0 cost but tracked) */
+  cache: {
+    hits: number
+    misses: number
+    puts: number
+    savedCost: number
+  }
+  /** Total estimated cost */
+  totalCost: number
+  /** Percentage breakdown */
+  percentages: {
+    durableObjects: number
+    r2: number
+    workers: number
+  }
+}
+
+/**
+ * Cost metrics summary
+ */
+export interface CostMetricsSummary {
+  /** Period start timestamp */
+  periodStart: number
+  /** Period end timestamp */
+  periodEnd: number
+  /** Raw metrics */
+  metrics: {
+    doReads: number
+    doWrites: number
+    doDeletes: number
+    doStorageBytes: number
+    r2ClassA: number
+    r2ClassB: number
+    r2StorageBytes: number
+    cacheHits: number
+    cacheMisses: number
+    cachePuts: number
+    cpuTimeMs: number
+    subrequests: number
+    requests: number
+  }
+  /** Cost breakdown */
+  costs: CostBreakdown
+  /** OpenTelemetry-compatible attributes */
+  otelAttributes: Record<string, string | number | boolean>
+}
+
+/**
+ * Cost metrics collector interface
+ */
+export interface CostMetricsCollector {
+  /** Track a Durable Object storage operation */
+  trackDOOperation(operation: DOStorageOperation, count?: number, bytes?: number): void
+  /** Track an R2 operation */
+  trackR2Operation(operation: R2Operation, count?: number, bytes?: number): void
+  /** Track a Cache API operation */
+  trackCacheOperation(operation: CacheOperation, hit?: boolean, bytes?: number): void
+  /** Track CPU time consumption */
+  trackCPUTime(milliseconds: number): void
+  /** Track a subrequest */
+  trackSubrequest(type?: SubrequestType): void
+  /** Track a request */
+  trackRequest(): void
+  /** Set storage usage (for cost estimation) */
+  setDOStorageUsage(bytes: number): void
+  /** Set R2 storage usage (for cost estimation) */
+  setR2StorageUsage(bytes: number): void
+  /** Get cost metrics summary */
+  getSummary(): CostMetricsSummary
+  /** Get cost breakdown */
+  getCostBreakdown(): CostBreakdown
+  /** Export metrics in OpenTelemetry format */
+  exportOTel(): MetricSnapshot[]
+  /** Reset all metrics */
+  reset(): void
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Map R2 operation to operation class
+ */
+function getR2OperationClass(operation: R2Operation): R2OperationClass {
+  switch (operation) {
+    case 'put':
+    case 'delete':
+    case 'list':
+    case 'copy':
+    case 'multipartUpload':
+    case 'multipartComplete':
+    case 'multipartAbort':
+      return 'A'
+    case 'get':
+    case 'head':
+      return 'B'
+    default:
+      return 'A'
+  }
+}
+
+/**
+ * Cost metrics collector implementation
+ */
+export class CostMetricsCollectorImpl implements CostMetricsCollector {
+  private periodStart: number
+  private doReads = 0
+  private doWrites = 0
+  private doDeletes = 0
+  private doStorageBytes = 0
+  private r2ClassA = 0
+  private r2ClassB = 0
+  private r2StorageBytes = 0
+  private cacheHits = 0
+  private cacheMisses = 0
+  private cachePuts = 0
+  private cpuTimeMs = 0
+  private subrequests = 0
+  private subrequestsByType: Map<SubrequestType, number> = new Map()
+  private requests = 0
+
+  constructor() {
+    this.periodStart = Date.now()
+  }
+
+  trackDOOperation(
+    operation: DOStorageOperation,
+    count = 1,
+    bytes?: number
+  ): void {
+    switch (operation) {
+      case 'read':
+      case 'list':
+        this.doReads += count
+        break
+      case 'write':
+        this.doWrites += count
+        break
+      case 'delete':
+        this.doDeletes += count
+        break
+    }
+
+    if (bytes !== undefined && bytes > 0) {
+      // Track bytes for storage estimation
+      if (operation === 'write') {
+        this.doStorageBytes += bytes
+      }
+    }
+  }
+
+  trackR2Operation(operation: R2Operation, count = 1, bytes?: number): void {
+    const opClass = getR2OperationClass(operation)
+    if (opClass === 'A') {
+      this.r2ClassA += count
+    } else {
+      this.r2ClassB += count
+    }
+
+    if (bytes !== undefined && bytes > 0 && operation === 'put') {
+      this.r2StorageBytes += bytes
+    }
+  }
+
+  trackCacheOperation(
+    operation: CacheOperation,
+    hit?: boolean,
+    _bytes?: number
+  ): void {
+    switch (operation) {
+      case 'get':
+      case 'match':
+        if (hit === true) {
+          this.cacheHits++
+        } else if (hit === false) {
+          this.cacheMisses++
+        }
+        break
+      case 'put':
+        this.cachePuts++
+        break
+      case 'delete':
+        // Deletes don't affect hit/miss metrics
+        break
+    }
+  }
+
+  trackCPUTime(milliseconds: number): void {
+    this.cpuTimeMs += milliseconds
+  }
+
+  trackSubrequest(type: SubrequestType = 'other'): void {
+    this.subrequests++
+    const current = this.subrequestsByType.get(type) ?? 0
+    this.subrequestsByType.set(type, current + 1)
+  }
+
+  trackRequest(): void {
+    this.requests++
+  }
+
+  setDOStorageUsage(bytes: number): void {
+    this.doStorageBytes = bytes
+  }
+
+  setR2StorageUsage(bytes: number): void {
+    this.r2StorageBytes = bytes
+  }
+
+  getCostBreakdown(): CostBreakdown {
+    // Calculate DO costs
+    const doStorageGB = this.doStorageBytes / (1024 * 1024 * 1024)
+    const doStorageCost = doStorageGB * CloudflarePricing.DO_STORAGE_PER_GB_MONTH
+    const doReadsCost =
+      (this.doReads / 1_000_000) * CloudflarePricing.DO_READ_PER_MILLION
+    const doWritesCost =
+      (this.doWrites / 1_000_000) * CloudflarePricing.DO_WRITE_PER_MILLION
+    const doDeletesCost =
+      (this.doDeletes / 1_000_000) * CloudflarePricing.DO_DELETE_PER_MILLION
+    const doTotalCost =
+      doStorageCost + doReadsCost + doWritesCost + doDeletesCost
+
+    // Calculate R2 costs
+    const r2StorageGB = this.r2StorageBytes / (1024 * 1024 * 1024)
+    const r2StorageCost = r2StorageGB * CloudflarePricing.R2_STORAGE_PER_GB_MONTH
+    const r2ClassACost =
+      (this.r2ClassA / 1_000_000) * CloudflarePricing.R2_CLASS_A_PER_MILLION
+    const r2ClassBCost =
+      (this.r2ClassB / 1_000_000) * CloudflarePricing.R2_CLASS_B_PER_MILLION
+    const r2TotalCost = r2StorageCost + r2ClassACost + r2ClassBCost
+
+    // Calculate Workers costs
+    const workersRequestsCost =
+      (this.requests / 1_000_000) * CloudflarePricing.WORKERS_REQUESTS_PER_MILLION
+    const workersCpuCost =
+      (this.cpuTimeMs / 1_000_000) * CloudflarePricing.WORKERS_CPU_PER_MILLION_MS
+    const workersTotalCost = workersRequestsCost + workersCpuCost
+
+    // Calculate cache savings (estimated cost saved by cache hits)
+    // Assume each cache hit saves a DO read or R2 Class B operation
+    const cacheSavedCost =
+      (this.cacheHits / 1_000_000) * CloudflarePricing.R2_CLASS_B_PER_MILLION
+
+    // Total cost
+    const totalCost = doTotalCost + r2TotalCost + workersTotalCost
+
+    // Calculate percentages
+    const percentages =
+      totalCost > 0
+        ? {
+            durableObjects: (doTotalCost / totalCost) * 100,
+            r2: (r2TotalCost / totalCost) * 100,
+            workers: (workersTotalCost / totalCost) * 100,
+          }
+        : {
+            durableObjects: 0,
+            r2: 0,
+            workers: 0,
+          }
+
+    return {
+      durableObjects: {
+        storage: doStorageCost,
+        reads: doReadsCost,
+        writes: doWritesCost,
+        deletes: doDeletesCost,
+        total: doTotalCost,
+      },
+      r2: {
+        storage: r2StorageCost,
+        classA: r2ClassACost,
+        classB: r2ClassBCost,
+        total: r2TotalCost,
+      },
+      workers: {
+        requests: workersRequestsCost,
+        cpuTime: workersCpuCost,
+        total: workersTotalCost,
+      },
+      cache: {
+        hits: this.cacheHits,
+        misses: this.cacheMisses,
+        puts: this.cachePuts,
+        savedCost: cacheSavedCost,
+      },
+      totalCost,
+      percentages,
+    }
+  }
+
+  getSummary(): CostMetricsSummary {
+    const periodEnd = Date.now()
+    const costs = this.getCostBreakdown()
+
+    return {
+      periodStart: this.periodStart,
+      periodEnd,
+      metrics: {
+        doReads: this.doReads,
+        doWrites: this.doWrites,
+        doDeletes: this.doDeletes,
+        doStorageBytes: this.doStorageBytes,
+        r2ClassA: this.r2ClassA,
+        r2ClassB: this.r2ClassB,
+        r2StorageBytes: this.r2StorageBytes,
+        cacheHits: this.cacheHits,
+        cacheMisses: this.cacheMisses,
+        cachePuts: this.cachePuts,
+        cpuTimeMs: this.cpuTimeMs,
+        subrequests: this.subrequests,
+        requests: this.requests,
+      },
+      costs,
+      otelAttributes: this.getOTelAttributes(),
+    }
+  }
+
+  /**
+   * Get OpenTelemetry-compatible attributes
+   */
+  private getOTelAttributes(): Record<string, string | number | boolean> {
+    const costs = this.getCostBreakdown()
+
+    return {
+      // Service identification
+      'service.name': 'postgres-do',
+      'cloud.provider': 'cloudflare',
+      'cloud.platform': 'cloudflare_workers',
+
+      // DO metrics
+      'cloudflare.do.reads': this.doReads,
+      'cloudflare.do.writes': this.doWrites,
+      'cloudflare.do.deletes': this.doDeletes,
+      'cloudflare.do.storage_bytes': this.doStorageBytes,
+      'cloudflare.do.cost_usd': costs.durableObjects.total,
+
+      // R2 metrics
+      'cloudflare.r2.class_a_operations': this.r2ClassA,
+      'cloudflare.r2.class_b_operations': this.r2ClassB,
+      'cloudflare.r2.storage_bytes': this.r2StorageBytes,
+      'cloudflare.r2.cost_usd': costs.r2.total,
+
+      // Cache metrics
+      'cloudflare.cache.hits': this.cacheHits,
+      'cloudflare.cache.misses': this.cacheMisses,
+      'cloudflare.cache.puts': this.cachePuts,
+      'cloudflare.cache.hit_ratio':
+        this.cacheHits + this.cacheMisses > 0
+          ? this.cacheHits / (this.cacheHits + this.cacheMisses)
+          : 0,
+      'cloudflare.cache.saved_cost_usd': costs.cache.savedCost,
+
+      // Worker metrics
+      'cloudflare.workers.cpu_time_ms': this.cpuTimeMs,
+      'cloudflare.workers.subrequests': this.subrequests,
+      'cloudflare.workers.requests': this.requests,
+      'cloudflare.workers.cost_usd': costs.workers.total,
+
+      // Total cost
+      'cloudflare.cost.total_usd': costs.totalCost,
+      'cloudflare.cost.do_percentage': costs.percentages.durableObjects,
+      'cloudflare.cost.r2_percentage': costs.percentages.r2,
+      'cloudflare.cost.workers_percentage': costs.percentages.workers,
+    }
+  }
+
+  exportOTel(): MetricSnapshot[] {
+    const now = Date.now()
+    const snapshots: MetricSnapshot[] = []
+
+    // DO metrics
+    snapshots.push(
+      {
+        name: 'cloudflare.do.reads',
+        type: 'counter',
+        value: this.doReads,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.do.writes',
+        type: 'counter',
+        value: this.doWrites,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.do.deletes',
+        type: 'counter',
+        value: this.doDeletes,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.do.storage_bytes',
+        type: 'gauge',
+        value: this.doStorageBytes,
+        tags: {},
+        timestamp: now,
+      }
+    )
+
+    // R2 metrics
+    snapshots.push(
+      {
+        name: 'cloudflare.r2.class_a_operations',
+        type: 'counter',
+        value: this.r2ClassA,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.r2.class_b_operations',
+        type: 'counter',
+        value: this.r2ClassB,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.r2.storage_bytes',
+        type: 'gauge',
+        value: this.r2StorageBytes,
+        tags: {},
+        timestamp: now,
+      }
+    )
+
+    // Cache metrics
+    snapshots.push(
+      {
+        name: 'cloudflare.cache.hits',
+        type: 'counter',
+        value: this.cacheHits,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cache.misses',
+        type: 'counter',
+        value: this.cacheMisses,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cache.puts',
+        type: 'counter',
+        value: this.cachePuts,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cache.hit_ratio',
+        type: 'gauge',
+        value:
+          this.cacheHits + this.cacheMisses > 0
+            ? this.cacheHits / (this.cacheHits + this.cacheMisses)
+            : 0,
+        tags: {},
+        timestamp: now,
+      }
+    )
+
+    // Worker metrics
+    snapshots.push(
+      {
+        name: 'cloudflare.workers.cpu_time_ms',
+        type: 'counter',
+        value: this.cpuTimeMs,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.workers.subrequests',
+        type: 'counter',
+        value: this.subrequests,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.workers.requests',
+        type: 'counter',
+        value: this.requests,
+        tags: {},
+        timestamp: now,
+      }
+    )
+
+    // Add subrequest breakdown by type
+    for (const [type, count] of this.subrequestsByType) {
+      snapshots.push({
+        name: 'cloudflare.workers.subrequests',
+        type: 'counter',
+        value: count,
+        tags: { type },
+        timestamp: now,
+      })
+    }
+
+    // Cost metrics
+    const costs = this.getCostBreakdown()
+    snapshots.push(
+      {
+        name: 'cloudflare.cost.do_usd',
+        type: 'gauge',
+        value: costs.durableObjects.total,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cost.r2_usd',
+        type: 'gauge',
+        value: costs.r2.total,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cost.workers_usd',
+        type: 'gauge',
+        value: costs.workers.total,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cost.total_usd',
+        type: 'gauge',
+        value: costs.totalCost,
+        tags: {},
+        timestamp: now,
+      },
+      {
+        name: 'cloudflare.cost.cache_saved_usd',
+        type: 'gauge',
+        value: costs.cache.savedCost,
+        tags: {},
+        timestamp: now,
+      }
+    )
+
+    return snapshots
+  }
+
+  reset(): void {
+    this.periodStart = Date.now()
+    this.doReads = 0
+    this.doWrites = 0
+    this.doDeletes = 0
+    this.doStorageBytes = 0
+    this.r2ClassA = 0
+    this.r2ClassB = 0
+    this.r2StorageBytes = 0
+    this.cacheHits = 0
+    this.cacheMisses = 0
+    this.cachePuts = 0
+    this.cpuTimeMs = 0
+    this.subrequests = 0
+    this.subrequestsByType.clear()
+    this.requests = 0
+  }
+}
+
+/**
+ * Create a new cost metrics collector
+ */
+export function createCostMetricsCollector(): CostMetricsCollector {
+  return new CostMetricsCollectorImpl()
+}
+
+/**
+ * No-op cost metrics collector
+ */
+export class NoOpCostMetricsCollector implements CostMetricsCollector {
+  trackDOOperation(): void {}
+  trackR2Operation(): void {}
+  trackCacheOperation(): void {}
+  trackCPUTime(): void {}
+  trackSubrequest(): void {}
+  trackRequest(): void {}
+  setDOStorageUsage(): void {}
+  setR2StorageUsage(): void {}
+
+  getSummary(): CostMetricsSummary {
+    return {
+      periodStart: Date.now(),
+      periodEnd: Date.now(),
+      metrics: {
+        doReads: 0,
+        doWrites: 0,
+        doDeletes: 0,
+        doStorageBytes: 0,
+        r2ClassA: 0,
+        r2ClassB: 0,
+        r2StorageBytes: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        cachePuts: 0,
+        cpuTimeMs: 0,
+        subrequests: 0,
+        requests: 0,
+      },
+      costs: this.getCostBreakdown(),
+      otelAttributes: {},
+    }
+  }
+
+  getCostBreakdown(): CostBreakdown {
+    return {
+      durableObjects: { storage: 0, reads: 0, writes: 0, deletes: 0, total: 0 },
+      r2: { storage: 0, classA: 0, classB: 0, total: 0 },
+      workers: { requests: 0, cpuTime: 0, total: 0 },
+      cache: { hits: 0, misses: 0, puts: 0, savedCost: 0 },
+      totalCost: 0,
+      percentages: { durableObjects: 0, r2: 0, workers: 0 },
+    }
+  }
+
+  exportOTel(): MetricSnapshot[] {
+    return []
+  }
+
+  reset(): void {}
+}
+
+/**
+ * Create a no-op cost metrics collector
+ */
+export function createNoOpCostMetricsCollector(): CostMetricsCollector {
+  return new NoOpCostMetricsCollector()
+}
+
+// ============================================================================
+// Metric Names
+// ============================================================================
+
+/**
+ * Standard cost metric names
+ */
+export const CostMetricNames = {
+  // DO metrics
+  DO_READS: 'cloudflare.do.reads',
+  DO_WRITES: 'cloudflare.do.writes',
+  DO_DELETES: 'cloudflare.do.deletes',
+  DO_STORAGE_BYTES: 'cloudflare.do.storage_bytes',
+  DO_COST_USD: 'cloudflare.cost.do_usd',
+
+  // R2 metrics
+  R2_CLASS_A: 'cloudflare.r2.class_a_operations',
+  R2_CLASS_B: 'cloudflare.r2.class_b_operations',
+  R2_STORAGE_BYTES: 'cloudflare.r2.storage_bytes',
+  R2_COST_USD: 'cloudflare.cost.r2_usd',
+
+  // Cache metrics
+  CACHE_HITS: 'cloudflare.cache.hits',
+  CACHE_MISSES: 'cloudflare.cache.misses',
+  CACHE_PUTS: 'cloudflare.cache.puts',
+  CACHE_HIT_RATIO: 'cloudflare.cache.hit_ratio',
+  CACHE_SAVED_USD: 'cloudflare.cost.cache_saved_usd',
+
+  // Worker metrics
+  WORKERS_CPU_TIME_MS: 'cloudflare.workers.cpu_time_ms',
+  WORKERS_SUBREQUESTS: 'cloudflare.workers.subrequests',
+  WORKERS_REQUESTS: 'cloudflare.workers.requests',
+  WORKERS_COST_USD: 'cloudflare.cost.workers_usd',
+
+  // Total cost
+  TOTAL_COST_USD: 'cloudflare.cost.total_usd',
+} as const
+
+export type CostMetricName = (typeof CostMetricNames)[keyof typeof CostMetricNames]