Database Instrumentation

Automatic database instrumentation with OTLP span creation for observability backends (Jaeger, Honeycomb), plus query logging for Prisma and Drizzle ORMs with slow query detection, parameter sanitization, and precise timing metrics.

Prisma Setup

Basic Setup

Wrap your Prisma client with Vestig logging:

typescript

1// lib/db.ts
2import { PrismaClient } from '@prisma/client'
3import { withVestigPrisma, createPrismaLogConfig } from '@vestig/next/db'
4import { createLogger } from 'vestig'
5 
6const logger = createLogger({ namespace: 'db' })
7 
8export const prisma = withVestigPrisma(
9  new PrismaClient({
10    log: createPrismaLogConfig(),  // Required for query events
11  }),
12  { logger }
13)

Manual Event Handler

For more control, use the event handler directly:

typescript

1import { PrismaClient } from '@prisma/client'
2import { createPrismaQueryHandler } from '@vestig/next/db'
3import { createLogger } from 'vestig'
4 
5const logger = createLogger({ namespace: 'db' })
6 
7const prisma = new PrismaClient({
8  log: [{ emit: 'event', level: 'query' }],
9})
10 
11prisma.$on('query', createPrismaQueryHandler({ logger }))
12 
13export { prisma }

PostgreSQL Auto-Instrumentation (Recommended)

For OTLP span creation and precise timing metrics, use instrumentPostgres() to wrap your postgres-js client at the driver level:

typescript

1// lib/db.ts
2import postgres from 'postgres'
3import { instrumentPostgres } from '@vestig/next/db'
4import { drizzle } from 'drizzle-orm/postgres-js'
5 
6// Wrap the postgres client for automatic instrumentation
7const client = instrumentPostgres(postgres(process.env.DATABASE_URL!), {
8  slowQueryThreshold: 100,  // Mark queries over 100ms as slow
9  onQuery: (entry) => {
10    // Custom metrics callback (e.g., for noisy neighbor detection)
11    if (entry.isSlow) {
12      metrics.record('slow_query', {
13        table: entry.table,
14        duration: entry.duration,
15      })
16    }
17  }
18})
19 
20// Use with Drizzle ORM
21export const db = drizzle(client)

What Gets Instrumented

instrumentPostgres() automatically instruments:

Template literal queries: sql\SELECT * FROM users``
Unsafe queries: sql.unsafe('SELECT * FROM users')
Transactions: sql.begin(async (tx) => { ... })
SQL files: sql.file('path/to/query.sql')

OTLP Span Attributes

Each query creates a span with OpenTelemetry semantic conventions:

Attribute	Description	Example
`db.system`	Database system	`postgresql`
`db.operation`	SQL operation	`SELECT`, `INSERT`, `UPDATE`, `DELETE`
`db.statement`	SQL query (sanitized)	`SELECT * FROM users WHERE id = $1`
`db.sql.table`	Table name (if detectable)	`users`
`db.duration_ms`	Query duration	`42`
`db.rows_affected`	Rows returned/affected	`10`
`db.slow_query`	Exceeded threshold	`true`
`db.name`	Database name (if configured)	`myapp_production`

Integration with registerVestig()

Configure database instrumentation globally in your instrumentation.ts:

typescript

1// instrumentation.ts
2import { registerVestig } from '@vestig/next/instrumentation'
3 
4export function register() {
5  registerVestig({
6    serviceName: 'my-app',
7    otlp: {
8      endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
9    },
10    autoInstrument: {
11      fetch: true,
12      database: {
13        slowQueryThreshold: 100,
14        onQuery: (entry) => {
15          // Send to your metrics system
16          if (entry.isSlow) sendToMetrics(entry)
17        }
18      }
19    }
20  })
21}

Then instrumentPostgres() will automatically use these settings:

typescript

1// lib/db.ts
2import postgres from 'postgres'
3import { instrumentPostgres } from '@vestig/next/db'
4 
5// Automatically uses config from registerVestig()
6const client = instrumentPostgres(postgres(process.env.DATABASE_URL!))

Why Use instrumentPostgres()?

