Skip to content

Conversation

@logaretm
Copy link

@logaretm logaretm commented Nov 7, 2025

Adds Node.js tracing channels for db query operations, enabling observability and performance monitoring.

Channel Naming Convention

All channels use the db0.query convention which when coupled with tracing channels produce the following diagnostic channels:

  • tracing:db0.query:start
  • tracing:db0.query:end
  • tracing:db0.query:asyncStart
  • tracing:db0.query:asyncEnd
  • tracing:db0.query:error

Which matches nicely with fastify but there isn't a lot of convention for them other than the Node.js recommendation.

Unlike unstorage it didn't feel like we need multiple channels since more or less it boils down to executing a query.

Tracing context includes

  • query - query to be executed
  • method - source of the query like sql or exec, basically the method name.
  • dialect - the db dialect

Example

I have made it so it is opt-in like unstorage.

Users can create traced instances like so:

// opt in
import { withTracing, createDatabase } from "db0";
import sqlite from 'db0/connectors/node-sqlite';

// Create traced DB
const db = withTracing(
  createDatabase(
    sqlite({
      name: 'db',
    })
  )
);

SDKs and consumers can then do:

import { tracingChannel } from 'node:diagnostics_channel';

const channel = tracingChannel('db0.query');

channel.subscribe({
  start: (data) => {
    // start timing, or spans or whatever...
  },
  asyncEnd: (data) => {
    console.log(`${data.driver?.name} fetched ${data.keys[0]} in ${duration}ms`);
  },
  error: (data) => {
    console.error(`Error in ${data.driver?.name}:`, data.error);
  }
});

All operations emit standard tracing events: start, end, asyncStart, asyncEnd, and error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant