@dotdo/postgres 0.1.0

package/src/observability/prometheus.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Tests for Prometheus Exporter
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  createPrometheusExporter,
+  PrometheusExporterImpl,
+  createMetricsHandler,
+  DEFAULT_METRIC_META,
+} from './prometheus'
+import { createMetricsCollector } from './metrics'
+import type { MetricSnapshot } from './types'
+
+describe('PrometheusExporter', () => {
+  describe('createPrometheusExporter()', () => {
+    it('should create a PrometheusExporterImpl instance', () => {
+      const exporter = createPrometheusExporter()
+      expect(exporter).toBeInstanceOf(PrometheusExporterImpl)
+    })
+  })
+
+  describe('export()', () => {
+    let exporter: PrometheusExporterImpl
+
+    beforeEach(() => {
+      exporter = new PrometheusExporterImpl()
+    })
+
+    it('should export counter metrics in Prometheus format', () => {
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'postgres.query.count',
+          type: 'counter',
+          value: 100,
+          tags: { operation: 'SELECT' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporter.export(metrics)
+
+      expect(output).toContain('# HELP postgres_query_total')
+      expect(output).toContain('# TYPE postgres_query_total counter')
+      expect(output).toContain('postgres_query_total{operation="SELECT"} 100')
+    })
+
+    it('should export gauge metrics in Prometheus format', () => {
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'postgres.do.storage_bytes',
+          type: 'gauge',
+          value: 1048576,
+          tags: {},
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporter.export(metrics)
+
+      expect(output).toContain('# TYPE postgres_do_storage_bytes gauge')
+      expect(output).toContain('postgres_do_storage_bytes 1048576')
+    })
+
+    it('should export histogram metrics with sum and count', () => {
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'postgres.query.duration_ms',
+          type: 'histogram',
+          value: 500, // sum
+          tags: { operation: 'INSERT' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporter.export(metrics)
+
+      expect(output).toContain('# TYPE postgres_query_duration_milliseconds histogram')
+      expect(output).toContain('postgres_query_duration_milliseconds_sum{operation="INSERT"} 500')
+      expect(output).toContain('postgres_query_duration_milliseconds_count{operation="INSERT"} 1')
+    })
+
+    it('should escape label values correctly', () => {
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'test.metric',
+          type: 'counter',
+          value: 1,
+          tags: { query: 'SELECT * FROM "users"' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporter.export(metrics)
+
+      expect(output).toContain('query="SELECT * FROM \\"users\\""')
+    })
+
+    it('should handle multiple metrics with same name but different tags', () => {
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'postgres.query.count',
+          type: 'counter',
+          value: 100,
+          tags: { operation: 'SELECT' },
+          timestamp: Date.now(),
+        },
+        {
+          name: 'postgres.query.count',
+          type: 'counter',
+          value: 50,
+          tags: { operation: 'INSERT' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporter.export(metrics)
+
+      expect(output).toContain('postgres_query_total{operation="SELECT"} 100')
+      expect(output).toContain('postgres_query_total{operation="INSERT"} 50')
+    })
+
+    it('should include timestamp when configured', () => {
+      const exporterWithTimestamp = new PrometheusExporterImpl({ includeTimestamp: true })
+      const timestamp = Date.now()
+
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'test.counter',
+          type: 'counter',
+          value: 1,
+          tags: {},
+          timestamp,
+        },
+      ]
+
+      const output = exporterWithTimestamp.export(metrics)
+
+      expect(output).toContain(String(timestamp))
+    })
+
+    it('should use custom prefix', () => {
+      const exporterWithPrefix = new PrometheusExporterImpl({ prefix: 'custom' })
+
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'my.metric',
+          type: 'counter',
+          value: 1,
+          tags: {},
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporterWithPrefix.export(metrics)
+
+      expect(output).toContain('custom_my_metric')
+    })
+
+    it('should add default labels to all metrics', () => {
+      const exporterWithLabels = new PrometheusExporterImpl({
+        defaultLabels: { service: 'postgres-do', env: 'production' },
+      })
+
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'test.metric',
+          type: 'counter',
+          value: 1,
+          tags: {},
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporterWithLabels.export(metrics)
+
+      expect(output).toContain('service="postgres-do"')
+      expect(output).toContain('env="production"')
+    })
+  })
+
+  describe('exportFromCollector()', () => {
+    it('should export metrics from a MetricsCollector', () => {
+      const collector = createMetricsCollector()
+      collector.increment('test.counter', 10)
+      collector.gauge('test.gauge', 42)
+
+      const exporter = createPrometheusExporter()
+      const output = exporter.exportFromCollector(collector)
+
+      expect(output).toContain('test_counter')
+      expect(output).toContain('10')
+      expect(output).toContain('test_gauge')
+      expect(output).toContain('42')
+    })
+  })
+
+  describe('addMetricMeta()', () => {
+    it('should add custom metric metadata', () => {
+      const exporter = new PrometheusExporterImpl()
+
+      exporter.addMetricMeta('custom.metric', {
+        name: 'custom_metric_fancy',
+        type: 'counter',
+        help: 'A fancy custom metric',
+      })
+
+      const metrics: MetricSnapshot[] = [
+        {
+          name: 'custom.metric',
+          type: 'counter',
+          value: 1,
+          tags: {},
+          timestamp: Date.now(),
+        },
+      ]
+
+      const output = exporter.export(metrics)
+
+      expect(output).toContain('# HELP custom_metric_fancy A fancy custom metric')
+      expect(output).toContain('# TYPE custom_metric_fancy counter')
+    })
+  })
+
+  describe('getContentType()', () => {
+    it('should return the correct Prometheus content type', () => {
+      const exporter = createPrometheusExporter()
+      expect(exporter.getContentType()).toBe('text/plain; version=0.0.4; charset=utf-8')
+    })
+  })
+
+  describe('DEFAULT_METRIC_META', () => {
+    it('should include standard postgres metrics', () => {
+      expect(DEFAULT_METRIC_META['postgres.query.count']).toBeDefined()
+      expect(DEFAULT_METRIC_META['postgres.query.duration_ms']).toBeDefined()
+      expect(DEFAULT_METRIC_META['postgres.cache.hits']).toBeDefined()
+      expect(DEFAULT_METRIC_META['postgres.do.activations']).toBeDefined()
+      expect(DEFAULT_METRIC_META['postgres.errors.count']).toBeDefined()
+    })
+  })
+})
+
+describe('createMetricsHandler()', () => {
+  it('should return null for non-metrics paths', async () => {
+    const collector = createMetricsCollector()
+    const handler = createMetricsHandler(collector)
+
+    const request = new Request('https://example.com/api/users')
+    const response = await handler(request)
+
+    expect(response).toBeNull()
+  })
+
+  it('should return metrics for /metrics path', async () => {
+    const collector = createMetricsCollector()
+    collector.increment('test.counter', 5)
+
+    const handler = createMetricsHandler(collector)
+    const request = new Request('https://example.com/metrics')
+    const response = await handler(request)
+
+    expect(response).not.toBeNull()
+    expect(response!.status).toBe(200)
+    expect(response!.headers.get('Content-Type')).toContain('text/plain')
+
+    const body = await response!.text()
+    expect(body).toContain('test_counter')
+  })
+
+  it('should use custom path when configured', async () => {
+    const collector = createMetricsCollector()
+    const handler = createMetricsHandler(collector, { path: '/custom/metrics' })
+
+    const request1 = new Request('https://example.com/metrics')
+    expect(await handler(request1)).toBeNull()
+
+    const request2 = new Request('https://example.com/custom/metrics')
+    expect(await handler(request2)).not.toBeNull()
+  })
+
+  it('should return 401 when authentication fails', async () => {
+    const collector = createMetricsCollector()
+    const handler = createMetricsHandler(collector, {
+      authenticate: () => false,
+    })
+
+    const request = new Request('https://example.com/metrics')
+    const response = await handler(request)
+
+    expect(response!.status).toBe(401)
+  })
+})

package/src/observability/prometheus.ts

@@ -0,0 +1,170 @@
+/**
+ * Prometheus Exporter
+ *
+ * Exports metrics in Prometheus text format for scraping.
+ */
+
+import type { MetricsCollector, MetricSnapshot } from './types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface MetricMeta {
+  name: string
+  type: 'counter' | 'gauge' | 'histogram' | 'summary'
+  help: string
+}
+
+export interface PrometheusExporterConfig {
+  prefix?: string
+  includeTimestamp?: boolean
+  defaultLabels?: Record<string, string>
+}
+
+export interface MetricsHandlerConfig {
+  path?: string
+  authenticate?: (request: Request) => boolean
+}
+
+export interface PrometheusExporter {
+  export(metrics: MetricSnapshot[]): string
+  exportFromCollector(collector: MetricsCollector): string
+  addMetricMeta(originalName: string, meta: MetricMeta): void
+  getContentType(): string
+}
+
+// ============================================================================
+// Default Metric Metadata
+// ============================================================================
+
+export const DEFAULT_METRIC_META: Record<string, MetricMeta> = {
+  'postgres.query.count': { name: 'postgres_query_total', type: 'counter', help: 'Total number of queries executed' },
+  'postgres.query.duration_ms': { name: 'postgres_query_duration_milliseconds', type: 'histogram', help: 'Query execution duration in milliseconds' },
+  'postgres.query.errors': { name: 'postgres_query_errors_total', type: 'counter', help: 'Total number of query errors' },
+  'postgres.cache.hits': { name: 'postgres_cache_hits_total', type: 'counter', help: 'Total cache hits' },
+  'postgres.cache.misses': { name: 'postgres_cache_misses_total', type: 'counter', help: 'Total cache misses' },
+  'postgres.cache.hit_ratio': { name: 'postgres_cache_hit_ratio', type: 'gauge', help: 'Cache hit ratio (0-1)' },
+  'postgres.do.activations': { name: 'postgres_do_activations_total', type: 'counter', help: 'Total DO activations' },
+  'postgres.do.storage_bytes': { name: 'postgres_do_storage_bytes', type: 'gauge', help: 'DO storage usage in bytes' },
+  'postgres.errors.count': { name: 'postgres_errors_total', type: 'counter', help: 'Total number of errors' },
+  'postgres.memory.heap_bytes': { name: 'postgres_memory_heap_bytes', type: 'gauge', help: 'WASM heap usage in bytes' },
+  'postgres.memory.usage_ratio': { name: 'postgres_memory_usage_ratio', type: 'gauge', help: 'Memory usage ratio (0-1)' },
+  'postgres.alerts.total': { name: 'postgres_alerts_total', type: 'counter', help: 'Total alerts fired' },
+  'postgres.alerts.firing': { name: 'postgres_alerts_firing', type: 'gauge', help: 'Currently firing alerts' },
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+function escapeLabelValue(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')
+}
+
+function toPrometheusName(name: string, prefix?: string): string {
+  let result = name.replace(/\./g, '_').replace(/-/g, '_')
+  if (prefix) result = `${prefix}_${result}`
+  return result
+}
+
+function formatLabels(tags: Record<string, string>, defaultLabels?: Record<string, string>): string {
+  const merged = { ...defaultLabels, ...tags }
+  const entries = Object.entries(merged)
+  if (entries.length === 0) return ''
+  const formatted = entries.map(([key, value]) => `${key}="${escapeLabelValue(value)}"`).join(',')
+  return `{${formatted}}`
+}
+
+export class PrometheusExporterImpl implements PrometheusExporter {
+  private config: PrometheusExporterConfig
+  private metricMeta: Map<string, MetricMeta> = new Map()
+
+  constructor(config?: PrometheusExporterConfig) {
+    this.config = config ?? {}
+    for (const [originalName, meta] of Object.entries(DEFAULT_METRIC_META)) {
+      this.metricMeta.set(originalName, meta)
+    }
+  }
+
+  addMetricMeta(originalName: string, meta: MetricMeta): void {
+    this.metricMeta.set(originalName, meta)
+  }
+
+  export(metrics: MetricSnapshot[]): string {
+    const lines: string[] = []
+    const processedMetrics = new Set<string>()
+    const groupedMetrics: Map<string, MetricSnapshot[]> = new Map()
+
+    for (const metric of metrics) {
+      const group = groupedMetrics.get(metric.name) ?? []
+      group.push(metric)
+      groupedMetrics.set(metric.name, group)
+    }
+
+    for (const [originalName, metricGroup] of groupedMetrics) {
+      const meta = this.metricMeta.get(originalName)
+      const prometheusName = meta?.name ?? toPrometheusName(originalName, this.config.prefix)
+      const metricType = meta?.type ?? metricGroup[0]!.type
+      const help = meta?.help ?? `Metric ${originalName}`
+
+      if (!processedMetrics.has(prometheusName)) {
+        lines.push(`# HELP ${prometheusName} ${help}`)
+        lines.push(`# TYPE ${prometheusName} ${metricType}`)
+        processedMetrics.add(prometheusName)
+      }
+
+      for (const metric of metricGroup) {
+        const labels = formatLabels(metric.tags, this.config.defaultLabels)
+        const timestamp = this.config.includeTimestamp ? ` ${metric.timestamp}` : ''
+
+        if (metric.type === 'histogram') {
+          lines.push(`${prometheusName}_sum${labels} ${metric.value}${timestamp}`)
+          lines.push(`${prometheusName}_count${labels} 1${timestamp}`)
+        } else {
+          lines.push(`${prometheusName}${labels} ${metric.value}${timestamp}`)
+        }
+      }
+    }
+
+    return lines.join('\n')
+  }
+
+  exportFromCollector(collector: MetricsCollector): string {
+    const metrics = collector.getMetrics()
+    return this.export(metrics)
+  }
+
+  getContentType(): string {
+    return 'text/plain; version=0.0.4; charset=utf-8'
+  }
+}
+
+export function createPrometheusExporter(config?: PrometheusExporterConfig): PrometheusExporter {
+  return new PrometheusExporterImpl(config)
+}
+
+// ============================================================================
+// HTTP Handler
+// ============================================================================
+
+export function createMetricsHandler(
+  collector: MetricsCollector,
+  config?: MetricsHandlerConfig
+): (request: Request) => Promise<Response | null> {
+  const path = config?.path ?? '/metrics'
+  const exporter = createPrometheusExporter()
+
+  return async (request: Request): Promise<Response | null> => {
+    const url = new URL(request.url)
+    if (url.pathname !== path) return null
+    if (config?.authenticate && !config.authenticate(request)) {
+      return new Response('Unauthorized', { status: 401 })
+    }
+    const body = exporter.exportFromCollector(collector)
+    return new Response(body, {
+      status: 200,
+      headers: { 'Content-Type': exporter.getContentType() },
+    })
+  }
+}