silgi 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/integrations/drizzle/index.mjs

@@ -0,0 +1,286 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/integrations/drizzle/index.ts
+/**
+* Silgi + Drizzle ORM tracing integration.
+*
+* Wraps Drizzle session methods to intercept every query and record
+* spans in silgi analytics. Uses AsyncLocalStorage to bridge request
+* context to the DB layer.
+*
+* Patching priority (inspired by @kubiks/otel-drizzle):
+* 1. `db.session.prepareQuery` — wrap returned prepared.execute (main ORM path)
+* 2. `db.session.query` — for direct string queries
+* 3. `db.session.transaction` — re-instrument tx session per transaction call
+* 4. `db.$client.query` or `db.$client.execute` — fallback to raw driver
+* 5. `db._.session.execute` — deep internal fallback
+*
+* Instance patching, NOT prototype patching. Idempotent via flag.
+*
+* @example
+* ```ts
+* import { instrumentDrizzle, withSilgiCtx } from 'silgi/drizzle'
+*
+* const db = instrumentDrizzle(drizzle(url, { schema }), {
+*   dbName: 'ecommerce',
+*   peerName: 'db.example.com',
+*   peerPort: 5432,
+* })
+*
+* const listUsers = s.$resolve(async ({ ctx }) => {
+*   return withSilgiCtx(ctx, () => db.select().from(users))
+* })
+* ```
+*/
+const ctxStorage = new AsyncLocalStorage();
+const INSTRUMENTED = "__silgiDrizzleInstrumented";
+const DEFAULT_DB_SYSTEM = "postgresql";
+const DEFAULT_MAX_QUERY_LENGTH = 1e3;
+/**
+* Instrument a Drizzle db instance to record query spans in silgi analytics.
+* Returns the same db instance (mutated). Safe to call multiple times.
+*/
+function instrumentDrizzle(db, config) {
+	if (!db || db[INSTRUMENTED]) return db;
+	const cfg = resolveConfig(config);
+	let instrumented = false;
+	const session = db.session ?? db._?.session;
+	if (session) instrumented = patchSession(session, cfg, false);
+	if (!instrumented && db.$client) instrumented = patchRawClient(db.$client, cfg);
+	if (!instrumented && db._?.session && typeof db._.session.execute === "function") instrumented = patchSessionExecute(db._.session, cfg);
+	if (!instrumented) {
+		console.warn("[silgi/drizzle] Could not find any patchable method — skipping instrumentation");
+		return db;
+	}
+	db[INSTRUMENTED] = true;
+	return db;
+}
+/**
+* Run a function with silgi context available to instrumented Drizzle instances.
+* All Drizzle queries inside `fn` will be recorded as trace spans.
+*/
+function withSilgiCtx(ctx, fn) {
+	return ctxStorage.run(ctx, fn);
+}
+function resolveConfig(config) {
+	return {
+		dbSystem: config?.dbSystem ?? DEFAULT_DB_SYSTEM,
+		dbName: config?.dbName,
+		captureQueryText: config?.captureQueryText !== false,
+		maxQueryTextLength: config?.maxQueryTextLength ?? DEFAULT_MAX_QUERY_LENGTH,
+		peerName: config?.peerName,
+		peerPort: config?.peerPort
+	};
+}
+/**
+* Patch session.prepareQuery, session.query, and session.transaction.
+* Returns true if any method was patched.
+*/
+function patchSession(session, cfg, isTx) {
+	const flagSuffix = isTx ? "_tx" : "";
+	if (session[INSTRUMENTED + flagSuffix]) return true;
+	let patched = false;
+	if (typeof session.prepareQuery === "function") {
+		const originalPrepareQuery = session.prepareQuery.bind(session);
+		session.prepareQuery = function patchedPrepareQuery(...args) {
+			const prepared = originalPrepareQuery.apply(this, args);
+			if (!prepared || typeof prepared.execute !== "function") return prepared;
+			const reqTrace = ctxStorage.getStore()?.__analyticsTrace;
+			if (!reqTrace) return prepared;
+			const queryText = extractQueryText(args[0]) ?? prepared.rawQueryConfig?.text ?? prepared.queryConfig?.text ?? null;
+			const originalExecute = prepared.execute.bind(prepared);
+			prepared.execute = function tracedExecute(...execArgs) {
+				return traceExecution(reqTrace, cfg, queryText, isTx, originalExecute, this, execArgs);
+			};
+			return prepared;
+		};
+		patched = true;
+	}
+	if (typeof session.query === "function") {
+		const originalQuery = session.query.bind(session);
+		session.query = function patchedQuery(queryString, params) {
+			const reqTrace = ctxStorage.getStore()?.__analyticsTrace;
+			if (!reqTrace) return originalQuery.call(this, queryString, params);
+			return traceExecution(reqTrace, cfg, queryString ?? null, isTx, originalQuery, this, [queryString, params]);
+		};
+		patched = true;
+	}
+	if (!isTx && typeof session.transaction === "function") {
+		const originalTransaction = session.transaction.bind(session);
+		session.transaction = function patchedTransaction(callback, txConfig) {
+			return originalTransaction.call(this, (tx) => {
+				const txSession = tx.session ?? tx;
+				if (txSession && typeof txSession.prepareQuery === "function") patchSession(txSession, cfg, true);
+				return callback(tx);
+			}, txConfig);
+		};
+		patched = true;
+	}
+	if (patched) session[INSTRUMENTED + flagSuffix] = true;
+	return patched;
+}
+/**
+* Patch $client.query or $client.execute as fallback for raw driver access.
+*/
+function patchRawClient(client, cfg) {
+	if (!client || client[INSTRUMENTED]) return false;
+	const methodName = typeof client.query === "function" ? "query" : typeof client.execute === "function" ? "execute" : null;
+	if (!methodName) return false;
+	const originalMethod = client[methodName].bind(client);
+	client[methodName] = function patchedClientMethod(...args) {
+		const reqTrace = ctxStorage.getStore()?.__analyticsTrace;
+		if (!reqTrace) return originalMethod.apply(this, args);
+		return traceExecution(reqTrace, cfg, extractQueryText(args[0]) ?? null, false, originalMethod, this, args);
+	};
+	client[INSTRUMENTED] = true;
+	return true;
+}
+/**
+* Patch db._.session.execute as deep internal fallback.
+*/
+function patchSessionExecute(session, cfg) {
+	if (session[INSTRUMENTED]) return false;
+	const originalExecute = session.execute.bind(session);
+	session.execute = function patchedDeepExecute(...args) {
+		const reqTrace = ctxStorage.getStore()?.__analyticsTrace;
+		if (!reqTrace) return originalExecute.apply(this, args);
+		return traceExecution(reqTrace, cfg, extractQueryText(args[0]) ?? null, false, originalExecute, this, args);
+	};
+	session[INSTRUMENTED] = true;
+	return true;
+}
+/**
+* Execute a function and record a trace span with timing, attributes, and error handling.
+* Handles both sync and async (Promise) return values.
+*/
+function traceExecution(reqTrace, cfg, queryText, isTx, fn, thisArg, args) {
+	const spanName = buildSpanName(queryText, isTx);
+	const attributes = buildAttributes(cfg, queryText, isTx);
+	const start = performance.now();
+	try {
+		const result = fn.apply(thisArg, args);
+		if (result instanceof Promise) return result.then((value) => {
+			pushSpan(reqTrace, spanName, start, queryText, cfg, attributes, void 0);
+			return value;
+		}, (error) => {
+			pushSpan(reqTrace, spanName, start, queryText, cfg, attributes, error);
+			throw error;
+		});
+		pushSpan(reqTrace, spanName, start, queryText, cfg, attributes, void 0);
+		return result;
+	} catch (error) {
+		pushSpan(reqTrace, spanName, start, queryText, cfg, attributes, error);
+		throw error;
+	}
+}
+function pushSpan(reqTrace, name, start, queryText, cfg, attributes, error) {
+	const detail = cfg.captureQueryText && queryText ? truncateQuery(queryText, cfg.maxQueryTextLength) : void 0;
+	reqTrace.spans.push({
+		name,
+		kind: "db",
+		durationMs: round(performance.now() - start),
+		startOffsetMs: round(start - reqTrace.t0),
+		detail,
+		attributes,
+		error: error ? formatError(error) : void 0
+	});
+}
+function buildAttributes(cfg, queryText, isTx) {
+	const attrs = { "db.system": cfg.dbSystem };
+	if (cfg.dbName) attrs["db.name"] = cfg.dbName;
+	if (cfg.peerName) attrs["net.peer.name"] = cfg.peerName;
+	if (cfg.peerPort) attrs["net.peer.port"] = cfg.peerPort;
+	if (isTx) attrs["db.transaction"] = true;
+	if (queryText) {
+		const op = extractOperationName(queryText);
+		if (op) attrs["db.operation"] = op;
+		if (cfg.captureQueryText) attrs["db.statement"] = truncateQuery(queryText, cfg.maxQueryTextLength);
+	}
+	return attrs;
+}
+function buildSpanName(queryText, isTx) {
+	const prefix = isTx ? "db.tx" : "db";
+	if (!queryText) return `${prefix}.query`;
+	const opInfo = extractOperationInfo(queryText);
+	if (!opInfo) return `${prefix}.query`;
+	return opInfo.table ? `${prefix}.${opInfo.op}.${opInfo.table}` : `${prefix}.${opInfo.op}`;
+}
+/**
+* Extract SQL text from various query argument formats:
+* - Plain string
+* - { sql: string }
+* - { text: string }
+* - { queryString: string }
+* - { queryChunks: ..., sql: string }
+*/
+function extractQueryText(queryArg) {
+	if (typeof queryArg === "string") return queryArg;
+	if (queryArg && typeof queryArg === "object") {
+		const q = queryArg;
+		if (typeof q.sql === "string") return q.sql;
+		if (typeof q.text === "string") return q.text;
+		if (typeof q.queryString === "string") return q.queryString;
+		if (typeof q.queryChunks === "object" && typeof q.sql === "string") return q.sql;
+	}
+	return null;
+}
+function truncateQuery(text, maxLength) {
+	if (text.length <= maxLength) return text;
+	return text.slice(0, maxLength) + "...";
+}
+/**
+* Parse the SQL operation and target table from query text.
+* Returns lowercase op name and table for span naming.
+*/
+function extractOperationInfo(sql) {
+	const upper = sql.trimStart().toUpperCase();
+	if (upper.startsWith("SELECT")) return {
+		op: "select",
+		table: matchTable(sql, /from\s+"?(\w+)"?/i)
+	};
+	if (upper.startsWith("INSERT")) return {
+		op: "insert",
+		table: matchTable(sql, /into\s+"?(\w+)"?/i)
+	};
+	if (upper.startsWith("UPDATE")) return {
+		op: "update",
+		table: matchTable(sql, /update\s+"?(\w+)"?/i)
+	};
+	if (upper.startsWith("DELETE")) return {
+		op: "delete",
+		table: matchTable(sql, /from\s+"?(\w+)"?/i)
+	};
+	if (upper.startsWith("BEGIN") || upper.startsWith("START TRANSACTION")) return {
+		op: "begin",
+		table: null
+	};
+	if (upper.startsWith("COMMIT")) return {
+		op: "commit",
+		table: null
+	};
+	if (upper.startsWith("ROLLBACK")) return {
+		op: "rollback",
+		table: null
+	};
+	return null;
+}
+/**
+* Extract uppercase operation name for the db.operation attribute.
+*/
+function extractOperationName(sql) {
+	const trimmed = sql.trimStart();
+	const match = /^(\w+)/u.exec(trimmed);
+	return match ? match[1].toUpperCase() : null;
+}
+function matchTable(sql, pattern) {
+	const m = sql.match(pattern);
+	return m ? m[1] : null;
+}
+function formatError(error) {
+	if (error instanceof Error) return error.stack ?? `${error.name}: ${error.message}`;
+	return String(error);
+}
+function round(n) {
+	return Math.round(n * 100) / 100;
+}
+//#endregion
+export { instrumentDrizzle, withSilgiCtx };

