@typed-sql/opentelemetry 2.0.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# @typed-sql/opentelemetry
+
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 1b054b6: Add an adapter-neutral, redacted database observation lifecycle for queries, cardinality contracts,
+  batches, PostgreSQL pipelines, streams, cancellation, and nested transactions. Runtime fingerprints
+  correlate with compiler structural variants while SQL, parameter values, connection configuration,
+  and driver causes remain excluded by default. Publish the optional OpenTelemetry bridge with current
+  database semantic conventions and explicit high-cardinality or exception-capture opt-ins.
+
+### Patch Changes
+
+- Updated dependencies [29afc3d]
+- Updated dependencies [3f063f6]
+- Updated dependencies [6a7ae58]
+- Updated dependencies [b06fd0a]
+- Updated dependencies [3050209]
+- Updated dependencies [1b054b6]
+- Updated dependencies [b4f1b6e]
+- Updated dependencies [87189c3]
+- Updated dependencies [e654fae]
+- Updated dependencies [b2ec119]
+  - @typed-sql/core@2.0.0-rc.0
+
+## 1.0.0
+
+- Add an optional OpenTelemetry adapter for typed-sql's redacted database observation lifecycle.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typed-sql contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @typed-sql/opentelemetry
+
+Optional OpenTelemetry tracing for typed-sql's redacted database observer contract.
+
+This package has a stable public contract. The OpenTelemetry API is an application-owned peer;
+typed-sql does not install an SDK or exporter.
+
+```sh
+pnpm add @typed-sql/opentelemetry @opentelemetry/api
+```
+
+```ts
+import { createOpenTelemetryObserver } from "@typed-sql/opentelemetry";
+import { createPgDatabase } from "@typed-sql/postgres/pg";
+
+const database = await createPgDatabase({
+  connectionString: process.env.DATABASE_URL!,
+  observer: createOpenTelemetryObserver(),
+});
+```
+
+The default attributes contain a stable query fingerprint, dialect, grammar version, execution kind,
+cardinality contract, and transaction depth. SQL text, parameter values, connection strings, driver
+errors, batch fingerprint lists, and returned-row counts are excluded by default.
+
+See the [observability guide](../../docs/guides/observability.md) for lifecycle semantics, opt-ins,
+custom observers, and complete tracing setup.
+
+MIT © typed-sql contributors

package/dist/packages/opentelemetry/src/index.d.ts

@@ -0,0 +1,15 @@
+import { type Tracer } from "@opentelemetry/api";
+import type { DatabaseObserver } from "@typed-sql/core";
+export interface OpenTelemetryObserverOptions {
+    readonly tracer?: Tracer;
+    readonly instrumentationName?: string;
+    readonly instrumentationVersion?: string;
+    /** Opt-in because database row counts are an opt-in OpenTelemetry attribute. */
+    readonly recordReturnedRows?: boolean;
+    /** Opt-in because driver errors can contain query text or values. */
+    readonly recordExceptions?: boolean;
+    /** Opt-in because a fingerprint list can be high-cardinality for dynamic batches. */
+    readonly recordBatchFingerprints?: boolean;
+}
+export declare function createOpenTelemetryObserver(options?: OpenTelemetryObserverOptions): DatabaseObserver;
+//# sourceMappingURL=index.d.ts.map

package/dist/packages/opentelemetry/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AACvH,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,qFAAqF;IACrF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC5C;AA6DD,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,gBAAgB,CAsBxG"}

package/dist/packages/opentelemetry/src/index.js

