duron 0.2.1 → 0.3.0-beta.0

package/src/telemetry/local.ts

@@ -0,0 +1,336 @@
+import type { Adapter, InsertMetricOptions } from '../adapters/adapter.js'
+import {
+  type AddSpanAttributeOptions,
+  type AddSpanEventOptions,
+  type EndSpanOptions,
+  type RecordMetricOptions,
+  type Span,
+  type StartDatabaseSpanOptions,
+  type StartJobSpanOptions,
+  type StartStepSpanOptions,
+  TelemetryAdapter,
+} from './adapter.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LocalTelemetryAdapterOptions {
+  /**
+   * Delay in milliseconds before flushing queued metrics to the database.
+   * Metrics are batched and inserted after this delay of inactivity.
+   * @default 1000
+   */
+  flushDelayMs?: number
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_FLUSH_DELAY_MS = 1000
+
+// ============================================================================
+// Local Telemetry Adapter
+// ============================================================================
+
+/**
+ * Local telemetry adapter that stores metrics directly in the Duron database.
+ * Perfect for development and self-hosted deployments.
+ *
+ * This adapter automatically uses the database adapter configured in the Duron client.
+ * Metrics are batched and inserted after a configurable delay of inactivity to reduce database load.
+ *
+ * @example
+ * ```typescript
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter({ flushDelayMs: 500 }), // Custom 500ms delay
+ *   actions: { ... }
+ * })
+ * ```
+ */
+export class LocalTelemetryAdapter extends TelemetryAdapter {
+  #spanStartTimes = new Map<string, number>()
+  #metricsQueue: InsertMetricOptions[] = []
+  #flushTimer: ReturnType<typeof setTimeout> | null = null
+  #flushPromise: Promise<void> | null = null
+  #flushDelayMs: number
+
+  constructor(options?: LocalTelemetryAdapterOptions) {
+    super()
+    this.#flushDelayMs = options?.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS
+  }
+
+  /**
+   * Get the database adapter from the Duron client.
+   * @throws Error if the client is not set
+   */
+  get #database(): Adapter {
+    const client = this.client
+    if (!client) {
+      throw new Error(
+        'LocalTelemetryAdapter requires the Duron client to be set. This is done automatically by the Duron client.',
+      )
+    }
+    return client.database
+  }
+
+  // ============================================================================
+  // Queue Management
+  // ============================================================================
+
+  /**
+   * Queue a metric for batch insertion.
+   * The metric will be inserted after 1 second of inactivity.
+   */
+  #queueMetric(options: InsertMetricOptions): void {
+    this.#metricsQueue.push(options)
+    this.#scheduleFlush()
+  }
+
+  /**
+   * Schedule a flush of the metrics queue.
+   * Resets the timer on each call (debounce behavior).
+   */
+  #scheduleFlush(): void {
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer)
+    }
+
+    this.#flushTimer = setTimeout(() => {
+      this.#flushTimer = null
+      this.#flushPromise = this.#flushQueue().finally(() => {
+        this.#flushPromise = null
+      })
+    }, this.#flushDelayMs)
+  }
+
+  /**
+   * Flush all queued metrics to the database.
+   */
+  async #flushQueue(): Promise<void> {
+    if (this.#metricsQueue.length === 0) {
+      return
+    }
+
+    // Take all metrics from the queue
+    const metrics = this.#metricsQueue.splice(0, this.#metricsQueue.length)
+
+    // Batch insert all metrics in a single database operation
+    await this.#database.insertMetrics(metrics)
+  }
+
+  /**
+   * Force flush the queue immediately.
+   * Used during shutdown to ensure all metrics are persisted.
+   */
+  async #forceFlush(): Promise<void> {
+    // Clear any pending timer
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer)
+      this.#flushTimer = null
+    }
+
+    // Wait for any in-progress flush
+    if (this.#flushPromise) {
+      await this.#flushPromise
+    }
+
+    // Flush remaining metrics
+    await this.#flushQueue()
+  }
+
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+
+  protected async _start(): Promise<void> {
+    // Database adapter should already be started by the client
+  }
+
+  protected async _stop(): Promise<void> {
+    // Flush any remaining metrics before stopping
+    await this.#forceFlush()
+    this.#spanStartTimes.clear()
+  }
+
+  // ============================================================================
+  // Span Methods
+  // ============================================================================
+
+  protected async _startJobSpan(options: StartJobSpanOptions): Promise<Span> {
+    const spanId = `job:${options.jobId}`
+    this.#spanStartTimes.set(spanId, Date.now())
+
+    // Record span start as a metric
+    this.#queueMetric({
+      jobId: options.jobId,
+      name: 'duron.job.span.start',
+      value: Date.now(),
+      type: 'span_event',
+      attributes: {
+        actionName: options.actionName,
+        groupKey: options.groupKey,
+        spanId,
+      },
+    })
+
+    return {
+      id: spanId,
+      jobId: options.jobId,
+      stepId: null,
+      parentSpanId: null,
+    }
+  }
+
+  protected async _endJobSpan(span: Span, options: EndSpanOptions): Promise<void> {
+    const startTime = this.#spanStartTimes.get(span.id)
+    const duration = startTime ? Date.now() - startTime : 0
+    this.#spanStartTimes.delete(span.id)
+
+    // Record span end with duration
+    this.#queueMetric({
+      jobId: span.jobId,
+      name: 'duron.job.span.end',
+      value: duration,
+      type: 'span_event',
+      attributes: {
+        spanId: span.id,
+        status: options.status,
+        error: options.error?.message ?? null,
+        durationMs: duration,
+      },
+    })
+  }
+
+  protected async _startStepSpan(options: StartStepSpanOptions): Promise<Span> {
+    const spanId = `step:${options.stepId}`
+    this.#spanStartTimes.set(spanId, Date.now())
+
+    // Record span start as a metric
+    this.#queueMetric({
+      jobId: options.jobId,
+      stepId: options.stepId,
+      name: 'duron.step.span.start',
+      value: Date.now(),
+      type: 'span_event',
+      attributes: {
+        stepName: options.stepName,
+        parentStepId: options.parentStepId,
+        parentSpanId: options.parentSpan?.id ?? null,
+        spanId,
+      },
+    })
+
+    return {
+      id: spanId,
+      jobId: options.jobId,
+      stepId: options.stepId,
+      parentSpanId: options.parentSpan?.id ?? null,
+    }
+  }
+
+  protected async _endStepSpan(span: Span, options: EndSpanOptions): Promise<void> {
+    const startTime = this.#spanStartTimes.get(span.id)
+    const duration = startTime ? Date.now() - startTime : 0
+    this.#spanStartTimes.delete(span.id)
+
+    // Record span end with duration
+    this.#queueMetric({
+      jobId: span.jobId,
+      stepId: span.stepId ?? undefined,
+      name: 'duron.step.span.end',
+      value: duration,
+      type: 'span_event',
+      attributes: {
+        spanId: span.id,
+        status: options.status,
+        error: options.error?.message ?? null,
+        durationMs: duration,
+      },
+    })
+  }
+
+  protected async _startDatabaseSpan(_options: StartDatabaseSpanOptions): Promise<Span | null> {
+    // Local adapter doesn't trace database operations to avoid infinite loops
+    return null
+  }
+
+  protected async _endDatabaseSpan(_span: Span, _options: EndSpanOptions): Promise<void> {
+    // No-op for local adapter
+  }
+
+  // ============================================================================
+  // Metrics Methods
+  // ============================================================================
+
+  protected async _recordMetric(options: RecordMetricOptions): Promise<void> {
+    this.#queueMetric({
+      jobId: options.jobId,
+      stepId: options.stepId,
+      name: options.name,
+      value: options.value,
+      type: 'metric',
+      attributes: options.attributes,
+    })
+  }
+
+  protected async _addSpanEvent(options: AddSpanEventOptions): Promise<void> {
+    this.#queueMetric({
+      jobId: options.span.jobId,
+      stepId: options.span.stepId ?? undefined,
+      name: options.name,
+      value: Date.now(),
+      type: 'span_event',
+      attributes: {
+        spanId: options.span.id,
+        ...options.attributes,
+      },
+    })
+  }
+
+  protected async _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void> {
+    this.#queueMetric({
+      jobId: options.span.jobId,
+      stepId: options.span.stepId ?? undefined,
+      name: `attribute:${options.key}`,
+      value: typeof options.value === 'number' ? options.value : 0,
+      type: 'span_attribute',
+      attributes: {
+        spanId: options.span.id,
+        key: options.key,
+        value: String(options.value),
+      },
+    })
+  }
+}
+
+/**
+ * Create a local telemetry adapter that stores metrics in the Duron database.
+ * Perfect for development and self-hosted deployments.
+ *
+ * The database adapter is automatically obtained from the Duron client.
+ * Metrics are batched and inserted after a configurable delay of inactivity to reduce database load.
+ *
+ * @param options - Configuration options
+ * @param options.flushDelayMs - Delay in milliseconds before flushing queued metrics (default: 1000)
+ * @returns LocalTelemetryAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter(), // Uses default 1 second delay
+ *   actions: { ... }
+ * })
+ *
+ * // Or with custom flush delay
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter({ flushDelayMs: 500 }), // 500ms delay
+ *   actions: { ... }
+ * })
+ * ```
+ */
+export const localTelemetryAdapter = (options?: LocalTelemetryAdapterOptions) => new LocalTelemetryAdapter(options)