package/dist/plugins/analytics.d.mts

@@ -23,7 +23,11 @@ interface TraceSpan {
   durationMs: number;
   startOffsetMs?: number;
   detail?: string;
+  input?: unknown;
+  output?: unknown;
   error?: string;
+  /** Structured key-value attributes (db.name, auth.operation, user.id, etc.) */
+  attributes?: Record<string, string | number | boolean>;
 }
 interface ErrorEntry {
   id: number;
@@ -110,11 +114,22 @@ interface AnalyticsSnapshot {
   timeSeries: TimeWindow[];
 }
 declare class RequestTrace {
-  #private;
   spans: TraceSpan[];
+  /** Procedure-level input — set via `setProcedureInput()` or `trace(..., { procedure: { input } })` */
+  procedureInput: unknown;
+  /** Procedure-level output — set via `setProcedureOutput()` or `trace(..., { procedure: { output } })` */
+  procedureOutput: unknown;
+  /** @internal Start time — used by integrations (drizzle etc.) for span offset calculation */
+  readonly t0: number;
   trace<T>(name: string, fn: () => T | Promise<T>, opts?: {
     kind?: SpanKind;
     detail?: string;
+    input?: unknown;
+    output?: unknown | ((result: T) => unknown);
+    procedure?: {
+      input?: unknown;
+      output?: unknown | ((result: T) => unknown);
+    };
   }): Promise<T>;
   totalByKind(kind: SpanKind): number;
 }
@@ -134,6 +149,12 @@ declare class RequestTrace {
 declare function trace<T>(ctx: Record<string, unknown>, name: string, fn: () => T | Promise<T>, opts?: {
   kind?: SpanKind;
   detail?: string;
+  input?: unknown;
+  output?: unknown | ((result: T) => unknown);
+  procedure?: {
+    input?: unknown;
+    output?: unknown | ((result: T) => unknown);
+  };
 }): Promise<T>;
 declare class AnalyticsCollector {
   #private;

package/dist/plugins/analytics.mjs

@@ -65,7 +65,12 @@ function generateRequestId() {
 }
 var RequestTrace = class {
 	spans = [];
-	#t0 = performance.now();
+	/** Procedure-level input — set via `setProcedureInput()` or `trace(..., { procedure: { input } })` */
+	procedureInput = void 0;
+	/** Procedure-level output — set via `setProcedureOutput()` or `trace(..., { procedure: { output } })` */
+	procedureOutput = void 0;
+	/** @internal Start time — used by integrations (drizzle etc.) for span offset calculation */
+	t0 = performance.now();
 	async trace(name, fn, opts) {
 		const start = performance.now();
 		const kind = opts?.kind ?? guessKind(name);
@@ -75,19 +80,28 @@ var RequestTrace = class {
 				name,
 				kind,
 				durationMs: round(performance.now() - start),
-				startOffsetMs: round(start - this.#t0),
-				detail: opts?.detail
+				startOffsetMs: round(start - this.t0),
+				detail: opts?.detail,
+				input: opts?.input,
+				output: typeof opts?.output === "function" ? opts.output(result) : opts?.output
 			});
+			if (opts?.procedure) {
+				if (opts.procedure.input !== void 0) this.procedureInput = opts.procedure.input;
+				const po = opts.procedure.output;
+				if (po !== void 0) this.procedureOutput = typeof po === "function" ? po(result) : po;
+			}
 			return result;
 		} catch (err) {
 			this.spans.push({
 				name,
 				kind,
 				durationMs: round(performance.now() - start),
-				startOffsetMs: round(start - this.#t0),
+				startOffsetMs: round(start - this.t0),
 				detail: opts?.detail,
+				input: opts?.input,
 				error: err instanceof Error ? err.message : String(err)
 			});
+			if (opts?.procedure?.input !== void 0) this.procedureInput = opts.procedure.input;
 			throw err;
 		}
 	}
@@ -277,7 +291,7 @@ var RequestAccumulator = class {
 	#collector;
 	constructor(request, collector) {
 		this.requestId = generateRequestId();
-		this.#t0 = performance.now();
+		this.t0 = performance.now();
 		this.#request = request;
 		this.#collector = collector;
 		const existing = parseCookie(request.headers.get("cookie"), SESSION_COOKIE);
@@ -300,7 +314,7 @@ var RequestAccumulator = class {
 	/** Flush with response headers extracted from the actual Response object. */
 	flushWithResponse(res) {
 		if (this.#procedures.length === 0) return;
-		const durationMs = round(performance.now() - this.#t0);
+		const durationMs = round(performance.now() - this.t0);
 		const headers = {};
 		this.#request.headers.forEach((v, k) => {
 			headers[k] = k === "authorization" || k === "cookie" ? "[REDACTED]" : v;