Feature	Drizzle Logger	instrumentPostgres()
OTLP Spans	❌	✅
Precise Timing	⚠️ Approximate	✅ Exact
Transaction Spans	❌	✅
Global Config	❌	✅
Observability Backends	❌	✅ Jaeger, Honeycomb, etc.

Drizzle Logger (Alternative)

If you only need logging (no OTLP spans), use the Drizzle logger:

typescript

1// lib/db.ts
2import { drizzle } from 'drizzle-orm/postgres-js'
3import postgres from 'postgres'
4import { createVestigDrizzleLogger } from '@vestig/next/db'
5import { createLogger } from 'vestig'
6 
7const logger = createLogger({ namespace: 'db' })
8const client = postgres(process.env.DATABASE_URL!)
9 
10export const db = drizzle(client, {
11  logger: createVestigDrizzleLogger({ logger }),
12})

With Query Timing

Use measureQuery for explicit timing:

typescript

1import { measureQuery } from '@vestig/next/db'
2 
3// Wrap expensive queries
4const users = await measureQuery(
5  () => db.select().from(users).where(eq(users.status, 'active')),
6  'SELECT * FROM users WHERE status = ?',
7  ['active'],
8  { logger }
9)

Configuration

Both Prisma and Drizzle wrappers accept the same configuration:

Option	Type	Default	Description
`enabled`	`boolean`	`true` (dev) / `false` (prod)	Enable/disable logging
`slowQueryThreshold`	`number`	`100`	Threshold in ms for slow query warnings
`logLevel`	`'all' \| 'slow' \| 'none'`	`'all'` (dev) / `'slow'` (prod)	Which queries to log
`sanitizeParams`	`boolean`	`true`	Redact sensitive parameters
`maxQueryLength`	`number`	`1000`	Truncate long queries
`namespace`	`string`	`'db'`	Logger namespace
`onQuery`	`(entry: QueryLogEntry) => void`	`undefined`	Custom callback for each query

Query Log Entry

Each logged query produces an entry with this structure:

typescript

1interface QueryLogEntry {
2  id: string                      // Unique query ID
3  timestamp: string               // ISO timestamp
4  query: string                   // SQL query (sanitized)
5  params?: unknown[]              // Parameters (sanitized)
6  duration: number                // Execution time in ms
7  isSlow: boolean                 // Exceeded threshold?
8  operation: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'OTHER'
9  table?: string                  // Detected table name
10  context?: {
11    requestId?: string            // Correlation ID
12    traceId?: string              // Trace ID
13  }
14}

Slow Query Detection

Queries exceeding the threshold are flagged and logged at warn level:

typescript

1const prisma = withVestigPrisma(
2  new PrismaClient({ log: createPrismaLogConfig() }),
3  {
4    logger,
5    slowQueryThreshold: 100,  // 100ms
6  }
7)

Output:

text

1⚠️ [db] Slow query detected (245ms) SELECT * FROM orders JOIN order_items...

Parameter Sanitization

Sensitive parameters are automatically redacted:

typescript

1// These patterns are sanitized:
2const sensitivePatterns = [
3  'password',
4  'secret',
5  'token',
6  'api_key',
7  'credit_card',
8  'ssn',
9  'social_security',
10]
11 
12// Input
13await prisma.user.create({
14  data: { email: 'test@example.com', password: 'secret123' }
15})
16 
17// Logged as
18// INSERT INTO users (email, password) VALUES ($1, $2)
19// params: ['test@example.com', '[REDACTED]']

Production Configuration

For production, log only slow queries:

typescript

1const prisma = withVestigPrisma(
2  new PrismaClient({ log: createPrismaLogConfig() }),
3  {
4    logger,
5    logLevel: 'slow',        // Only slow queries
6    slowQueryThreshold: 200, // 200ms threshold
7    enabled: true,           // Keep enabled
8  }
9)

Custom Query Callbacks

Process queries for custom analytics:

typescript

1const prisma = withVestigPrisma(
2  new PrismaClient({ log: createPrismaLogConfig() }),
3  {
4    logger,
5    onQuery: (entry) => {
6      // Send to APM
7      apm.recordQuery({
8        query: entry.query,
9        duration: entry.duration,
10        slow: entry.isSlow,
11      })
12 
13      // Track in metrics
14      metrics.histogram('db.query.duration', entry.duration, {
15        operation: entry.operation,
16        table: entry.table,
17      })
18    },
19  }
20)