package/src/telemetry/noop.ts

@@ -0,0 +1,95 @@
+import {
+  type AddSpanAttributeOptions,
+  type AddSpanEventOptions,
+  type EndSpanOptions,
+  type RecordMetricOptions,
+  type Span,
+  type StartDatabaseSpanOptions,
+  type StartJobSpanOptions,
+  type StartStepSpanOptions,
+  TelemetryAdapter,
+} from './adapter.js'
+
+// ============================================================================
+// Noop Telemetry Adapter
+// ============================================================================
+
+/**
+ * No-operation telemetry adapter.
+ * Used when telemetry is disabled. All methods are no-ops.
+ */
+export class NoopTelemetryAdapter extends TelemetryAdapter {
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+
+  protected async _start(): Promise<void> {
+    // No-op
+  }
+
+  protected async _stop(): Promise<void> {
+    // No-op
+  }
+
+  // ============================================================================
+  // Span Methods
+  // ============================================================================
+
+  protected async _startJobSpan(options: StartJobSpanOptions): Promise<Span> {
+    return {
+      id: 'noop',
+      jobId: options.jobId,
+      stepId: null,
+      parentSpanId: null,
+    }
+  }
+
+  protected async _endJobSpan(_span: Span, _options: EndSpanOptions): Promise<void> {
+    // No-op
+  }
+
+  protected async _startStepSpan(options: StartStepSpanOptions): Promise<Span> {
+    return {
+      id: 'noop',
+      jobId: options.jobId,
+      stepId: options.stepId,
+      parentSpanId: options.parentSpan?.id ?? null,
+    }
+  }
+
+  protected async _endStepSpan(_span: Span, _options: EndSpanOptions): Promise<void> {
+    // No-op
+  }
+
+  protected async _startDatabaseSpan(_options: StartDatabaseSpanOptions): Promise<Span | null> {
+    return null
+  }
+
+  protected async _endDatabaseSpan(_span: Span, _options: EndSpanOptions): Promise<void> {
+    // No-op
+  }
+
+  // ============================================================================
+  // Metrics Methods
+  // ============================================================================
+
+  protected async _recordMetric(_options: RecordMetricOptions): Promise<void> {
+    // No-op
+  }
+
+  protected async _addSpanEvent(_options: AddSpanEventOptions): Promise<void> {
+    // No-op
+  }
+
+  protected async _addSpanAttribute(_options: AddSpanAttributeOptions): Promise<void> {
+    // No-op
+  }
+}
+
+/**
+ * Create a no-operation telemetry adapter.
+ * Use this when telemetry should be disabled.
+ *
+ * @returns NoopTelemetryAdapter instance
+ */
+export const noopTelemetryAdapter = () => new NoopTelemetryAdapter()