@schedulespark/observability 0.0.2-beta-1-0-0

package/dist/node/redact.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Recursively redacts values whose key looks like a secret (authorization headers,
+ * cookies, passwords, tokens, API keys). Applied by default to any context object
+ * before it's persisted, since events are written straight into the host's own
+ * database.
+ */
+export declare function redactSecrets<T>(value: T): T;

package/dist/node/redact.js

@@ -0,0 +1,26 @@
+const SECRET_KEY_PATTERN = /authorization|cookie|password|secret|token|api[-_]?key/i;
+/**
+ * Recursively redacts values whose key looks like a secret (authorization headers,
+ * cookies, passwords, tokens, API keys). Applied by default to any context object
+ * before it's persisted, since events are written straight into the host's own
+ * database.
+ */
+export function redactSecrets(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecrets(item));
+    }
+    if (value !== null && typeof value === "object") {
+        return redactObject(value);
+    }
+    return value;
+}
+/**
+ * Redacts secret-looking keys on a plain object, recursing into nested values.
+ */
+function redactObject(input) {
+    const result = {};
+    for (const [key, val] of Object.entries(input)) {
+        result[key] = SECRET_KEY_PATTERN.test(key) ? "[redacted]" : redactSecrets(val);
+    }
+    return result;
+}

package/dist/node/tracing.d.ts

@@ -0,0 +1,28 @@
+import type { CaptureQueue } from "./queue.js";
+import type { RecordedSpan, SpanStatus } from "../core/index.js";
+/**
+ * A child operation within a transaction. Basic tracing only supports one level of
+ * nesting — a span can't start further spans of its own.
+ */
+export interface Span {
+    finish: (status?: SpanStatus) => void;
+}
+/**
+ * A root timed operation (e.g. one tRPC procedure call, one HTTP request).
+ */
+export interface Transaction {
+    startSpan: (name: string, tags?: Record<string, string>) => Span;
+    finish: (status?: SpanStatus) => void;
+}
+/**
+ * Starts new transactions, all sharing one underlying span queue.
+ */
+export interface Tracer {
+    startTransaction: (name: string, tags?: Record<string, string>) => Transaction;
+}
+/**
+ * Creates a tracer bound to a queue: `startTransaction` builds transactions/spans
+ * that enqueue themselves on `finish()`, batched and flushed the same non-blocking
+ * way captured events are.
+ */
+export declare function createTracer(queue: CaptureQueue<RecordedSpan>): Tracer;

package/dist/node/tracing.js

@@ -0,0 +1,49 @@
+import { randomUUID } from "node:crypto";
+const DEFAULT_STATUS = "ok";
+/**
+ * Creates a tracer bound to a queue: `startTransaction` builds transactions/spans
+ * that enqueue themselves on `finish()`, batched and flushed the same non-blocking
+ * way captured events are.
+ */
+export function createTracer(queue) {
+    return {
+        startTransaction(name, tags) {
+            const traceId = randomUUID();
+            return buildTimedOperation(queue, { traceId, parentId: null, name, tags });
+        }
+    };
+}
+/**
+ * Builds a span-like object (used for both transactions and their child spans):
+ * tracks its own start time and enqueues a `RecordedSpan` on `finish()`.
+ */
+function buildTimedOperation(queue, input) {
+    const id = randomUUID();
+    const startedAt = new Date();
+    const start = Date.now();
+    return {
+        startSpan(name, tags) {
+            return buildChildSpan(queue, { traceId: input.traceId, parentId: id, name, tags });
+        },
+        finish(status = DEFAULT_STATUS) {
+            queue.enqueue({
+                id,
+                traceId: input.traceId,
+                parentId: input.parentId,
+                name: input.name,
+                status,
+                startedAt: startedAt.toISOString(),
+                durationMs: Date.now() - start,
+                tags: input.tags ?? {}
+            });
+        }
+    };
+}
+/**
+ * Builds a leaf span — like `buildTimedOperation`, but without its own `startSpan`,
+ * since basic tracing caps nesting at one level.
+ */
+function buildChildSpan(queue, input) {
+    const { finish } = buildTimedOperation(queue, input);
+    return { finish };
+}