Correlation with Requests

Queries are automatically correlated with the current request context:

typescript

1// In a Server Component or API Route
2import { withRequestContext } from '@vestig/next'
3 
4export async function GET(request: Request) {
5  return withRequestContext(request, async () => {
6    // This query will include requestId and traceId
7    const users = await prisma.user.findMany()
8    return Response.json(users)
9  })
10}

Log output includes context:

json

1{
2  "query": "SELECT * FROM users",
3  "duration": 12,
4  "context": {
5    "requestId": "req_abc123",
6    "traceId": "trace_xyz789"
7  }
8}

Best Practices

1. Use Appropriate Thresholds

Set thresholds based on your application:

typescript

1// API routes: stricter
2withVestigPrisma(prisma, { slowQueryThreshold: 50 })
3 
4// Background jobs: more lenient
5withVestigPrisma(prisma, { slowQueryThreshold: 500 })

2. Enable Only Slow Logging in Production

Reduce log volume without missing issues:

typescript

1withVestigPrisma(prisma, {
2  logLevel: process.env.NODE_ENV === 'production' ? 'slow' : 'all',
3})

3. Combine with Dev Overlay

View queries in the Dev Overlay during development:

typescript

1{process.env.NODE_ENV === 'development' && <VestigDevOverlay />}

4. Index Slow Queries

Use the onQuery callback to track and address slow queries:

typescript

1onQuery: (entry) => {
2  if (entry.isSlow) {
3    // Log to a separate channel for review
4    slowQueryLog.warn(`Slow: ${entry.query}`, {
5      duration: entry.duration,
6      table: entry.table,
7    })
8  }
9}

Supported Databases

Works with any database supported by Prisma or Drizzle:

PostgreSQL
MySQL
SQLite
SQL Server
MongoDB (Prisma only)
PlanetScale
Neon
Supabase

Next Steps

Dev Overlay — View queries in real-time
Tracing — Correlate queries with requests
Server Components — Database in RSC

Database Instrumentation

Prisma Setup

Basic Setup

Wrap your Prisma client with Vestig logging:

typescript

1// lib/db.ts
2import { PrismaClient } from '@prisma/client'
3import { withVestigPrisma, createPrismaLogConfig } from '@vestig/next/db'
4import { createLogger } from 'vestig'
5 
6const logger = createLogger({ namespace: 'db' })
7 
8export const prisma = withVestigPrisma(
9  new PrismaClient({
10    log: createPrismaLogConfig(),  // Required for query events
11  }),
12  { logger }
13)

Manual Event Handler

For more control, use the event handler directly:

typescript

1import { PrismaClient } from '@prisma/client'
2import { createPrismaQueryHandler } from '@vestig/next/db'
3import { createLogger } from 'vestig'
4 
5const logger = createLogger({ namespace: 'db' })
6 
7const prisma = new PrismaClient({
8  log: [{ emit: 'event', level: 'query' }],
9})
10 
11prisma.$on('query', createPrismaQueryHandler({ logger }))
12 
13export { prisma }

PostgreSQL Auto-Instrumentation (Recommended)

For OTLP span creation and precise timing metrics, use instrumentPostgres() to wrap your postgres-js client at the driver level:

typescript

1// lib/db.ts
2import postgres from 'postgres'
3import { instrumentPostgres } from '@vestig/next/db'
4import { drizzle } from 'drizzle-orm/postgres-js'
5 
6// Wrap the postgres client for automatic instrumentation
7const client = instrumentPostgres(postgres(process.env.DATABASE_URL!), {
8  slowQueryThreshold: 100,  // Mark queries over 100ms as slow
9  onQuery: (entry) => {
10    // Custom metrics callback (e.g., for noisy neighbor detection)
11    if (entry.isSlow) {
12      metrics.record('slow_query', {
13        table: entry.table,
14        duration: entry.duration,
15      })
16    }
17  }
18})
19 
20// Use with Drizzle ORM
21export const db = drizzle(client)

