Kysely

This guide covers how to enable query tracing with Kysely and collect PostgreSQL pool metrics.

Wrap your Kysely dialect to create query spans
Control which query and error details are recorded
Optionally collect PostgreSQL pool metrics

Overview

@monocle.sh/instrumentation-kysely wraps a Kysely dialect and creates OpenTelemetry spans for database operations. It uses your active OpenTelemetry provider and must be configured in your application. The AdonisJS agent does not install or enable this package automatically.

Installation

Install the instrumentation, Kysely, and the database driver used by your dialect. This package supports Kysely ^0.28.16.

Terminal

npm install @monocle.sh/instrumentation-kysely kysely@^0.28.16

Install the driver used by your Kysely dialect separately. The example below uses pg.

Configure query tracing

Initialize OpenTelemetry before importing your database module. Wrap your existing dialect with observeDialect() and set dbSystem to identify the database.

app/services/database.ts

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",
  }),
});

The wrapper traces queries, streams, and transaction commands. If you also enable instrumentation for the underlying database driver, each query can produce a nested driver span. Disable one layer if you want a single span per query.

Control captured data

Query text and database errors are recorded by default. Query text contains placeholders for bound parameters, but literal values in raw SQL remain in the statement. Error messages can also contain submitted values.

Set recordQueryText: false to omit SQL statements. The default maximum length is 1,022 characters; use maxQueryLength to change it.
Set recordErrors: false to omit exception details while keeping the span error status and type.
Set requireParentSpan: true to trace database operations only when a parent span is active.
Pass connection with host, port, and database to add database connection details to spans.

PostgreSQL pool metrics

Call registerPgPoolMetrics() after initializing your metrics provider. It records used and idle connections and pending requests. Call the returned function during shutdown, before closing the pool.

app/services/database.ts

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();
}

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Other

Overview

Installation

Configure query tracing

Control captured data

PostgreSQL pool metrics

​Overview

​Installation

​Configure query tracing

​Control captured data

​PostgreSQL pool metrics

Overview

Installation

Configure query tracing

Control captured data

PostgreSQL pool metrics