package/dist/storage/comments.d.ts

@@ -0,0 +1,13 @@
+import type { StorageHandle } from "./pool.js";
+import type { Comment } from "../core/index.js";
+/**
+ * Adds a free-text comment to an issue.
+ */
+export declare function addComment(handle: StorageHandle, issueId: string, input: {
+    author: string;
+    body: string;
+}): Promise<Comment>;
+/**
+ * Lists an issue's comments, oldest first.
+ */
+export declare function listComments(handle: StorageHandle, issueId: string): Promise<Comment[]>;

package/dist/storage/comments.js

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { mapCommentRow } from "./rows.js";
+/**
+ * Adds a free-text comment to an issue.
+ */
+export async function addComment(handle, issueId, input) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.comments (id, issue_id, author, body, created_at)
+     VALUES ($1, $2, $3, $4, now())
+     RETURNING *`, [randomUUID(), issueId, input.author, input.body]);
+    return mapCommentRow(rows[0]);
+}
+/**
+ * Lists an issue's comments, oldest first.
+ */
+export async function listComments(handle, issueId) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.comments WHERE issue_id = $1 ORDER BY created_at ASC`, [issueId]);
+    return rows.map(mapCommentRow);
+}

package/dist/storage/index.d.ts

@@ -0,0 +1,31 @@
+import type { StorageHandle, StorageOptions } from "./pool.js";
+export { closeStorage, createStorage } from "./pool.js";
+export { migrate } from "./migrations.js";
+export { addComment, listComments } from "./comments.js";
+export { recordLog, listLogs } from "./logs.js";
+export { countEventsSince } from "./metrics.js";
+export { recordMetricPoint } from "./metrics-ingest.js";
+export { listMetricRollups, rollupMetrics } from "./metrics-rollup.js";
+export { createProject, findProjectByApiKey, listProjects } from "./projects.js";
+export { assignIssue, getIssueWithEvents, listIssues, recordEvent, updateIssueStatus } from "./queries.js";
+export { pruneEvents, pruneLogs } from "./retention.js";
+export { createSavedView, deleteSavedView, listSavedViews } from "./saved-views.js";
+export { listTransactions, recordSpan } from "./spans.js";
+export type { StorageHandle, StorageOptions } from "./pool.js";
+export type { ListMetricRollupsOptions, RollupMetricsOptions, RollupMetricsResult } from "./metrics-rollup.js";
+export type { RecordEventResult } from "./queries.js";
+export type { PruneLogsResult, PruneResult } from "./retention.js";
+/**
+ * Opens a storage handle and waits for its migrations to finish before returning it.
+ * Prefer this over `createStorage` when you'd rather surface a migration failure
+ * immediately (e.g. the standalone CLI) instead of letting it happen in the
+ * background — `createStorage` already migrates in the background either way, so
+ * this is just `createStorage` plus an explicit `await handle.ready`.
+ */
+export declare function initStorage(options: StorageOptions): Promise<StorageHandle>;
+/**
+ * Waits for an already-open storage handle's migrations to finish. Useful when a
+ * host application wants to log a migration failure without blocking route
+ * registration on it.
+ */
+export declare function migrateHandle(handle: StorageHandle): Promise<void>;

package/dist/storage/index.js