@@ -0,0 +1,87 @@
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+function databaseSystem(dialect) {
+    if (dialect === "postgres")
+        return "postgresql";
+    return dialect;
+}
+function spanName(operation) {
+    const system = databaseSystem(operation.dialect);
+    if (operation.kind === "batch")
+        return `BATCH ${system}`;
+    if (operation.kind === "pipeline")
+        return `PIPELINE ${system}`;
+    if (operation.kind === "transaction")
+        return `TRANSACTION ${system}`;
+    return system;
+}
+function startAttributes(operation, options) {
+    const attributes = {
+        "db.system.name": databaseSystem(operation.dialect),
+        "typed_sql.grammar.version": operation.grammarVersion,
+        "typed_sql.operation.kind": operation.kind,
+        "typed_sql.transaction.depth": operation.transactionDepth,
+    };
+    if (operation.kind === "query") {
+        attributes["typed_sql.query.fingerprint"] = operation.fingerprint;
+        attributes["typed_sql.query.cardinality"] = operation.cardinality;
+        attributes["typed_sql.query.prepared"] = operation.prepared;
+    }
+    else if (operation.kind === "stream") {
+        attributes["typed_sql.query.fingerprint"] = operation.fingerprint;
+        attributes["typed_sql.query.prepared"] = operation.prepared;
+    }
+    else if (operation.kind === "batch" || operation.kind === "pipeline") {
+        attributes["db.operation.name"] = operation.kind === "batch" ? "BATCH" : "PIPELINE";
+        attributes["db.operation.batch.size"] = operation.size;
+        if (options.recordBatchFingerprints === true) {
+            attributes["typed_sql.query.fingerprints"] = [...operation.fingerprints];
+        }
+    }
+    else
+        attributes["db.operation.name"] = "TRANSACTION";
+    return attributes;
+}
+function endSpan(span, completion, options) {
+    span.setAttribute("typed_sql.duration_ms", completion.durationMilliseconds);
+    if (options.recordReturnedRows === true && completion.rowCount !== undefined) {
+        span.setAttribute("db.response.returned_rows", completion.rowCount);
+    }
+    if (completion.status !== "success") {
+        const errorType = completion.cancellationReason === "deadline"
+            ? "timeout"
+            : completion.cancellationReason === "signal"
+                ? "cancelled"
+                : (completion.errorType ?? "unknown");
+        span.setAttribute("error.type", errorType);
+        if (completion.cancellationReason !== undefined) {
+            span.setAttribute("typed_sql.cancellation.reason", completion.cancellationReason);
+        }
+        if (options.recordExceptions === true && completion.cause instanceof Error)
+            span.recordException(completion.cause);
+        span.setStatus({ code: SpanStatusCode.ERROR });
+    }
+    span.end();
+}
+export function createOpenTelemetryObserver(options = {}) {
+    const tracer = options.tracer ??
+        trace.getTracer(options.instrumentationName ?? "@typed-sql/opentelemetry", options.instrumentationVersion);
+    return Object.freeze({
+        captureErrorCause: options.recordExceptions === true,
+        start(operation) {
+            const span = tracer.startSpan(spanName(operation), {
+                kind: SpanKind.CLIENT,
+                attributes: startAttributes(operation, options),
+            });
+            const active = trace.setSpan(context.active(), span);
+            return {
+                run(callback) {
+                    return context.with(active, callback);
+                },
+                end(completion) {
+                    endSpan(span, completion, options);
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/opentelemetry/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@typed-sql/opentelemetry",
+  "version": "2.0.0-rc.0",
+  "description": "Optional OpenTelemetry tracing integration for typed-sql database observers.",
+  "license": "MIT",
+  "author": "Lojhan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lojhan/typed-sql.git",
+    "directory": "packages/opentelemetry"
+  },
+  "homepage": "https://github.com/Lojhan/typed-sql#readme",
+  "bugs": {
+    "url": "https://github.com/Lojhan/typed-sql/issues"
+  },
+  "engines": {
+    "node": ">=22.11"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.map",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "typedSql": {
+    "releaseTrack": "stable"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/packages/opentelemetry/src/index.js"
+  },
+  "dependencies": {
+    "@typed-sql/core": "2.0.0-rc.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.9.0 <2"
+  },
+  "scripts": {
+    "test": "poku test --reporter=compact --enforce",
+    "coverage": "poku test --coverage=@pokujs/c8 --coverageConfig=.c8rc.json --reporter=compact --enforce"
+  }
+}