What Gets Instrumented

instrumentPostgres() automatically instruments:

Template literal queries: sql\SELECT * FROM users``
Unsafe queries: sql.unsafe('SELECT * FROM users')
Transactions: sql.begin(async (tx) => { ... })
SQL files: sql.file('path/to/query.sql')

OTLP Span Attributes

Each query creates a span with OpenTelemetry semantic conventions:

Attribute	Description	Example
`db.system`	Database system	`postgresql`
`db.operation`	SQL operation	`SELECT`, `INSERT`, `UPDATE`, `DELETE`
`db.statement`	SQL query (sanitized)	`SELECT * FROM users WHERE id = $1`
`db.sql.table`	Table name (if detectable)	`users`
`db.duration_ms`	Query duration	`42`
`db.rows_affected`	Rows returned/affected	`10`
`db.slow_query`	Exceeded threshold	`true`
`db.name`	Database name (if configured)	`myapp_production`

Integration with registerVestig()

Configure database instrumentation globally in your instrumentation.ts:

typescript

1// instrumentation.ts
2import { registerVestig } from '@vestig/next/instrumentation'
3 
4export function register() {
5  registerVestig({
6    serviceName: 'my-app',
7    otlp: {
8      endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
9    },
10    autoInstrument: {
11      fetch: true,
12      database: {
13        slowQueryThreshold: 100,
14        onQuery: (entry) => {
15          // Send to your metrics system
16          if (entry.isSlow) sendToMetrics(entry)
17        }
18      }
19    }
20  })
21}

Then instrumentPostgres() will automatically use these settings:

typescript

1// lib/db.ts
2import postgres from 'postgres'
3import { instrumentPostgres } from '@vestig/next/db'
4 
5// Automatically uses config from registerVestig()
6const client = instrumentPostgres(postgres(process.env.DATABASE_URL!))

Why Use instrumentPostgres()?

Feature	Drizzle Logger	instrumentPostgres()
OTLP Spans	❌	✅
Precise Timing	⚠️ Approximate	✅ Exact
Transaction Spans	❌	✅
Global Config	❌	✅
Observability Backends	❌	✅ Jaeger, Honeycomb, etc.

Drizzle Logger (Alternative)

If you only need logging (no OTLP spans), use the Drizzle logger:

typescript

1// lib/db.ts
2import { drizzle } from 'drizzle-orm/postgres-js'
3import postgres from 'postgres'
4import { createVestigDrizzleLogger } from '@vestig/next/db'
5import { createLogger } from 'vestig'
6 
7const logger = createLogger({ namespace: 'db' })
8const client = postgres(process.env.DATABASE_URL!)
9 
10export const db = drizzle(client, {
11  logger: createVestigDrizzleLogger({ logger }),
12})

With Query Timing

Use measureQuery for explicit timing:

typescript

1import { measureQuery } from '@vestig/next/db'
2 
3// Wrap expensive queries
4const users = await measureQuery(
5  () => db.select().from(users).where(eq(users.status, 'active')),
6  'SELECT * FROM users WHERE status = ?',
7  ['active'],
8  { logger }
9)

Configuration

Both Prisma and Drizzle wrappers accept the same configuration:

Option	Type	Default	Description
`enabled`	`boolean`	`true` (dev) / `false` (prod)	Enable/disable logging
`slowQueryThreshold`	`number`	`100`	Threshold in ms for slow query warnings
`logLevel`	`'all' \| 'slow' \| 'none'`	`'all'` (dev) / `'slow'` (prod)	Which queries to log
`sanitizeParams`	`boolean`	`true`	Redact sensitive parameters
`maxQueryLength`	`number`	`1000`	Truncate long queries
`namespace`	`string`	`'db'`	Logger namespace
`onQuery`	`(entry: QueryLogEntry) => void`	`undefined`	Custom callback for each query

Query Log Entry

Each logged query produces an entry with this structure:

typescript

