@8monkey/opentelemetry-instrumentation-bun-sql 0.1.0-rc0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,118 @@
+# OpenTelemetry Bun.SQL Instrumentation
+
+OpenTelemetry instrumentation for [Bun.SQL](https://bun.sh/docs/api/sql), the built-in database client in Bun supporting PostgreSQL, MySQL, and SQLite.
+
+## Installation
+
+```bash
+bun add @8monkey/opentelemetry-instrumentation-bun-sql
+```
+
+## Supported Versions
+
+- Bun >= 1.2
+
+## Usage
+
+```typescript
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { SimpleSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { BunSqlInstrumentation } from "@8monkey/opentelemetry-instrumentation-bun-sql";
+
+// 1. Register instrumentation before creating any SQL instances.
+//    Bun built-ins bypass Node.js module hooks, so the instrumentation patches
+//    require("bun").SQL at enable time — instances created before this are not traced.
+const provider = new NodeTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
+});
+provider.register();
+
+registerInstrumentations({
+  instrumentations: [new BunSqlInstrumentation()],
+});
+
+// 2. Create instances via require("bun"), not `import { SQL } from "bun"`.
+//    Static import bindings are resolved at module load time (before step 1 runs)
+//    and therefore always capture the original, unpatched constructor.
+const sql = new (require("bun") as typeof Bun).SQL({ adapter: "sqlite" });
+
+await sql`SELECT 1`;
+await sql.close();
+```
+
+## Semantic Conventions
+
+This instrumentation follows the [OpenTelemetry Database Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/database/).
+
+### Attributes
+
+| Attribute                   | Description                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------------- |
+| `db.system.name`            | Database system: `postgresql`, `mysql`, or `sqlite`                                   |
+| `db.operation.name`         | SQL operation: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, etc.                           |
+| `db.query.text`             | The SQL query text (parameterized for tagged templates, sanitized for unsafe queries) |
+| `db.namespace`              | Database name or SQLite filename                                                      |
+| `db.response.returned_rows` | Number of rows returned                                                               |
+| `server.address`            | Server hostname (PostgreSQL/MySQL)                                                    |
+| `server.port`               | Server port (PostgreSQL/MySQL)                                                        |
+| `error.type`                | Error class name (e.g., `SQLiteError`, `PostgresError`)                               |
+| `db.response.status_code`   | Database-specific error code                                                          |
+
+### Span names
+
+Span names follow the OTel convention priority:
+
+1. `{db.operation.name} {db.namespace}` (e.g., `SELECT mydb`)
+2. `{db.operation.name}` (e.g., `SELECT`)
+3. `{db.namespace}` (e.g., `mydb`)
+4. `{db.system.name}` (e.g., `postgresql`)
+
+## Configuration
+
+| Option                      | Type                        | Default         | Description                                                                                        |
+| --------------------------- | --------------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
+| `requireParentSpan`         | `boolean`                   | `false`         | Only create spans when a parent span exists in context                                             |
+| `enhancedDatabaseReporting` | `boolean`                   | `false`         | Include query parameters (`db.query.parameter.<n>`) and result data in spans                       |
+| `ignoreConnectionSpans`     | `boolean`                   | `false`         | Suppress spans for `CLOSE` and `RESERVE` operations                                                |
+| `maskStatement`             | `boolean`                   | `true`          | Replace integer literals and quoted strings with `?` in non-parameterized queries (`sql.unsafe()`) |
+| `maskStatementHook`         | `(query: string) => string` | Built-in masker | Custom masking function for non-parameterized queries                                              |
+| `addSqlCommenterComment`    | `boolean`                   | `false`         | Append SQL commenter traceparent comments to queries                                               |
+| `requestHook`               | `(span, info) => void`      | -               | Called before query execution to customize span attributes                                         |
+| `responseHook`              | `(span, info) => void`      | -               | Called after query execution with response metadata                                                |
+
+### Example with hooks
+
+```typescript
+import type {
+  BunSqlRequestHookInformation,
+  BunSqlResponseHookInformation,
+} from "@8monkey/opentelemetry-instrumentation-bun-sql";
+
+new BunSqlInstrumentation({
+  requestHook: (span, info: BunSqlRequestHookInformation) => {
+    span.setAttribute("custom.query", info.query);
+  },
+  responseHook: (span, info: BunSqlResponseHookInformation) => {
+    if (info.rowCount !== undefined) {
+      span.setAttribute("custom.row_count", info.rowCount);
+    }
+  },
+});
+```
+
+## What gets instrumented
+
+- **Tagged template queries**: `` sql`SELECT * FROM users WHERE id = ${id}` ``
+- **Unsafe queries**: `sql.unsafe("SELECT * FROM users")`
+- **Queries inside transactions**: queries run inside `sql.begin(tx => ...)`, `tx.savepoint(sp => ...)`, etc. are individually traced; no span is emitted for the transaction boundary itself
+- **Connection management**: `sql.close()`, `sql.reserve()`
+- **Chaining methods**: `.values()`, `.raw()`, `.simple()`, `.execute()`
+
+### Query text handling
+
+| Query type                                 | `db.query.text` behavior                                   |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| Tagged template                            | Parameterized: `SELECT * FROM users WHERE id = $1`         |
+| `sql.unsafe()`                             | Sanitized by default: `SELECT * FROM users WHERE name = ?` |
+| `sql.unsafe()` with `maskStatement: false` | Raw text preserved                                         |

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { BunSqlInstrumentation } from "./instrumentation.js";
+export type { BunSqlInstrumentationConfig, BunSqlRequestHookInformation, BunSqlResponseHookInformation, BunSqlInstrumentationExecutionRequestHook, BunSqlInstrumentationExecutionResponseHook, } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { BunSqlInstrumentation } from "./instrumentation.js";

package/dist/instrumentation.d.ts

@@ -0,0 +1,33 @@
+import { InstrumentationBase } from "@opentelemetry/instrumentation";
+import type { SQL } from "bun";
+import type { BunSqlInstrumentationConfig } from "./types.js";
+export declare class BunSqlInstrumentation extends InstrumentationBase {
+    private _originalSQL;
+    private _originalSqlSingleton;
+    private _patched;
+    constructor(config?: BunSqlInstrumentationConfig);
+    getConfig(): BunSqlInstrumentationConfig;
+    init(): [];
+    enable(): void;
+    disable(): void;
+    private _getBunModule;
+    /**
+     * Wrap a Bun SQL instance with a Proxy to intercept tagged template calls
+     * and method invocations.
+     */
+    _wrapInstance(instance: SQL): SQL;
+    private _handleTaggedTemplate;
+    private _wrapUnsafe;
+    private _execQuery;
+    private _wrapConnOp;
+    /**
+     * Wrap a lazy query result (thenable) to intercept resolution/rejection
+     * for span lifecycle management, while preserving chaining methods.
+     * Uses a Proxy to intercept .then() and chaining methods without
+     * directly mutating the result object.
+     */
+    private _wrapQueryResult;
+    private _handleQuerySuccess;
+    private _recordError;
+    private _callRequestHook;
+}

package/dist/instrumentation.js

@@ -0,0 +1,354 @@
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import { InstrumentationBase, safeExecuteInTheMiddle } from "@opentelemetry/instrumentation";
+import { ATTR_DB_NAMESPACE, ATTR_DB_OPERATION_NAME, ATTR_DB_QUERY_TEXT, ATTR_DB_RESPONSE_STATUS_CODE, ATTR_DB_SYSTEM_NAME, ATTR_ERROR_TYPE, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, } from "@opentelemetry/semantic-conventions";
+import { addSqlCommenterComment } from "@opentelemetry/sql-common";
+import { ATTR_DB_QUERY_PARAMETER_PREFIX, ATTR_DB_RESPONSE_RETURNED_ROWS } from "./semconv.js";
+import { buildParameterizedQuery, buildSpanName, extractOperationName, getDbNamespace, getDbSystemName, getServerAddress, getServerPort, sanitizeQuery, } from "./utils.js";
+import { VERSION } from "./version.js";
+const INSTRUMENTATION_NAME = "@8monkey/opentelemetry-instrumentation-bun-sql";
+// Symbol to mark instances we've already wrapped
+const WRAPPED = Symbol.for("bun-sql-otel-wrapped");
+const CHAINING_METHODS = new Set(["values", "raw", "simple", "execute"]);
+function isRecord(val) {
+    return typeof val === "object" && val !== null;
+}
+function buildCtxAttributes(ctx, extra) {
+    const attrs = {
+        [ATTR_DB_SYSTEM_NAME]: ctx.systemName,
+        ...extra,
+    };
+    if (ctx.namespace !== undefined)
+        attrs[ATTR_DB_NAMESPACE] = ctx.namespace;
+    if (ctx.serverAddress !== undefined)
+        attrs[ATTR_SERVER_ADDRESS] = ctx.serverAddress;
+    if (ctx.serverPort !== undefined)
+        attrs[ATTR_SERVER_PORT] = ctx.serverPort;
+    return attrs;
+}
+export class BunSqlInstrumentation extends InstrumentationBase {
+    constructor(config) {
+        super(INSTRUMENTATION_NAME, VERSION, config ?? {});
+        // Only initialize if not already set by enable() called from super()
+        this._originalSQL ??= null;
+        this._originalSqlSingleton ??= null;
+        this._patched ??= false;
+    }
+    getConfig() {
+        return {
+            maskStatement: true,
+            ...super.getConfig(),
+        };
+    }
+    init() {
+        // Bun built-in modules are not intercepted by Node.js module hooks.
+        // Patching is done directly in enable()/disable().
+        return [];
+    }
+    enable() {
+        if (this._patched)
+            return;
+        const bunModule = this._getBunModule();
+        if (bunModule === undefined)
+            return;
+        try {
+            if (bunModule.SQL !== undefined && bunModule.SQL !== null) {
+                // oxlint-disable-next-line no-unsafe-type-assertion
+                const OrigSQL = bunModule.SQL;
+                this._originalSQL = OrigSQL;
+                const wrapInstance = this._wrapInstance.bind(this);
+                // Wrap the SQL constructor so new instances are automatically instrumented
+                const wrappedSQL = function SQL(...args) {
+                    const instance = new OrigSQL(...args);
+                    return wrapInstance(instance);
+                };
+                // Preserve static properties
+                for (const key of ["prototype", "MySQLError", "PostgresError", "SQLError", "SQLiteError"]) {
+                    const desc = Object.getOwnPropertyDescriptor(OrigSQL, key);
+                    if (desc !== undefined) {
+                        Object.defineProperty(wrappedSQL, key, desc);
+                    }
+                }
+                bunModule.SQL = wrappedSQL;
+            }
+            // Also wrap the default `sql` singleton if present
+            const sqlVal = bunModule.sql;
+            if (sqlVal !== undefined && sqlVal !== null && Reflect.get(sqlVal, WRAPPED) !== true) {
+                this._originalSqlSingleton = sqlVal;
+                bunModule.sql = this._wrapInstance(sqlVal);
+            }
+            this._patched = true;
+            this._diag.debug("Bun.SQL instrumentation enabled");
+        }
+        catch (e) {
+            if (this._originalSQL !== null)
+                bunModule.SQL = this._originalSQL;
+            if (this._originalSqlSingleton !== null)
+                bunModule.sql = this._originalSqlSingleton;
+            this._originalSQL = this._originalSqlSingleton = null;
+            this._patched = false;
+            this._diag.error("Failed to enable Bun.SQL instrumentation", e);
+        }
+    }
+    disable() {
+        if (!this._patched)
+            return;
+        try {
+            const bunModule = this._getBunModule();
+            if (bunModule === undefined)
+                return;
+            if (this._originalSQL !== null) {
+                bunModule.SQL = this._originalSQL;
+                this._originalSQL = null;
+            }
+            if (this._originalSqlSingleton !== null) {
+                bunModule.sql = this._originalSqlSingleton;
+                this._originalSqlSingleton = null;
+            }
+            this._patched = false;
+            this._diag.debug("Bun.SQL instrumentation disabled");
+        }
+        catch (e) {
+            this._diag.error("Failed to disable Bun.SQL instrumentation", e);
+        }
+    }
+    _getBunModule() {
+        try {
+            // oxlint-disable-next-line no-unsafe-type-assertion
+            return require("bun");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Wrap a Bun SQL instance with a Proxy to intercept tagged template calls
+     * and method invocations.
+     */
+    _wrapInstance(instance) {
+        if (Reflect.get(instance, WRAPPED) === true) {
+            return instance;
+        }
+        const options = instance.options;
+        const optionsRecord = options;
+        const ctx = {
+            systemName: getDbSystemName(options.adapter),
+            namespace: getDbNamespace(optionsRecord),
+            serverAddress: getServerAddress(optionsRecord),
+            serverPort: getServerPort(optionsRecord),
+        };
+        return new Proxy(instance, {
+            apply: (_target, _thisArg, args) => this._handleTaggedTemplate(instance, args, ctx),
+            get: (target, prop, receiver) => {
+                if (prop === WRAPPED)
+                    return true;
+                // Wrap known methods with typed access
+                switch (prop) {
+                    case "unsafe":
+                        return this._wrapUnsafe(target.unsafe.bind(target), ctx);
+                    case "begin":
+                    case "transaction":
+                        return (callback) => target.begin((tx) => callback(this._wrapInstance(tx)));
+                    case "savepoint":
+                        return (callback) => 
+                        // oxlint-disable-next-line no-unsafe-type-assertion
+                        target.savepoint((tx) => callback(this._wrapInstance(tx)));
+                    case "beginDistributed":
+                    case "distributed":
+                        return (id, callback) => target.beginDistributed(id, (tx) => callback(this._wrapInstance(tx)));
+                    case "reserve":
+                        return this._wrapConnOp("RESERVE", target.reserve.bind(target), ctx, (r) => this._wrapInstance(r));
+                    case "close":
+                    case "end":
+                        return this._wrapConnOp("CLOSE", target.close.bind(target), ctx, (r) => r);
+                    default: {
+                        const value = Reflect.get(target, prop, receiver);
+                        if (typeof value === "function") {
+                            // oxlint-disable-next-line no-unsafe-return
+                            return value.bind(target);
+                        }
+                        return value;
+                    }
+                }
+            },
+        });
+    }
+    _handleTaggedTemplate(instance, args, ctx) {
+        const config = this.getConfig();
+        // oxlint-disable-next-line no-unsafe-type-assertion
+        const strings = args[0];
+        const params = args.slice(1);
+        const queryText = buildParameterizedQuery(strings);
+        const operationName = extractOperationName(queryText);
+        if (config.requireParentSpan === true && trace.getSpan(context.active()) === undefined) {
+            return instance(strings, ...params);
+        }
+        return this._execQuery(queryText, operationName, params, ctx, config, (span) => {
+            let templateStrings = strings;
+            if (config.addSqlCommenterComment === true) {
+                const suffix = addSqlCommenterComment(span, queryText).slice(queryText.length);
+                if (suffix !== "") {
+                    const last = strings.length - 1;
+                    const cooked = [...strings];
+                    const raw = [...strings.raw];
+                    cooked[last] += suffix;
+                    raw[last] += suffix;
+                    // oxlint-disable-next-line no-unsafe-type-assertion
+                    templateStrings = Object.assign(cooked, { raw });
+                }
+            }
+            return instance(templateStrings, ...params);
+        });
+    }
+    _wrapUnsafe(original, ctx) {
+        return (query, params) => {
+            const config = this.getConfig();
+            if (config.requireParentSpan === true && trace.getSpan(context.active()) === undefined) {
+                return original(query, params);
+            }
+            const operationName = extractOperationName(query);
+            // Mask non-parameterized queries per OTel semconv
+            const queryText = config.maskStatement === false ? query : (config.maskStatementHook ?? sanitizeQuery)(query);
+            return this._execQuery(queryText, operationName, params, ctx, config, (span) => original(config.addSqlCommenterComment === true ? addSqlCommenterComment(span, query) : query, params));
+        };
+    }
+    _execQuery(queryText, operationName, params, ctx, config, execute) {
+        const attributes = buildCtxAttributes(ctx);
+        if (operationName !== undefined)
+            attributes[ATTR_DB_OPERATION_NAME] = operationName;
+        attributes[ATTR_DB_QUERY_TEXT] = queryText;
+        if (config.enhancedDatabaseReporting === true && params !== undefined) {
+            for (let i = 0; i < params.length; i++) {
+                attributes[`${ATTR_DB_QUERY_PARAMETER_PREFIX}.${i}`] = String(params[i]);
+            }
+        }
+        const span = this.tracer.startSpan(buildSpanName({ operationName, namespace: ctx.namespace, systemName: ctx.systemName }), { kind: SpanKind.CLIENT, attributes });
+        this._callRequestHook(span, {
+            query: queryText,
+            operation: operationName,
+            params: config.enhancedDatabaseReporting === true ? params : undefined,
+        }, config);
+        try {
+            const result = context.with(trace.setSpan(context.active(), span), () => execute(span));
+            return this._wrapQueryResult(result, span, config);
+        }
+        catch (error) {
+            this._recordError(span, error instanceof Error ? error : new Error(String(error)));
+            span.end();
+            throw error;
+        }
+    }
+    _wrapConnOp(op, original, ctx, onSuccess) {
+        return () => {
+            const config = this.getConfig();
+            if (config.ignoreConnectionSpans === true ||
+                (config.requireParentSpan === true && trace.getSpan(context.active()) === undefined)) {
+                return original().then(onSuccess);
+            }
+            const span = this.tracer.startSpan(buildSpanName({ operationName: op, namespace: ctx.namespace, systemName: ctx.systemName }), {
+                kind: SpanKind.CLIENT,
+                attributes: buildCtxAttributes(ctx, { [ATTR_DB_OPERATION_NAME]: op }),
+            });
+            try {
+                return original().then((r) => {
+                    span.end();
+                    return onSuccess(r);
+                }, (e) => {
+                    this._recordError(span, e);
+                    span.end();
+                    throw e;
+                });
+            }
+            catch (e) {
+                this._recordError(span, e instanceof Error ? e : new Error(String(e)));
+                span.end();
+                throw e;
+            }
+        };
+    }
+    /**
+     * Wrap a lazy query result (thenable) to intercept resolution/rejection
+     * for span lifecycle management, while preserving chaining methods.
+     * Uses a Proxy to intercept .then() and chaining methods without
+     * directly mutating the result object.
+     */
+    _wrapQueryResult(queryResult, span, config) {
+        if (typeof queryResult !== "object" || queryResult === null || !("then" in queryResult)) {
+            span.end();
+            return queryResult;
+        }
+        const resultObj = queryResult;
+        // oxlint-disable-next-line no-unsafe-type-assertion
+        const origThen = resultObj["then"];
+        const wrappedThen = (onFulfilled, onRejected) => origThen.call(resultObj, (data) => {
+            this._handleQuerySuccess(span, data, config);
+            return onFulfilled === undefined ? data : onFulfilled(data);
+        }, (error) => {
+            this._recordError(span, error instanceof Error ? error : new Error(String(error)));
+            span.end();
+            if (onRejected !== undefined)
+                return onRejected(error);
+            throw error;
+        });
+        // Use Proxy to intercept .then() and chaining methods
+        return new Proxy(queryResult, {
+            get: (target, prop, receiver) => {
+                if (prop === "then")
+                    return wrappedThen;
+                if (typeof prop === "string" && CHAINING_METHODS.has(prop)) {
+                    const value = Reflect.get(target, prop, receiver);
+                    if (typeof value === "function") {
+                        return (...args) => {
+                            const chainResult = value.apply(target, args);
+                            return this._wrapQueryResult(chainResult, span, config);
+                        };
+                    }
+                    return value;
+                }
+                // oxlint-disable-next-line no-unsafe-return
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+    }
+    _handleQuerySuccess(span, data, config) {
+        const record = isRecord(data) ? data : null;
+        const rowCount = record !== null && typeof record["count"] === "number" ? record["count"] : undefined;
+        if (rowCount !== undefined)
+            span.setAttribute(ATTR_DB_RESPONSE_RETURNED_ROWS, rowCount);
+        if (config.responseHook !== undefined) {
+            const command = record !== null && typeof record["command"] === "string" ? record["command"] : undefined;
+            safeExecuteInTheMiddle(() => {
+                config.responseHook(span, {
+                    rowCount,
+                    command,
+                    data: config.enhancedDatabaseReporting === true ? data : undefined,
+                });
+            }, (err) => {
+                if (err)
+                    this._diag.error("Error in responseHook", err);
+            }, true);
+        }
+        span.end();
+    }
+    _recordError(span, error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        span.recordException(error);
+        span.setAttribute(ATTR_ERROR_TYPE, error.constructor.name);
+        // Capture database-specific error codes
+        if ("code" in error && typeof error.code === "string") {
+            span.setAttribute(ATTR_DB_RESPONSE_STATUS_CODE, error.code);
+        }
+        else if ("errno" in error && typeof error.errno === "number") {
+            span.setAttribute(ATTR_DB_RESPONSE_STATUS_CODE, String(error.errno));
+        }
+    }
+    _callRequestHook(span, info, config) {
+        if (config.requestHook !== undefined) {
+            safeExecuteInTheMiddle(() => {
+                config.requestHook(span, info);
+            }, (err) => {
+                if (err)
+                    this._diag.error("Error in requestHook", err);
+            }, true);
+        }
+    }
+}

package/dist/semconv.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Semantic convention attribute names not yet in @opentelemetry/semantic-conventions.
+ */
+/** Individual query parameter values (opt-in). Use as `db.query.parameter.<key>`. */
+export declare const ATTR_DB_QUERY_PARAMETER_PREFIX = "db.query.parameter";
+/** Number of rows returned by the query response. */
+export declare const ATTR_DB_RESPONSE_RETURNED_ROWS = "db.response.returned_rows";
+/** The database system name for SQLite (not yet a named constant in semconv). */
+export declare const DB_SYSTEM_NAME_VALUE_SQLITE = "sqlite";

package/dist/semconv.js

@@ -0,0 +1,9 @@
+/**
+ * Semantic convention attribute names not yet in @opentelemetry/semantic-conventions.
+ */
+/** Individual query parameter values (opt-in). Use as `db.query.parameter.<key>`. */
+export const ATTR_DB_QUERY_PARAMETER_PREFIX = "db.query.parameter";
+/** Number of rows returned by the query response. */
+export const ATTR_DB_RESPONSE_RETURNED_ROWS = "db.response.returned_rows";
+/** The database system name for SQLite (not yet a named constant in semconv). */
+export const DB_SYSTEM_NAME_VALUE_SQLITE = "sqlite";

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+import type { Span } from "@opentelemetry/api";
+import type { InstrumentationConfig } from "@opentelemetry/instrumentation";
+export interface BunSqlRequestHookInformation {
+    /** The SQL query text (parameterized for tagged templates, raw for unsafe). */
+    query: string;
+    /** The SQL operation name (SELECT, INSERT, etc.). */
+    operation?: string;
+    /** Query parameter values (only present for tagged template queries). */
+    params?: unknown[];
+}
+export interface BunSqlResponseHookInformation {
+    /** Number of rows returned. */
+    rowCount?: number;
+    /** The command type (SELECT, INSERT, etc.). */
+    command?: string;
+    /** Raw query result data. */
+    data?: unknown;
+}
+export type BunSqlInstrumentationExecutionRequestHook = (span: Span, info: BunSqlRequestHookInformation) => void;
+export type BunSqlInstrumentationExecutionResponseHook = (span: Span, info: BunSqlResponseHookInformation) => void;
+export interface BunSqlInstrumentationConfig extends InstrumentationConfig {
+    /**
+     * Attach query parameters and result data to spans.
+     * Parameters are Opt-In per OTel DB semconv.
+     * @default false
+     */
+    enhancedDatabaseReporting?: boolean;
+    /**
+     * Only create spans when a parent span exists in the current context.
+     * Useful for reducing noise in high-throughput systems.
+     * @default false
+     */
+    requireParentSpan?: boolean;
+    /**
+     * Suppress connection-level spans (reserve/release/close).
+     * @default false
+     */
+    ignoreConnectionSpans?: boolean;
+    /**
+     * Mask non-parameterized queries (sql.unsafe(), sql.file()) by
+     * replacing literal values with `?` placeholders.
+     * Per OTel semconv, non-parameterized queries SHOULD be masked by default.
+     * @default true
+     */
+    maskStatement?: boolean;
+    /**
+     * Custom masking function for non-parameterized queries.
+     * Only used when `maskStatement` is true.
+     * @default Replaces string/numeric/boolean literals with `?`
+     */
+    maskStatementHook?: (query: string) => string;
+    /**
+     * Add SQL commenter traceparent comments to queries.
+     * Per OTel semconv, SHOULD NOT be enabled by default.
+     * @default false
+     */
+    addSqlCommenterComment?: boolean;
+    /**
+     * Hook called before query execution to customize span attributes.
+     */
+    requestHook?: BunSqlInstrumentationExecutionRequestHook;
+    /**
+     * Hook called after query execution to customize span attributes from response.
+     */
+    responseHook?: BunSqlInstrumentationExecutionResponseHook;
+}

package/dist/utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Extract the SQL operation name (SELECT, INSERT, etc.) from a query string.
+ * Returns the first word uppercased, matching the approach used by pg and mysql2 adapters.
+ */
+export declare function extractOperationName(sql: string): string | undefined;
+/**
+ * Build parameterized query text from tagged template strings.
+ * Replaces interpolated values with $1, $2, ... placeholders.
+ */
+export declare function buildParameterizedQuery(strings: TemplateStringsArray): string;
+/**
+ * Sanitize a non-parameterized query by replacing literal values with `?`.
+ * Matches the scope of mysql2's default masking (integers and single-quoted strings).
+ *
+ * Replaces:
+ * - Single-quoted strings: 'hello' → ?
+ * - Integer literals: 42 → ?
+ *
+ * Does NOT replace:
+ * - Double-quoted identifiers ("table_name") — these are identifiers in PostgreSQL/SQLite
+ * - Keywords
+ * - Operators
+ */
+export declare function sanitizeQuery(sql: string): string;
+/**
+ * Build span name per OTel DB semantic conventions:
+ * 1. {db.operation.name} {db.namespace} if both available
+ * 2. {db.operation.name} if no namespace
+ * 3. {db.namespace} alone
+ * 4. {db.system.name} as fallback
+ */
+export declare function buildSpanName(opts: {
+    operationName?: string;
+    namespace?: string;
+    systemName: string;
+}): string;
+/**
+ * Map Bun.SQL adapter name to the OTel `db.system.name` value.
+ */
+export declare function getDbSystemName(adapter: string | undefined): string;
+/**
+ * Extract database namespace (database name) from SQL instance options.
+ */
+export declare function getDbNamespace(options: Record<string, unknown>): string | undefined;
+/**
+ * Extract server address from SQL instance options.
+ */
+export declare function getServerAddress(options: Record<string, unknown>): string | undefined;
+/**
+ * Extract server port from SQL instance options.
+ */
+export declare function getServerPort(options: Record<string, unknown>): number | undefined;

package/dist/utils.js

@@ -0,0 +1,110 @@
+/**
+ * Extract the SQL operation name (SELECT, INSERT, etc.) from a query string.
+ * Returns the first word uppercased, matching the approach used by pg and mysql2 adapters.
+ */
+export function extractOperationName(sql) {
+    const trimmed = sql.trimStart();
+    if (trimmed.length === 0)
+        return undefined;
+    const spaceIdx = trimmed.indexOf(" ");
+    let firstWord = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+    if (firstWord.endsWith(";"))
+        firstWord = firstWord.slice(0, -1);
+    if (firstWord.length === 0)
+        return undefined;
+    return firstWord.toUpperCase();
+}
+/**
+ * Build parameterized query text from tagged template strings.
+ * Replaces interpolated values with $1, $2, ... placeholders.
+ */
+export function buildParameterizedQuery(strings) {
+    let query = "";
+    for (let i = 0; i < strings.length; i++) {
+        query += strings[i];
+        if (i < strings.length - 1) {
+            query += `$${i + 1}`;
+        }
+    }
+    return query;
+}
+/**
+ * Sanitize a non-parameterized query by replacing literal values with `?`.
+ * Matches the scope of mysql2's default masking (integers and single-quoted strings).
+ *
+ * Replaces:
+ * - Single-quoted strings: 'hello' → ?
+ * - Integer literals: 42 → ?
+ *
+ * Does NOT replace:
+ * - Double-quoted identifiers ("table_name") — these are identifiers in PostgreSQL/SQLite
+ * - Keywords
+ * - Operators
+ */
+export function sanitizeQuery(sql) {
+    return sql.replaceAll(/\b\d+\b/g, "?").replaceAll(/'(?:\\.|''|[^'])*'/g, "?");
+}
+/**
+ * Build span name per OTel DB semantic conventions:
+ * 1. {db.operation.name} {db.namespace} if both available
+ * 2. {db.operation.name} if no namespace
+ * 3. {db.namespace} alone
+ * 4. {db.system.name} as fallback
+ */
+export function buildSpanName(opts) {
+    if (opts.operationName !== undefined && opts.namespace !== undefined)
+        return `${opts.operationName} ${opts.namespace}`;
+    if (opts.operationName !== undefined)
+        return opts.operationName;
+    if (opts.namespace !== undefined)
+        return opts.namespace;
+    return opts.systemName;
+}
+/**
+ * Map Bun.SQL adapter name to the OTel `db.system.name` value.
+ */
+export function getDbSystemName(adapter) {
+    switch (adapter) {
+        case "postgres":
+        case "postgresql":
+            return "postgresql";
+        case "mysql":
+            return "mysql";
+        case "sqlite":
+            return "sqlite";
+        case undefined:
+            return "unknown";
+        default:
+            return adapter;
+    }
+}
+/**
+ * Extract database namespace (database name) from SQL instance options.
+ */
+export function getDbNamespace(options) {
+    if (typeof options["database"] === "string")
+        return options["database"];
+    if (typeof options["filename"] === "string") {
+        const filename = options["filename"];
+        return filename === ":memory:" ? ":memory:" : filename;
+    }
+    return undefined;
+}
+/**
+ * Extract server address from SQL instance options.
+ */
+export function getServerAddress(options) {
+    if (typeof options["hostname"] === "string")
+        return options["hostname"];
+    if (typeof options["host"] === "string")
+        return options["host"];
+    return undefined;
+}
+/**
+ * Extract server port from SQL instance options.
+ */
+export function getServerPort(options) {
+    if (typeof options["port"] === "number")
+        return options["port"];
+    return undefined;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0-rc0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.0-rc0";

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@8monkey/opentelemetry-instrumentation-bun-sql",
+  "version": "0.1.0-rc0",
+  "description": "OpenTelemetry instrumentation for `Bun.SQL` database client for PostgreSQL / MySQL / SQLite",
+  "keywords": [
+    "bun",
+    "mysql",
+    "opentelemetry",
+    "otel",
+    "postgresql",
+    "sqlite"
+  ],
+  "homepage": "https://hebo.ai",
+  "bugs": {
+    "url": "https://github.com/8monkey-ai/opentelemetry-instrumentation-bun-sql/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/8monkey-ai/opentelemetry-instrumentation-bun-sql.git"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "git clean -fdx -e '.env*' .",
+    "format": "oxfmt .",
+    "format:staged": "oxfmt --no-error-on-unmatched-pattern",
+    "lint": "oxlint",
+    "lint:staged": "oxlint --fix",
+    "typecheck": "oxlint --type-check",
+    "test": "bun test",
+    "check": "bun lint && bun typecheck",
+    "fix": "bun lint:staged && bun format:staged"
+  },
+  "dependencies": {
+    "@opentelemetry/instrumentation": "^0.214.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@opentelemetry/sql-common": "^0.41.2"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.4.4",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.6.1",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "bun-types": "^1.3.12",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "oxlint-tsgolint": "^0.20.0",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.3.0"
+  },
+  "peerDependenciesMeta": {}
+}