Following up after a meeting with @pi0, we recently at Sentry built and shipped KV storage 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 mounts via getMounts and instrument each driver by monkey patching select methods on it and reporting various span attributes depending on the method called and the driver being used.

Here is a snippet of the relevant part:

// Get all mounted storage drivers
const mounts = storage.getMounts();
for (const mount of mounts) {
  // Skip excluded mounts and root mount
  if (!userMounts.has(mount.base)) {
    continue;
  }

  instrumentDriver(mount.driver, mount.base);
}

// Wrap the mount method to instrument future runtime mounts
storage.mount = wrapStorageMount(storage);

This is great to avoid having to instrument each driver individually, you can find the instrumentation code itself around starting spans here.

This isn't ideal as it is based on the assumption that the user may have exactly one storage instance, which is mostly true for Nuxt apps which is exposed via useStorage on toolkits like Nitro's.

This means unstorage API allows them to define multiple storage instances with createStorage, so storage instances created in runtime in that way would not be instrumented if they happen to use different drivers.

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 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 unstorage tracing channel, something like this:

import { tracingChannel } from "node:diagnostics_channel";

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

// Example: getItem with tracing
function getItem(key: string, opts = {}) {
  key = normalizeKey(key);

  return channel.tracePromise(
    async () => {
      const { relativeKey, driver } = getMount(key);
      return asyncCall(driver.getItem, relativeKey, opts).then(
        (value) => destr(value) as StorageValue
      );
    },
    { op: "getItem", key }
  );
}

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

import { tracingChannel } from "node:diagnostics_channel";

tracingChannel("unjs.unstorage").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.

Potential Concerns

• unstorage also supports the browser via a driver, so a tracing channel wouldn't exist there.