1interface QueryLogEntry {
2  id: string                      // Unique query ID
3  timestamp: string               // ISO timestamp
4  query: string                   // SQL query (sanitized)
5  params?: unknown[]              // Parameters (sanitized)
6  duration: number                // Execution time in ms
7  isSlow: boolean                 // Exceeded threshold?
8  operation: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'OTHER'
9  table?: string                  // Detected table name
10  context?: {
11    requestId?: string            // Correlation ID
12    traceId?: string              // Trace ID
13  }
14}

Slow Query Detection

Queries exceeding the threshold are flagged and logged at warn level:

typescript

1const prisma = withVestigPrisma(
2  new PrismaClient({ log: createPrismaLogConfig() }),
3  {
4    logger,
5    slowQueryThreshold: 100,  // 100ms
6  }
7)

Output:

text

1⚠️ [db] Slow query detected (245ms) SELECT * FROM orders JOIN order_items...

Parameter Sanitization

Sensitive parameters are automatically redacted:

typescript

1// These patterns are sanitized:
2const sensitivePatterns = [
3  'password',
4  'secret',
5  'token',
6  'api_key',
7  'credit_card',
8  'ssn',
9  'social_security',
10]
11 
12// Input
13await prisma.user.create({
14  data: { email: 'test@example.com', password: 'secret123' }
15})
16 
17// Logged as
18// INSERT INTO users (email, password) VALUES ($1, $2)
19// params: ['test@example.com', '[REDACTED]']

Production Configuration

For production, log only slow queries:

typescript

1const prisma = withVestigPrisma(
2  new PrismaClient({ log: createPrismaLogConfig() }),
3  {
4    logger,
5    logLevel: 'slow',        // Only slow queries
6    slowQueryThreshold: 200, // 200ms threshold
7    enabled: true,           // Keep enabled
8  }
9)

Custom Query Callbacks

Process queries for custom analytics:

typescript

1const prisma = withVestigPrisma(
2  new PrismaClient({ log: createPrismaLogConfig() }),
3  {
4    logger,
5    onQuery: (entry) => {
6      // Send to APM
7      apm.recordQuery({
8        query: entry.query,
9        duration: entry.duration,
10        slow: entry.isSlow,
11      })
12 
13      // Track in metrics
14      metrics.histogram('db.query.duration', entry.duration, {
15        operation: entry.operation,
16        table: entry.table,
17      })
18    },
19  }
20)

Correlation with Requests

Queries are automatically correlated with the current request context:

typescript

1// In a Server Component or API Route
2import { withRequestContext } from '@vestig/next'
3 
4export async function GET(request: Request) {
5  return withRequestContext(request, async () => {
6    // This query will include requestId and traceId
7    const users = await prisma.user.findMany()
8    return Response.json(users)
9  })
10}

Log output includes context:

json

1{
2  "query": "SELECT * FROM users",
3  "duration": 12,
4  "context": {
5    "requestId": "req_abc123",
6    "traceId": "trace_xyz789"
7  }
8}

Best Practices

1. Use Appropriate Thresholds

Set thresholds based on your application:

typescript

1// API routes: stricter
2withVestigPrisma(prisma, { slowQueryThreshold: 50 })
3 
4// Background jobs: more lenient
5withVestigPrisma(prisma, { slowQueryThreshold: 500 })

2. Enable Only Slow Logging in Production

Reduce log volume without missing issues:

typescript

1withVestigPrisma(prisma, {
2  logLevel: process.env.NODE_ENV === 'production' ? 'slow' : 'all',
3})

3. Combine with Dev Overlay

View queries in the Dev Overlay during development:

typescript

1{process.env.NODE_ENV === 'development' && <VestigDevOverlay />}

4. Index Slow Queries

Use the onQuery callback to track and address slow queries:

typescript

1onQuery: (entry) => {
2  if (entry.isSlow) {
3    // Log to a separate channel for review
4    slowQueryLog.warn(`Slow: ${entry.query}`, {
5      duration: entry.duration,
6      table: entry.table,
7    })
8  }
9}

Supported Databases

Works with any database supported by Prisma or Drizzle:

PostgreSQL
MySQL
SQLite
SQL Server
MongoDB (Prisma only)
PlanetScale
Neon
Supabase

Next Steps

Dev Overlay — View queries in real-time
Tracing — Correlate queries with requests
Server Components — Database in RSC