@unhandled/instrumentation-kysely 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @unhandled/instrumentation-kysely
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Traces [Kysely](https://kysely.dev) queries, streams and transactions, and exports `pg` pool gauges. Supports Kysely `^0.28.16` and `^0.29.6` with `PostgresDialect` (`pg`) and `PostgresJSDialect` (`kysely-postgres-js`).
+
+This package is manual only. It has no `/integration` entry, so the AdonisJS agent never enables it for you.
+
+## Install
+
+```sh
+npm i @unhandled/instrumentation-kysely
+```
+
+## Use
+
+Create the dialect after OpenTelemetry is initialised and pass the wrapped dialect to Kysely:
+
+```ts
+import { Kysely, PostgresDialect } from 'kysely'
+import pg from 'pg'
+import { observeDialect } from '@unhandled/instrumentation-kysely'
+
+const pool = new pg.Pool({ host, port, database, user, password, max: 10 })
+
+export const db = new Kysely<Database>({
+  dialect: observeDialect({
+    dialect: new PostgresDialect({ pool }),
+    dbSystem: 'postgresql',
+    connection: { host, port, database },
+  }),
+})
+```
+
+## Options
+
+| Option              | Default  | Effect                                                                                        |
+| ------------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `dialect`           | required | The dialect to wrap.                                                                          |
+| `dbSystem`          | required | Value of `db.system.name`, for example `postgresql`.                                          |
+| `recordQueryText`   | `true`   | `false` leaves `db.query.text` off every span.                                                |
+| `recordErrors`      | `true`   | `false` keeps `ERROR` status but drops the status message and the exception event.            |
+| `requireParentSpan` | `false`  | Only create spans when a span is already active.                                              |
+| `connection`        | none     | `{ host, port, database }`, reported as `server.address`, `server.port` and `db.namespace`.   |
+
+SQL text and error messages can contain sensitive data. Query parameters are never recorded, but literals inlined in SQL are. Turn off `recordQueryText` and `recordErrors` if that matters.
+
+## Spans
+
+Every span is `CLIENT` kind. The name is `<OPERATION> <table>` (`SELECT users`), or just the operation when no table can be parsed, with the operation and table read from the SQL text. A transaction produces `BEGIN`, one span per query, then `COMMIT` or `ROLLBACK`. A stream is one span that lasts until the stream is drained, closed or fails.
+
+| Attribute            | Value                                                                   |
+| -------------------- | ----------------------------------------------------------------------- |
+| `db.system.name`     | `dbSystem`                                                              |
+| `db.query.text`      | SQL with placeholders, when `recordQueryText` is on                     |
+| `db.operation.name`  | Upper-cased first keyword, for example `SELECT`                         |
+| `db.collection.name` | Target table when it can be parsed                                      |
+| `db.namespace`       | `connection.database`                                                   |
+| `server.address`     | `connection.host`                                                       |
+| `server.port`        | `connection.port`                                                       |
+| `db.transaction`     | `true` on `BEGIN`, `COMMIT`, `ROLLBACK` and queries inside a transaction |
+| `error.type`         | Error class name on failures                                            |
+
+## Pool metrics
+
+```ts
+import { registerPgPoolMetrics } from '@unhandled/instrumentation-kysely'
+
+const stop = registerPgPoolMetrics({ pool, max: 10, poolName: 'primary' })
+// later, before pool.end()
+stop()
+```
+
+Call it after the metrics provider is set up. Only `pg.Pool` is supported; anything else throws a `TypeError`. postgres.js exposes no pool counters.
+
+| Gauge                                    | Meaning                                  |
+| ---------------------------------------- | ---------------------------------------- |
+| `db.client.connection.used`              | Connections checked out                  |
+| `db.client.connection.idle`              | Open connections sitting idle            |
+| `db.client.connection.pending_requests`  | Callers waiting for a connection         |
+| `db.client.connection.max`               | The `max` you passed                     |
+
+Each point carries `db.client.connection.pool.name` set to `poolName`.
+
+## Duplicate spans
+
+If you also enable OpenTelemetry's `pg` instrumentation, every query is traced twice, once here and once at the driver. Keep one of them. postgres.js has no OpenTelemetry coverage, so wrapping its dialect here causes no duplicates.

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export { observeDialect } from "./observe_dialect.ts";
+export { POOL_METRIC_NAMES, registerPgPoolMetrics } from "./pool_metrics.ts";
+export type { ParsedSql } from "./sql_parser.ts";
+export { parseSql } from "./sql_parser.ts";
+export type { ConnectionInfo, ObserveDialectOptions, PgPoolLike, RegisterPgPoolMetricsOptions, } from "./types.ts";

package/build/index.js

@@ -0,0 +1,3 @@
+export { observeDialect } from "./observe_dialect.js";
+export { POOL_METRIC_NAMES, registerPgPoolMetrics } from "./pool_metrics.js";
+export { parseSql } from "./sql_parser.js";

package/build/observe_dialect.d.ts

@@ -0,0 +1,3 @@
+import type { Dialect } from "kysely";
+import type { ObserveDialectOptions } from "./types.ts";
+export declare const observeDialect: (options: ObserveDialectOptions) => Dialect;

package/build/observe_dialect.js

@@ -0,0 +1,194 @@
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import { ATTR } from "@unhandled/protocol";
+import { parseSql } from "./sql_parser.js";
+const INSTRUMENTATION_NAME = "@unhandled/instrumentation-kysely";
+const INSTRUMENTATION_VERSION = "0.1.0";
+const startSpan = (settings, state, sql) => {
+    const parent = context.active();
+    if (settings.requireParentSpan && !trace.getSpan(parent)) {
+        return undefined;
+    }
+    const { operation, collection } = parseSql(sql);
+    const { connection } = settings;
+    const attributes = { [ATTR.dbSystemName]: settings.dbSystem };
+    if (settings.recordQueryText) {
+        attributes[ATTR.dbQueryText] = sql;
+    }
+    if (operation) {
+        attributes[ATTR.dbOperationName] = operation;
+    }
+    if (collection) {
+        attributes[ATTR.dbCollectionName] = collection;
+    }
+    if (connection.database) {
+        attributes[ATTR.dbNamespace] = connection.database;
+    }
+    if (connection.host) {
+        attributes[ATTR.serverAddress] = connection.host;
+    }
+    if (connection.port !== undefined) {
+        attributes[ATTR.serverPort] = connection.port;
+    }
+    if (state.inTransaction) {
+        attributes[ATTR.dbTransaction] = true;
+    }
+    let name = settings.dbSystem;
+    if (operation) {
+        name = collection ? `${operation} ${collection}` : operation;
+    }
+    const span = trace
+        .getTracer(INSTRUMENTATION_NAME, INSTRUMENTATION_VERSION)
+        .startSpan(name, { kind: SpanKind.CLIENT, attributes }, parent);
+    return { span, context: trace.setSpan(parent, span), ended: false };
+};
+const finishSpan = (settings, active, error) => {
+    if (!active || active.ended) {
+        return;
+    }
+    active.ended = true;
+    if (error !== undefined) {
+        active.span.setAttribute(ATTR.errorType, error instanceof Error ? error.name : "Error");
+        if (settings.recordErrors) {
+            active.span.recordException(error instanceof Error ? error : String(error));
+            active.span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        else {
+            active.span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+    }
+    active.span.end();
+};
+const observeCall = async (settings, state, sql, run) => {
+    const active = startSpan(settings, state, sql);
+    if (!active) {
+        return run();
+    }
+    try {
+        const result = await context.with(active.context, run);
+        finishSpan(settings, active);
+        return result;
+    }
+    catch (error) {
+        finishSpan(settings, active, error);
+        throw error;
+    }
+};
+const observeStream = (settings, state, sql, open) => {
+    let iterator;
+    let active;
+    const current = () => {
+        if (!iterator) {
+            active = startSpan(settings, state, sql);
+            iterator = active ? context.with(active.context, open) : open();
+        }
+        return iterator;
+    };
+    const within = (run) => (active ? context.with(active.context, run) : run());
+    const stream = {
+        next: async () => {
+            const source = current();
+            try {
+                const result = await within(() => source.next());
+                if (result.done) {
+                    finishSpan(settings, active);
+                }
+                return result;
+            }
+            catch (error) {
+                finishSpan(settings, active, error);
+                throw error;
+            }
+        },
+        return: async (value) => {
+            try {
+                return (await iterator?.return?.(value)) ?? { done: true, value };
+            }
+            finally {
+                finishSpan(settings, active);
+            }
+        },
+        throw: async (error) => {
+            try {
+                if (iterator?.throw) {
+                    return await iterator.throw(error);
+                }
+                throw error;
+            }
+            catch (thrown) {
+                finishSpan(settings, active, thrown);
+                throw thrown;
+            }
+        },
+        [Symbol.asyncIterator]: () => stream,
+    };
+    return stream;
+};
+const observeConnection = (inner, settings, registry) => {
+    const state = { inTransaction: false };
+    const observed = {
+        ...(inner.cancelQuery && { cancelQuery: inner.cancelQuery.bind(inner) }),
+        ...(inner.collectSessionInfo && { collectSessionInfo: inner.collectSessionInfo.bind(inner) }),
+        ...(inner.killSession && { killSession: inner.killSession.bind(inner) }),
+        executeQuery: (...args) => observeCall(settings, state, args[0].sql, () => inner.executeQuery(...args)),
+        streamQuery: (...args) => observeStream(settings, state, args[0].sql, () => inner.streamQuery(...args)),
+    };
+    registry.set(observed, { inner, state });
+    return observed;
+};
+const observeDriver = (inner, settings) => {
+    const registry = new WeakMap();
+    const resolve = (connection) => registry.get(connection) ?? { inner: connection, state: { inTransaction: false } };
+    const lifecycle = async (statement, connection, run, inTransactionAfter) => {
+        const { inner: raw, state } = resolve(connection);
+        const wasInTransaction = state.inTransaction;
+        state.inTransaction = true;
+        try {
+            await observeCall(settings, state, statement, () => run(raw));
+            state.inTransaction = inTransactionAfter;
+        }
+        catch (error) {
+            state.inTransaction = statement === "begin" ? wasInTransaction : false;
+            throw error;
+        }
+    };
+    const savepoint = inner.savepoint?.bind(inner);
+    const rollbackToSavepoint = inner.rollbackToSavepoint?.bind(inner);
+    const releaseSavepoint = inner.releaseSavepoint?.bind(inner);
+    return {
+        init: (options) => inner.init(options),
+        acquireConnection: async (options) => observeConnection(await inner.acquireConnection(options), settings, registry),
+        beginTransaction: (connection, transactionSettings) => lifecycle("begin", connection, (raw) => inner.beginTransaction(raw, transactionSettings), true),
+        commitTransaction: (connection) => lifecycle("commit", connection, (raw) => inner.commitTransaction(raw), false),
+        rollbackTransaction: (connection) => lifecycle("rollback", connection, (raw) => inner.rollbackTransaction(raw), false),
+        ...(savepoint && {
+            savepoint: (connection, name, compile) => savepoint(resolve(connection).inner, name, compile),
+        }),
+        ...(rollbackToSavepoint && {
+            rollbackToSavepoint: (connection, name, compile) => rollbackToSavepoint(resolve(connection).inner, name, compile),
+        }),
+        ...(releaseSavepoint && {
+            releaseSavepoint: (connection, name, compile) => releaseSavepoint(resolve(connection).inner, name, compile),
+        }),
+        releaseConnection: (connection, options) => inner.releaseConnection(resolve(connection).inner, options),
+        destroy: (options) => inner.destroy(options),
+    };
+};
+export const observeDialect = (options) => {
+    const { dialect } = options;
+    const settings = {
+        dbSystem: options.dbSystem,
+        recordQueryText: options.recordQueryText ?? true,
+        recordErrors: options.recordErrors ?? true,
+        requireParentSpan: options.requireParentSpan ?? false,
+        connection: options.connection ?? {},
+    };
+    return {
+        createDriver: () => observeDriver(dialect.createDriver(), settings),
+        createQueryCompiler: () => dialect.createQueryCompiler(),
+        createAdapter: () => dialect.createAdapter(),
+        createIntrospector: (db) => dialect.createIntrospector(db),
+    };
+};

package/build/pool_metrics.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterPgPoolMetricsOptions } from "./types.ts";
+export declare const POOL_METRIC_NAMES: {
+    readonly used: "db.client.connection.used";
+    readonly idle: "db.client.connection.idle";
+    readonly pending: "db.client.connection.pending_requests";
+    readonly limit: "db.client.connection.max";
+};
+export declare const registerPgPoolMetrics: (options: RegisterPgPoolMetricsOptions) => () => void;

package/build/pool_metrics.js

@@ -0,0 +1,52 @@
+import { metrics } from "@opentelemetry/api";
+const METER_NAME = "@unhandled/instrumentation-kysely";
+const METER_VERSION = "0.1.0";
+export const POOL_METRIC_NAMES = {
+    used: "db.client.connection.used",
+    idle: "db.client.connection.idle",
+    pending: "db.client.connection.pending_requests",
+    limit: "db.client.connection.max",
+};
+const ATTR_POOL_NAME = "db.client.connection.pool.name";
+const isPgPool = (value) => typeof value === "object" &&
+    value !== null &&
+    "connect" in value &&
+    typeof value.connect === "function" &&
+    "totalCount" in value &&
+    typeof value.totalCount === "number" &&
+    "idleCount" in value &&
+    typeof value.idleCount === "number" &&
+    "waitingCount" in value &&
+    typeof value.waitingCount === "number";
+export const registerPgPoolMetrics = (options) => {
+    const { pool, max, poolName } = options;
+    if (!isPgPool(pool)) {
+        throw new TypeError("registerPgPoolMetrics() only supports a pg.Pool (an object with totalCount, idleCount, waitingCount and connect). postgres.js and other drivers expose no pool counters.");
+    }
+    const meter = metrics.getMeter(METER_NAME, METER_VERSION);
+    const used = meter.createObservableGauge(POOL_METRIC_NAMES.used, {
+        description: "Connections currently checked out of the pool",
+        unit: "{connection}",
+    });
+    const idle = meter.createObservableGauge(POOL_METRIC_NAMES.idle, {
+        description: "Connections open and idle in the pool",
+        unit: "{connection}",
+    });
+    const pending = meter.createObservableGauge(POOL_METRIC_NAMES.pending, {
+        description: "Requests waiting for a connection",
+        unit: "{request}",
+    });
+    const limit = meter.createObservableGauge(POOL_METRIC_NAMES.limit, {
+        description: "Maximum number of connections the pool allows",
+        unit: "{connection}",
+    });
+    const attributes = { [ATTR_POOL_NAME]: poolName };
+    const observe = (result) => {
+        result.observe(used, pool.totalCount - pool.idleCount, attributes);
+        result.observe(idle, pool.idleCount, attributes);
+        result.observe(pending, pool.waitingCount, attributes);
+        result.observe(limit, max, attributes);
+    };
+    meter.addBatchObservableCallback(observe, [used, idle, pending, limit]);
+    return () => meter.removeBatchObservableCallback(observe, [used, idle, pending, limit]);
+};

package/build/sql_parser.d.ts

@@ -0,0 +1,5 @@
+export interface ParsedSql {
+    collection?: string;
+    operation?: string;
+}
+export declare const parseSql: (sql: string) => ParsedSql;

package/build/sql_parser.js

@@ -0,0 +1,151 @@
+const WHITESPACE_CHAR_PATTERN = /\s/;
+const STATEMENTS = new Set(["SELECT", "INSERT", "UPDATE", "DELETE", "MERGE"]);
+const DDL = new Set(["CREATE", "ALTER", "DROP", "TRUNCATE"]);
+const WORD = /[A-Za-z_]/;
+const WORD_PART = /[\w$]/;
+const skipBlanks = (sql, from) => {
+    let index = from;
+    while (index < sql.length) {
+        if (WHITESPACE_CHAR_PATTERN.test(sql[index])) {
+            index += 1;
+        }
+        else if (sql.startsWith("--", index)) {
+            const end = sql.indexOf("\n", index);
+            index = end === -1 ? sql.length : end + 1;
+        }
+        else if (sql.startsWith("/*", index)) {
+            const end = sql.indexOf("*/", index + 2);
+            index = end === -1 ? sql.length : end + 2;
+        }
+        else {
+            break;
+        }
+    }
+    return index;
+};
+const skipQuoted = (sql, from, close) => {
+    let index = from + 1;
+    while (index < sql.length) {
+        if (sql[index] === close) {
+            if (sql[index + 1] === close) {
+                index += 2;
+                continue;
+            }
+            return index + 1;
+        }
+        index += 1;
+    }
+    return sql.length;
+};
+const readWord = (sql, from) => {
+    if (!WORD.test(sql[from] ?? "")) {
+        return undefined;
+    }
+    let end = from + 1;
+    while (end < sql.length && WORD_PART.test(sql[end])) {
+        end += 1;
+    }
+    return { text: sql.slice(from, end), end };
+};
+const findKeyword = (sql, keywords, from) => {
+    let depth = 0;
+    let index = from;
+    while (index < sql.length) {
+        const char = sql[index];
+        if (char === "'" || char === '"' || char === "`") {
+            index = skipQuoted(sql, index, char);
+        }
+        else if (char === "[") {
+            index = skipQuoted(sql, index, "]");
+        }
+        else if (char === "(") {
+            depth += 1;
+            index += 1;
+        }
+        else if (char === ")") {
+            depth -= 1;
+            index += 1;
+        }
+        else if (WORD.test(char) && (index === 0 || !WORD_PART.test(sql[index - 1]))) {
+            const word = readWord(sql, index);
+            if (word && depth === 0 && keywords.has(word.text.toUpperCase())) {
+                return word;
+            }
+            index = word ? word.end : index + 1;
+        }
+        else {
+            index += 1;
+        }
+    }
+    return undefined;
+};
+const readIdentifier = (sql, from) => {
+    const char = sql[from];
+    if (char === '"' || char === "`" || char === "[") {
+        const end = skipQuoted(sql, from, char === "[" ? "]" : char);
+        return { text: sql.slice(from + 1, end - 1), end };
+    }
+    return readWord(sql, from);
+};
+const readQualifiedName = (sql, from) => {
+    const parts = [];
+    let index = skipBlanks(sql, from);
+    for (;;) {
+        const part = readIdentifier(sql, index);
+        if (!part) {
+            break;
+        }
+        parts.push(part.text);
+        const next = skipBlanks(sql, part.end);
+        if (sql[next] !== ".") {
+            break;
+        }
+        index = skipBlanks(sql, next + 1);
+    }
+    return parts.length > 0 ? parts.join(".") : undefined;
+};
+const SKIPPED_MODIFIERS = new Set(["ONLY", "IF", "NOT", "EXISTS"]);
+const readTarget = (sql, from) => {
+    let index = skipBlanks(sql, from);
+    for (;;) {
+        const word = readWord(sql, index);
+        if (!(word && SKIPPED_MODIFIERS.has(word.text.toUpperCase()))) {
+            break;
+        }
+        index = skipBlanks(sql, word.end);
+    }
+    return readQualifiedName(sql, index);
+};
+const statementStart = (sql, from) => {
+    const first = readWord(sql, from);
+    if (first?.text.toUpperCase() !== "WITH") {
+        return from;
+    }
+    const main = findKeyword(sql, STATEMENTS, first.end);
+    return main ? main.end - main.text.length : from;
+};
+export const parseSql = (sql) => {
+    const start = statementStart(sql, skipBlanks(sql, 0));
+    const first = readWord(sql, start);
+    if (!first) {
+        return {};
+    }
+    const operation = first.text.toUpperCase();
+    const after = first.end;
+    if (operation === "SELECT" || operation === "DELETE") {
+        const from = findKeyword(sql, new Set(["FROM"]), after);
+        return { operation, collection: from ? readTarget(sql, from.end) : undefined };
+    }
+    if (operation === "INSERT" || operation === "MERGE") {
+        const into = findKeyword(sql, new Set(["INTO"]), after);
+        return { operation, collection: into ? readTarget(sql, into.end) : undefined };
+    }
+    if (operation === "UPDATE") {
+        return { operation, collection: readTarget(sql, after) };
+    }
+    if (DDL.has(operation)) {
+        const table = findKeyword(sql, new Set(["TABLE"]), after);
+        return { operation, collection: table ? readTarget(sql, table.end) : undefined };
+    }
+    return { operation };
+};

package/build/types.d.ts

@@ -0,0 +1,25 @@
+import type { Dialect } from "kysely";
+export interface ConnectionInfo {
+    database?: string;
+    host?: string;
+    port?: number;
+}
+export interface ObserveDialectOptions {
+    connection?: ConnectionInfo;
+    dbSystem: string;
+    dialect: Dialect;
+    recordErrors?: boolean;
+    recordQueryText?: boolean;
+    requireParentSpan?: boolean;
+}
+export interface PgPoolLike {
+    connect: (...args: never[]) => unknown;
+    idleCount: number;
+    totalCount: number;
+    waitingCount: number;
+}
+export interface RegisterPgPoolMetricsOptions {
+    max: number;
+    pool: unknown;
+    poolName: string;
+}

package/build/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@unhandled/instrumentation-kysely",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Kysely query tracing and pg pool metrics for Unhandled",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/treboryx/unhandled.git",
+    "directory": "packages/instrumentation-kysely"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "~1.9.1",
+    "@opentelemetry/core": "^2.12.0",
+    "@unhandled/protocol": "0.0.1"
+  },
+  "devDependencies": {
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@opentelemetry/context-async-hooks": "^2.12.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.223.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.223.0",
+    "@opentelemetry/sdk-metrics": "^2.12.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
+    "@types/node": "^25.9.9",
+    "@types/pg": "^8.23.1",
+    "@unhandled/otlp-receiver": "0.0.0",
+    "kysely": "^0.29.7",
+    "kysely-postgres-js": "^5.0.1",
+    "pg": "^8.23.1",
+    "postgres": "^3.4.9",
+    "typescript": "~6.0.2"
+  },
+  "peerDependencies": {
+    "kysely": "^0.28.16 || ^0.29.6"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "node --test 'tests/**/*.test.ts'",
+    "typecheck": "tsrs --noEmit",
+    "typecheck:tsc": "tsc --noEmit"
+  }
 }