@contractspec/lib.observability 1.57.0 → 1.58.0

package/dist/telemetry/posthog-baseline-reader.js

@@ -0,0 +1,309 @@
+// @bun
+// src/telemetry/posthog-baseline-reader.ts
+class PosthogBaselineReader {
+  reader;
+  eventPrefix;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.eventPrefix = options.eventPrefix ?? "observability";
+  }
+  async readSamples(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.operation as operationName,",
+        "  properties.version as version,",
+        "  properties.durationMs as durationMs,",
+        "  properties.success as success,",
+        "  properties.errorCode as errorCode,",
+        "  properties.tenantId as tenantId,",
+        "  properties.traceId as traceId,",
+        "  properties.metadata as metadata,",
+        "  distinct_id as actorId,",
+        "  timestamp as timestamp",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 1000}`
+      ].join(`
+`),
+      values: buildOperationValues(input)
+    });
+    return mapTelemetrySamples(result);
+  }
+  async readAggregatedMetrics(operation, windowDays = 7) {
+    const dateRange = buildWindowRange(windowDays);
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  count() as totalCalls,",
+        "  avg(properties.durationMs) as averageLatencyMs,",
+        "  quantile(0.95)(properties.durationMs) as p95LatencyMs,",
+        "  quantile(0.99)(properties.durationMs) as p99LatencyMs,",
+        "  max(properties.durationMs) as maxLatencyMs,",
+        "  sum(if(properties.success = 1, 1, 0)) as successCount,",
+        "  sum(if(properties.success = 0, 1, 0)) as errorCount",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, {
+          operations: [operation],
+          dateRange
+        })}`
+      ].join(`
+`),
+      values: buildOperationValues({
+        operations: [operation],
+        dateRange
+      })
+    });
+    const stats = mapAggregatedMetrics(result, operation, dateRange);
+    if (!stats)
+      return null;
+    const topErrors = await this.readTopErrors(operation, dateRange);
+    return {
+      ...stats,
+      topErrors
+    };
+  }
+  async readOperationSequences(dateRange) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.sequences as sequences",
+        "from events",
+        `where event = {eventName}`,
+        dateRange?.from ? "and timestamp >= {dateFrom}" : "",
+        dateRange?.to ? "and timestamp < {dateTo}" : "",
+        "order by timestamp desc",
+        "limit 50"
+      ].filter(Boolean).join(`
+`),
+      values: {
+        eventName: `${this.eventPrefix}.window`,
+        dateFrom: toIsoString(dateRange?.from),
+        dateTo: toIsoString(dateRange?.to)
+      }
+    });
+    return mergeSequences(result);
+  }
+  async readTopErrors(operation, dateRange) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.errorCode as errorCode,",
+        "  count() as errorCount",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, {
+          operations: [operation],
+          dateRange
+        })} and properties.success = 0`,
+        "group by errorCode",
+        "order by errorCount desc",
+        "limit 5"
+      ].join(`
+`),
+      values: buildOperationValues({
+        operations: [operation],
+        dateRange
+      })
+    });
+    const rows = mapRows(result);
+    return rows.reduce((acc, row) => {
+      const code = asString(row.errorCode);
+      if (!code)
+        return acc;
+      acc[code] = asNumber(row.errorCount);
+      return acc;
+    }, {});
+  }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    return this.reader.queryHogQL(input);
+  }
+}
+function buildOperationWhereClause(eventPrefix, input) {
+  const clauses = [`event = '${eventPrefix}.operation'`];
+  if (input.operations?.length) {
+    clauses.push(`(${buildOperationFilters(input.operations)})`);
+  }
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
+  }
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
+  }
+  return clauses.join(" and ");
+}
+function buildOperationValues(input) {
+  const values = {
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+  input.operations?.forEach((op, index) => {
+    values[`operationName${index}`] = op.name;
+    values[`operationVersion${index}`] = op.version;
+  });
+  return values;
+}
+function buildOperationFilters(operations) {
+  return operations.map((_op, index) => `(properties.operation = {operationName${index}} and properties.version = {operationVersion${index}})`).join(" or ");
+}
+function mapTelemetrySamples(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const operationName = asString(row.operationName);
+    const version = asString(row.version);
+    const timestamp = asDate(row.timestamp);
+    if (!operationName || !version || !timestamp) {
+      return [];
+    }
+    return [
+      {
+        operation: { name: operationName, version },
+        durationMs: asNumber(row.durationMs),
+        success: asBoolean(row.success),
+        timestamp,
+        errorCode: asOptionalString(row.errorCode) ?? undefined,
+        tenantId: asOptionalString(row.tenantId) ?? undefined,
+        traceId: asOptionalString(row.traceId) ?? undefined,
+        actorId: asOptionalString(row.actorId) ?? undefined,
+        metadata: isRecord(row.metadata) ? row.metadata : undefined
+      }
+    ];
+  });
+}
+function mapAggregatedMetrics(result, operation, dateRange) {
+  const rows = mapRows(result);
+  const row = rows[0];
+  if (!row)
+    return null;
+  const totalCalls = asNumber(row.totalCalls);
+  if (!totalCalls)
+    return null;
+  const successCount = asNumber(row.successCount);
+  const errorCount = asNumber(row.errorCount);
+  const windowStart = toDate(dateRange.from) ?? new Date;
+  const windowEnd = toDate(dateRange.to) ?? new Date;
+  return {
+    operation,
+    totalCalls,
+    successRate: totalCalls ? successCount / totalCalls : 0,
+    errorRate: totalCalls ? errorCount / totalCalls : 0,
+    averageLatencyMs: asNumber(row.averageLatencyMs),
+    p95LatencyMs: asNumber(row.p95LatencyMs),
+    p99LatencyMs: asNumber(row.p99LatencyMs),
+    maxLatencyMs: asNumber(row.maxLatencyMs),
+    windowStart,
+    windowEnd,
+    topErrors: {}
+  };
+}
+function mergeSequences(result) {
+  const rows = mapRows(result);
+  const merged = new Map;
+  rows.forEach((row) => {
+    const sequences = row.sequences;
+    if (!Array.isArray(sequences))
+      return;
+    sequences.forEach((sequence) => {
+      if (!isRecord(sequence))
+        return;
+      const steps = Array.isArray(sequence.steps) ? sequence.steps.filter((step) => typeof step === "string") : [];
+      if (steps.length === 0)
+        return;
+      const tenantId = typeof sequence.tenantId === "string" ? sequence.tenantId : undefined;
+      const count = typeof sequence.count === "number" && Number.isFinite(sequence.count) ? sequence.count : 0;
+      const key = `${tenantId ?? "global"}:${steps.join(">")}`;
+      const existing = merged.get(key);
+      if (existing) {
+        existing.count += count;
+      } else {
+        merged.set(key, { steps, tenantId, count });
+      }
+    });
+  });
+  return [...merged.values()];
+}
+function mapRows(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return [];
+  }
+  const columns = result.columns;
+  return result.results.flatMap((row) => {
+    if (!Array.isArray(row))
+      return [];
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return [record];
+  });
+}
+function buildWindowRange(windowDays) {
+  const windowEnd = new Date;
+  const windowStart = new Date(windowEnd.getTime() - windowDays * 24 * 60 * 60 * 1000);
+  return {
+    from: windowStart,
+    to: windowEnd
+  };
+}
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asOptionalString(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed))
+      return parsed;
+  }
+  return 0;
+}
+function asBoolean(value) {
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number")
+    return value !== 0;
+  if (typeof value === "string")
+    return value.toLowerCase() === "true";
+  return false;
+}
+function asDate(value) {
+  if (value instanceof Date)
+    return value;
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime()))
+      return date;
+  }
+  return null;
+}
+function toIsoString(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
+}
+function toDate(value) {
+  if (!value)
+    return null;
+  return value instanceof Date ? value : new Date(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  PosthogBaselineReader
+};

package/dist/telemetry/posthog-telemetry.d.ts

@@ -0,0 +1,15 @@
+import type { AnalyticsProvider } from '@contractspec/lib.contracts/integrations/providers/analytics';
+import type { IntentAggregatorSnapshot, TelemetrySample } from '../intent/aggregator';
+export interface PosthogTelemetryProviderOptions {
+    eventPrefix?: string;
+    includeMetadata?: boolean;
+}
+export declare class PosthogTelemetryProvider {
+    private readonly provider;
+    private readonly eventPrefix;
+    private readonly includeMetadata;
+    constructor(provider: AnalyticsProvider, options?: PosthogTelemetryProviderOptions);
+    captureSample(sample: TelemetrySample): Promise<void>;
+    captureSnapshot(snapshot: IntentAggregatorSnapshot): Promise<void>;
+}
+//# sourceMappingURL=posthog-telemetry.d.ts.map

package/dist/telemetry/posthog-telemetry.js

@@ -0,0 +1,61 @@
+// @bun
+// src/telemetry/posthog-telemetry.ts
+class PosthogTelemetryProvider {
+  provider;
+  eventPrefix;
+  includeMetadata;
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.eventPrefix = options.eventPrefix ?? "observability";
+    this.includeMetadata = options.includeMetadata ?? false;
+  }
+  async captureSample(sample) {
+    await this.provider.capture({
+      distinctId: sample.actorId ?? sample.tenantId ?? "unknown",
+      event: `${this.eventPrefix}.operation`,
+      timestamp: sample.timestamp,
+      properties: {
+        operation: sample.operation.name,
+        version: sample.operation.version,
+        durationMs: sample.durationMs,
+        success: sample.success,
+        errorCode: sample.errorCode ?? null,
+        tenantId: sample.tenantId ?? null,
+        traceId: sample.traceId ?? null,
+        ...this.includeMetadata && sample.metadata ? { metadata: sample.metadata } : {}
+      }
+    });
+  }
+  async captureSnapshot(snapshot) {
+    await this.provider.capture({
+      distinctId: "system",
+      event: `${this.eventPrefix}.window`,
+      timestamp: snapshot.windowEnd ?? new Date,
+      properties: {
+        sampleCount: snapshot.sampleCount,
+        metricsCount: snapshot.metrics.length,
+        sequencesCount: snapshot.sequences.length,
+        windowStart: snapshot.windowStart?.toISOString() ?? null,
+        windowEnd: snapshot.windowEnd?.toISOString() ?? null,
+        ...this.includeMetadata ? {
+          metrics: snapshot.metrics.map((metric) => ({
+            operation: metric.operation.name,
+            version: metric.operation.version,
+            totalCalls: metric.totalCalls,
+            successRate: metric.successRate,
+            errorRate: metric.errorRate,
+            averageLatencyMs: metric.averageLatencyMs,
+            p95LatencyMs: metric.p95LatencyMs,
+            p99LatencyMs: metric.p99LatencyMs,
+            maxLatencyMs: metric.maxLatencyMs,
+            topErrors: metric.topErrors
+          })),
+          sequences: snapshot.sequences
+        } : {}
+      }
+    });
+  }
+}
+export {
+  PosthogTelemetryProvider
+};

package/dist/tracing/index.d.ts

@@ -0,0 +1,5 @@
+import { type Span, type Tracer } from '@opentelemetry/api';
+export declare function getTracer(name?: string): Tracer;
+export declare function traceAsync<T>(name: string, fn: (span: Span) => Promise<T>, tracerName?: string): Promise<T>;
+export declare function traceSync<T>(name: string, fn: (span: Span) => T, tracerName?: string): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/tracing/index.js

@@ -0,0 +1,53 @@
+// @bun
+// src/tracing/index.ts
+import {
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+var DEFAULT_TRACER_NAME = "@contractspec/lib.observability";
+function getTracer(name = DEFAULT_TRACER_NAME) {
+  return trace.getTracer(name);
+}
+async function traceAsync(name, fn, tracerName) {
+  const tracer = getTracer(tracerName);
+  return tracer.startActiveSpan(name, async (span) => {
+    try {
+      const result = await fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+function traceSync(name, fn, tracerName) {
+  const tracer = getTracer(tracerName);
+  return tracer.startActiveSpan(name, (span) => {
+    try {
+      const result = fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+export {
+  traceSync,
+  traceAsync,
+  getTracer
+};

package/dist/tracing/middleware.d.ts

@@ -0,0 +1,15 @@
+import type { TelemetrySample } from '../intent/aggregator';
+export interface TracingMiddlewareOptions {
+    resolveOperation?: (input: {
+        req: Request;
+        res?: Response;
+    }) => {
+        name: string;
+        version: string;
+    } | undefined;
+    onSample?: (sample: TelemetrySample) => void;
+    tenantResolver?: (req: Request) => string | undefined;
+    actorResolver?: (req: Request) => string | undefined;
+}
+export declare function createTracingMiddleware(options?: TracingMiddlewareOptions): (req: Request, next: () => Promise<Response>) => Promise<Response>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/tracing/middleware.js

@@ -0,0 +1,151 @@
+// @bun
+// src/tracing/index.ts
+import {
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+var DEFAULT_TRACER_NAME = "@contractspec/lib.observability";
+function getTracer(name = DEFAULT_TRACER_NAME) {
+  return trace.getTracer(name);
+}
+async function traceAsync(name, fn, tracerName) {
+  const tracer = getTracer(tracerName);
+  return tracer.startActiveSpan(name, async (span) => {
+    try {
+      const result = await fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+function traceSync(name, fn, tracerName) {
+  const tracer = getTracer(tracerName);
+  return tracer.startActiveSpan(name, (span) => {
+    try {
+      const result = fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+// src/metrics/index.ts
+import {
+  metrics
+} from "@opentelemetry/api";
+var DEFAULT_METER_NAME = "@contractspec/lib.observability";
+function getMeter(name = DEFAULT_METER_NAME) {
+  return metrics.getMeter(name);
+}
+function createCounter(name, description, meterName) {
+  return getMeter(meterName).createCounter(name, { description });
+}
+function createUpDownCounter(name, description, meterName) {
+  return getMeter(meterName).createUpDownCounter(name, { description });
+}
+function createHistogram(name, description, meterName) {
+  return getMeter(meterName).createHistogram(name, { description });
+}
+var standardMetrics = {
+  httpRequests: createCounter("http_requests_total", "Total HTTP requests"),
+  httpDuration: createHistogram("http_request_duration_seconds", "HTTP request duration"),
+  operationErrors: createCounter("operation_errors_total", "Total operation errors"),
+  workflowDuration: createHistogram("workflow_duration_seconds", "Workflow execution duration")
+};
+
+// src/tracing/middleware.ts
+function createTracingMiddleware(options = {}) {
+  return async (req, next) => {
+    const method = req.method;
+    const url = new URL(req.url);
+    const path = url.pathname;
+    standardMetrics.httpRequests.add(1, { method, path });
+    const startTime = performance.now();
+    return traceAsync(`HTTP ${method} ${path}`, async (span) => {
+      span.setAttribute("http.method", method);
+      span.setAttribute("http.url", req.url);
+      try {
+        const response = await next();
+        span.setAttribute("http.status_code", response.status);
+        const duration = (performance.now() - startTime) / 1000;
+        standardMetrics.httpDuration.record(duration, {
+          method,
+          path,
+          status: response.status.toString()
+        });
+        emitTelemetrySample({
+          req,
+          res: response,
+          span,
+          success: true,
+          durationMs: duration * 1000,
+          options
+        });
+        return response;
+      } catch (error) {
+        standardMetrics.operationErrors.add(1, { method, path });
+        emitTelemetrySample({
+          req,
+          span,
+          success: false,
+          durationMs: performance.now() - startTime,
+          error,
+          options
+        });
+        throw error;
+      }
+    });
+  };
+}
+function emitTelemetrySample({
+  req,
+  res,
+  span,
+  success,
+  durationMs,
+  error,
+  options
+}) {
+  if (!options.onSample || !options.resolveOperation)
+    return;
+  const operation = options.resolveOperation({ req, res });
+  if (!operation)
+    return;
+  const sample = {
+    operation,
+    durationMs,
+    success,
+    timestamp: new Date,
+    errorCode: !success && error instanceof Error ? error.name : success ? undefined : "unknown",
+    tenantId: options.tenantResolver?.(req),
+    actorId: options.actorResolver?.(req),
+    traceId: span.spanContext().traceId,
+    metadata: {
+      method: req.method,
+      path: new URL(req.url).pathname,
+      status: res?.status
+    }
+  };
+  options.onSample(sample);
+}
+export {
+  createTracingMiddleware
+};