Following up after a meeting with @pi0, we recently at Sentry built and db0 instrumentation in the Nuxt SDK and had some discussion on a better way to implement it with tracing channels.

Current Solution: Monkey Patching

In the current solution we iterate over the defined database instances by reading the user config and instrument each database instance by monkey patching .sql, .exec and .prepare.

Here is a snippet of the relevant parts:

db.prepare = new Proxy(db.prepare, {
  apply(target, thisArg, args: Parameters<typeof db.prepare>) {
    // Monkey patch the output statement class's `get`, `run` and `all` methods.
  },
});

db.sql = new Proxy(db.sql, {
  apply(target, thisArg, args: Parameters<typeof db.sql>) {
    // Start span and fill attributes, collect errors
  },
});

db.exec = new Proxy(db.exec, {
  apply(target, thisArg, args: Parameters<typeof db.exec>) {
    // Start span and fill attributes, collect errors
  },
});

This isn't ideal since the user can create other databases at runtime with createDatabase.

This solution is live right now in Nuxt SDK, and was going to be part of Nitro SDK which we shelved for now in order to see the outcome of making use of tracing channels around Nitro features first.

Proposal: Tracing Channels

Tracing channels are an experimental Node API that is available since 18.19 and 19.9 and it is already being used by other libraries in the ecosystem.

The main idea here is to fire events to an db0 tracing channel, something like this:

import { tracingChannel } from "node:diagnostics_channel";

const channel = tracingChannel("unjs.db");

// Example: exec with tracing
function exec(sql: string) {
  return channel.tracePromise(() => {
      checkDisposed();
      return Promise.resolve(connector.exec(sql));
    },
    { method: "exec", query: sql, connector },
  );
},

Then subscribers, like an instrumentation SDK could potentially use it like so:

import { tracingChannel } from "node:diagnostics_channel";

tracingChannel("unjs.db").subscribe({
  start: (msg) => {
     // start timing, create span, etc...
  },
  asyncEnd: (msg) => {
     // record timing, flush spans, etc..
  },
  asyncStart: () => {},
  end: () => {},
  error: (msg) => {
    // Handle errors, attach error to span, etc...
  },
});

We can discuss the details here and work towards a good proposal for it.

Notes

• .prepare is a bit unique, we may need to trace the Statement class separately since prepare itself doesn't do async work, but rather its all, run and get methods.
• Probably more context needs to be passed to the tracing events, like connector options, dialect, etc...