Drizzle ORM

@monocle.sh/instrumentation-drizzle creates OpenTelemetry spans for Drizzle queries. Initialize your OpenTelemetry SDK or agent before creating the database, then wrap the Drizzle instance with instrumentDrizzleClient(). The instrumentation is opt-in and is not enabled automatically by the Monocle agent.

Installation

The package requires Drizzle ORM 0.28.0 or later. Install your database driver separately. This example uses pg.

npm install @monocle.sh/instrumentation-drizzle drizzle-orm pg

Instrument your Drizzle database

Wrap the instance returned by drizzle() before using it. Set dbSystem so Monocle can identify the database in query details.

import { drizzle } from 'drizzle-orm/node-postgres'
import { instrumentDrizzleClient } from '@monocle.sh/instrumentation-drizzle'
import { Pool } from 'pg'

const pool = new Pool({ connectionString: process.env.DATABASE_URL })

export const db = instrumentDrizzleClient(drizzle(pool), {
  dbSystem: 'postgresql',
  dbName: 'app',
})

Queries and prepared queries create database spans. Queries run inside a transaction are marked with db.transaction, and query errors are recorded on their spans.

If you want to instrument the underlying client directly, use instrumentDrizzle() before passing the client to Drizzle:

import { drizzle } from 'drizzle-orm/node-postgres'
import {
  instrumentDrizzle,
  type InstrumentDrizzleConfig,
} from '@monocle.sh/instrumentation-drizzle'
import { Pool } from 'pg'

const config: InstrumentDrizzleConfig = { dbSystem: 'postgresql' }
const pool = instrumentDrizzle(new Pool({ connectionString: process.env.DATABASE_URL }), config)

export const db = drizzle(pool)

Choose one entry point for a database. Wrapping both the Drizzle instance and its underlying client can create duplicate spans for a query.

Configure query details

Pass these options to either instrumentation function:

• dbSystem identifies the database, for example postgresql, mysql, or sqlite. It defaults to unknown.
• dbName, peerName, and peerPort add database name and connection details to spans.
• captureQueryText includes SQL statements in spans by default. Set it to false to omit SQL text.
• maxQueryTextLength sets the maximum SQL statement length. It defaults to 1,000 characters.

The instrumentation creates CLIENT spans with database attributes such as the operation and table name when they can be read from the SQL statement. Transaction queries are marked with db.transaction.