@@ -0,0 +1,33 @@
+import { createStorage } from "./pool.js";
+export { closeStorage, createStorage } from "./pool.js";
+export { migrate } from "./migrations.js";
+export { addComment, listComments } from "./comments.js";
+export { recordLog, listLogs } from "./logs.js";
+export { countEventsSince } from "./metrics.js";
+export { recordMetricPoint } from "./metrics-ingest.js";
+export { listMetricRollups, rollupMetrics } from "./metrics-rollup.js";
+export { createProject, findProjectByApiKey, listProjects } from "./projects.js";
+export { assignIssue, getIssueWithEvents, listIssues, recordEvent, updateIssueStatus } from "./queries.js";
+export { pruneEvents, pruneLogs } from "./retention.js";
+export { createSavedView, deleteSavedView, listSavedViews } from "./saved-views.js";
+export { listTransactions, recordSpan } from "./spans.js";
+/**
+ * Opens a storage handle and waits for its migrations to finish before returning it.
+ * Prefer this over `createStorage` when you'd rather surface a migration failure
+ * immediately (e.g. the standalone CLI) instead of letting it happen in the
+ * background — `createStorage` already migrates in the background either way, so
+ * this is just `createStorage` plus an explicit `await handle.ready`.
+ */
+export async function initStorage(options) {
+    const handle = createStorage(options);
+    await handle.ready;
+    return handle;
+}
+/**
+ * Waits for an already-open storage handle's migrations to finish. Useful when a
+ * host application wants to log a migration failure without blocking route
+ * registration on it.
+ */
+export function migrateHandle(handle) {
+    return handle.ready;
+}

package/dist/storage/logs.d.ts

@@ -0,0 +1,19 @@
+import type { StorageHandle } from "./pool.js";
+import type { LogEntry, LogLevel } from "../core/index.js";
+/**
+ * Records a single structured log line. Defaults to the `"default"` project like
+ * every other capture path when the caller doesn't configure multi-project support.
+ */
+export declare function recordLog(handle: StorageHandle, input: {
+    level: LogLevel;
+    message: string;
+    context?: Record<string, unknown>;
+}, projectId?: string): Promise<LogEntry>;
+/**
+ * Lists the most recently logged lines, optionally filtered by level and/or project.
+ */
+export declare function listLogs(handle: StorageHandle, options?: {
+    level?: LogLevel;
+    projectId?: string;
+    limit?: number;
+}): Promise<LogEntry[]>;

package/dist/storage/logs.js

@@ -0,0 +1,35 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_PROJECT_ID } from "../core/index.js";
+import { mapLogRow } from "./rows.js";
+const DEFAULT_LOG_LIST_LIMIT = 100;
+/**
+ * Records a single structured log line. Defaults to the `"default"` project like
+ * every other capture path when the caller doesn't configure multi-project support.
+ */
+export async function recordLog(handle, input, projectId = DEFAULT_PROJECT_ID) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.logs (id, project_id, level, message, context, logged_at)
+     VALUES ($1, $2, $3, $4, $5, now())
+     RETURNING *`, [randomUUID(), projectId, input.level, input.message, input.context ?? {}]);
+    return mapLogRow(rows[0]);
+}
+/**
+ * Lists the most recently logged lines, optionally filtered by level and/or project.
+ */
+export async function listLogs(handle, options = {}) {
+    await handle.ready;
+    const params = [];
+    const conditions = [];
+    if (options.projectId) {
+        params.push(options.projectId);
+        conditions.push(`project_id = $${String(params.length)}`);
+    }
+    if (options.level) {
+        params.push(options.level);
+        conditions.push(`level = $${String(params.length)}`);
+    }
+    params.push(options.limit ?? DEFAULT_LOG_LIST_LIMIT);
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.logs ${where} ORDER BY logged_at DESC LIMIT $${String(params.length)}`, params);
+    return rows.map(mapLogRow);
+}

package/dist/storage/metrics-ingest.d.ts

@@ -0,0 +1,14 @@
+import type { StorageHandle } from "./pool.js";
+import type { MetricKind, MetricPoint } from "../core/index.js";
+/**
+ * Records a single raw metric data point. Defaults to the `"default"` project like
+ * every other capture path. Named `metrics-ingest.ts` (not `metrics.ts`, which already
+ * exists for `countEventsSince`/spike alerting) to avoid colliding in both filename
+ * and intent with that unrelated module.
+ */
+export declare function recordMetricPoint(handle: StorageHandle, point: {
+    name: string;
+    kind: MetricKind;
+    value: number;
+    tags?: Record<string, string>;
+}, projectId?: string): Promise<MetricPoint>;

package/dist/storage/metrics-ingest.js

