Kysely

@monocle.sh/instrumentation-kysely traces queries, streams, and transactions. Configure it manually after initializing OpenTelemetry; the Monocle agent does not enable it automatically.

Installation

Supports Kysely ^0.28.16 and ^0.29.6. This example uses pg:

npm install @monocle.sh/instrumentation-kysely kysely@^0.29.6 pg

Configure query tracing

Wrap your dialect with observeDialect() and set dbSystem to your database type.

import pg from 'pg'
import { Kysely, PostgresDialect } from 'kysely'
import { observeDialect } from '@monocle.sh/instrumentation-kysely'

interface Database {
  users: { id: number; name: string }
}

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

export const db = new Kysely<Database>({
  dialect: observeDialect({
    dialect: new PostgresDialect({ pool }),
    dbSystem: 'postgresql',
  }),
})

If your driver is also instrumented, queries can produce duplicate spans. Disable one instrumentation to keep a single span per query.

Use postgres.js

For postgres.js, use PostgresJSDialect from kysely-postgres-js:

npm install postgres kysely-postgres-js

import postgres from 'postgres'
import { PostgresJSDialect } from 'kysely-postgres-js'
import { observeDialect } from '@monocle.sh/instrumentation-kysely'

const dialect = observeDialect({
  dialect: new PostgresJSDialect({
    postgres: postgres(process.env.DATABASE_URL!),
  }),
  dbSystem: 'postgresql',
})

Pass this dialect to your Kysely instance. OpenTelemetry's pg instrumentation does not cover postgres.js, so it adds no duplicate spans here.

Control captured data

SQL and errors are recorded by default and may contain sensitive data. Options for observeDialect():

• recordQueryText: false: omit SQL text.
• recordErrors: false: omit error details while still marking failures.
• requireParentSpan: true: trace only within an active span.
• connection: add host, port, and database details.

Pool metrics with pg

After initializing your metrics provider, call registerPgPoolMetrics() to track used and idle connections, pending requests, and the configured limit. Stop collection before closing the pool:

import pg from 'pg'
import { registerPgPoolMetrics } from '@monocle.sh/instrumentation-kysely'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 10 })
const stopPoolMetrics = registerPgPoolMetrics({ pool, max: 10, poolName: 'main' })

export async function shutdownDatabase() {
  stopPoolMetrics()
  await pool.end()
}