slow-query-detector

slow-query-detector is an advanced query observability tool designed specifically for Node.js applications. The project provides a driver-agnostic solution for effective slow database query detection and integrates seamlessly with Prisma through its optional package, @olegkoval/queryd/prisma. This enables developers to catch slow queries before they impact user experience.

Key Features

• Effortless Instrumentation: Add query monitoring in minutes instead of days, preserving the existing database client and query structure.
• Flexible Query Detection: Monitor both individual slow queries and request-level query storms, ensuring efficient database performance.
• Sampling and Monitoring: Incorporate optional sampling techniques and EXPLAIN ANALYZE capabilities to investigate slow queries in detail.
• Pluggable Sinks: The design allows for customizable logging sinks, which enables structured query events that can be routed to logs or applied monitoring tools.

Quick Start Example

Getting started with slow-query-detector is straightforward:

import postgres from "postgres";
import {
  createSlowQueryDetector,
  wrapTaggedTemplate,
  createConsoleLogger,
  runWithDbContext,
} from "@olegkoval/queryd";

const sql = postgres(process.env.DATABASE_URL!);
const detector = createSlowQueryDetector(
  {
    warnThresholdMs: 200,
    dbName: "primary",
    requestBudget: { maxQueries: 80, maxTotalDurationMs: 2_000 },
  },
  { logger: createConsoleLogger() },
);
const db = wrapTaggedTemplate(sql, detector);

await runWithDbContext({ requestId: "req-home-1", userId: "u-42" }, async () => {
  await db`select ${1}::int`;
});

Performance Benchmarking

To validate performance, the project provides benchmarking scripts:

• Run local micro-benchmarks using the command:

  npm run benchmark
  

• Utilize Docker for consistent environment tests, ensuring reliable benchmarking outcomes across different setups.

Advanced Configuration

Slow-query-detector supports advanced configurations such as request budgets, allowing developers to define limits for the maximum number of queries and total duration per request.

Integration with Prisma

For those using Prisma, integration is seamless:

import { PrismaClient } from "@prisma/client";
import { createSlowQueryDetector, createConsoleLogger, runWithDbContext } from "@olegkoval/queryd";
import { wrapPrismaClient } from "@olegkoval/queryd/prisma";

const base = new PrismaClient();
const detector = createSlowQueryDetector(
  {
    warnThresholdMs: 200,
    dbName: "primary",
    requestBudget: { maxQueries: 80, maxTotalDurationMs: 2_000 },
  },
  { logger: createConsoleLogger() },
);
export const prisma = wrapPrismaClient(base, detector);

await runWithDbContext({ requestId: "req-1", userId: "u-1" }, async () => {
  await prisma.$queryRaw`SELECT 1`;
});

Project Documentation

For additional information on usage, advanced configurations, and contributing to the project, refer to the project documentation.

By leveraging the features of slow-query-detector, developers can significantly enhance database query performance, leading to improved user experiences.