@@ -0,0 +1,16 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_PROJECT_ID } from "../core/index.js";
+import { mapMetricPointRow } from "./rows.js";
+/**
+ * Records a single raw metric data point. Defaults to the `"default"` project like
+ * every other capture path. Named `metrics-ingest.ts` (not `metrics.ts`, which already
+ * exists for `countEventsSince`/spike alerting) to avoid colliding in both filename
+ * and intent with that unrelated module.
+ */
+export async function recordMetricPoint(handle, point, projectId = DEFAULT_PROJECT_ID) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.metric_points_raw (id, project_id, name, kind, value, tags, recorded_at)
+     VALUES ($1, $2, $3, $4, $5, $6, now())
+     RETURNING *`, [randomUUID(), projectId, point.name, point.kind, point.value, point.tags ?? {}]);
+    return mapMetricPointRow(rows[0]);
+}

package/dist/storage/metrics-rollup.d.ts

@@ -0,0 +1,38 @@
+import type { StorageHandle } from "./pool.js";
+import type { MetricBucketSize, MetricRollup } from "../core/index.js";
+/**
+ * Options controlling a single rollup run.
+ */
+export interface RollupMetricsOptions {
+    bucketSizes?: MetricBucketSize[];
+    rawRetentionDays?: number;
+}
+/**
+ * Outcome of a single rollup run.
+ */
+export interface RollupMetricsResult {
+    rolledUpBuckets: number;
+    prunedRawPoints: number;
+}
+/**
+ * Re-aggregates every raw metric point into `metric_rollups`, one bucket size at a
+ * time, then prunes raw points older than the retention window. Each bucket is a
+ * full replace (not an addition) of `sum`/`count`/`min`/`max` from the current raw
+ * data, so rerunning this job is always safe — it never double-counts a point that
+ * was already rolled up in a previous run.
+ */
+export declare function rollupMetrics(handle: StorageHandle, options?: RollupMetricsOptions): Promise<RollupMetricsResult>;
+/**
+ * Options for listing metric rollups.
+ */
+export interface ListMetricRollupsOptions {
+    bucketSize?: MetricBucketSize;
+    projectId?: string;
+    limit?: number;
+}
+/**
+ * Lists the most recent rollup bucket per `(name, tags)` combination, optionally
+ * filtered by bucket size/project. Only the latest bucket per metric is returned —
+ * this backs a simple "current state" table view, not a time-series chart.
+ */
+export declare function listMetricRollups(handle: StorageHandle, options?: ListMetricRollupsOptions): Promise<MetricRollup[]>;

package/dist/storage/metrics-rollup.js

@@ -0,0 +1,80 @@
+import { mapMetricRollupRow } from "./rows.js";
+const DEFAULT_BUCKET_SIZES = ["hour", "day"];
+const DEFAULT_RAW_RETENTION_DAYS = 3;
+const DEFAULT_ROLLUP_LIST_LIMIT = 200;
+/**
+ * Re-aggregates every raw metric point into `metric_rollups`, one bucket size at a
+ * time, then prunes raw points older than the retention window. Each bucket is a
+ * full replace (not an addition) of `sum`/`count`/`min`/`max` from the current raw
+ * data, so rerunning this job is always safe — it never double-counts a point that
+ * was already rolled up in a previous run.
+ */
+export async function rollupMetrics(handle, options = {}) {
+    await handle.ready;
+    const bucketSizes = options.bucketSizes ?? DEFAULT_BUCKET_SIZES;
+    const rawRetentionDays = options.rawRetentionDays ?? DEFAULT_RAW_RETENTION_DAYS;
+    if (!Number.isInteger(rawRetentionDays) || rawRetentionDays <= 0) {
+        throw new Error(`rawRetentionDays must be a positive integer, got ${String(rawRetentionDays)}`);
+    }
+    let rolledUpBuckets = 0;
+    for (const bucketSize of bucketSizes) {
+        rolledUpBuckets += await rollupBucketSize(handle, bucketSize);
+    }
+    const { rowCount } = await handle.pool.query(`DELETE FROM ${handle.quotedSchema}.metric_points_raw WHERE recorded_at < now() - ($1 || ' days')::interval`, [rawRetentionDays]);
+    return { rolledUpBuckets, prunedRawPoints: rowCount ?? 0 };
+}
+/**
+ * Rolls up every raw point into one bucket size, upserting each `(project, name,
+ * kind, tags, bucket)` combination.
+ */
+async function rollupBucketSize(handle, bucketSize) {
+    const { rowCount } = await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.metric_rollups
+       (id, project_id, name, kind, bucket_start, bucket_size, tags, sum, count, min, max)
+     SELECT
+       gen_random_uuid()::text,
+       project_id,
+       name,
+       kind,
+       date_trunc($1, recorded_at),
+       $1,
+       tags,
+       sum(value),
+       count(*),
+       min(value),
+       max(value)
+     FROM ${handle.quotedSchema}.metric_points_raw
+     GROUP BY project_id, name, kind, date_trunc($1, recorded_at), tags
+     ON CONFLICT (project_id, name, tags, bucket_start, bucket_size)
+     DO UPDATE SET
+       sum = EXCLUDED.sum,
+       count = EXCLUDED.count,
+       min = EXCLUDED.min,
+       max = EXCLUDED.max`, [bucketSize]);
+    return rowCount ?? 0;
+}
+/**
+ * Lists the most recent rollup bucket per `(name, tags)` combination, optionally
+ * filtered by bucket size/project. Only the latest bucket per metric is returned —
+ * this backs a simple "current state" table view, not a time-series chart.
+ */
+export async function listMetricRollups(handle, options = {}) {
+    await handle.ready;
+    const conditions = [];
+    const params = [];
+    if (options.bucketSize) {
+        params.push(options.bucketSize);
+        conditions.push(`bucket_size = $${String(params.length)}`);
+    }
+    if (options.projectId) {
+        params.push(options.projectId);
+        conditions.push(`project_id = $${String(params.length)}`);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    params.push(options.limit ?? DEFAULT_ROLLUP_LIST_LIMIT);
+    const { rows } = await handle.pool.query(`SELECT DISTINCT ON (name, tags) *
+     FROM ${handle.quotedSchema}.metric_rollups
+     ${where}
+     ORDER BY name, tags, bucket_start DESC
+     LIMIT $${String(params.length)}`, params);
+    return rows.map(mapMetricRollupRow);
+}

package/dist/storage/metrics.d.ts

@@ -0,0 +1,7 @@
+import type { StorageHandle } from "./pool.js";
+import type { EventLevel } from "../core/index.js";
+/**
+ * Counts events at a given level captured within the last `windowMinutes`. Used by
+ * the spike alert monitor; not exposed in the dashboard yet.
+ */
+export declare function countEventsSince(handle: StorageHandle, level: EventLevel, windowMinutes: number): Promise<number>;

package/dist/storage/metrics.js

@@ -0,0 +1,10 @@
+/**
+ * Counts events at a given level captured within the last `windowMinutes`. Used by
+ * the spike alert monitor; not exposed in the dashboard yet.
+ */
+export async function countEventsSince(handle, level, windowMinutes) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`SELECT count(*)::text AS count FROM ${handle.quotedSchema}.events
+     WHERE level = $1 AND captured_at > now() - ($2 || ' minutes')::interval`, [level, windowMinutes]);
+    return Number(rows[0]?.count ?? "0");
+}

package/dist/storage/migrations.d.ts

@@ -0,0 +1,17 @@
+import type { Pool } from "pg";
+/**
+ * A single versioned, forward-only schema migration.
+ */
+export interface Migration {
+    id: string;
+    sql: (quotedSchema: string) => string;
+}
+export declare const migrations: Migration[];
+/**
+ * Ensures the observability schema, migration-tracking table, and all pending
+ * migrations exist. Safe to call concurrently from multiple pools/processes against
+ * the same database (e.g. a Node SDK client and a dashboard server booting at the same
+ * time): a Postgres advisory lock, scoped to the schema name, serializes migration
+ * runs so `CREATE SCHEMA IF NOT EXISTS` races can never produce a duplicate-key error.
+ */
+export declare function migrate(pool: Pool, quotedSchema: string): Promise<void>;