autotel/dist/db.d.ts

Write Once, Observe Anywhere

/**
 * Database Instrumentation Helpers
 *
 * Optional import: Not included in main bundle
 * Import from: 'autotel/db'
 *
 * Provides functional utilities for database query instrumentation.
 * Works with Prisma, Drizzle, TypeORM, raw SQL, and more.
 *
 * @example
 * ```typescript
 * import { instrumentDatabase } from 'autotel/db'
 *
 * const db = drizzle(pool)
 * instrumentDatabase(db, { dbSystem: 'postgresql', dbName: 'myapp' })
 *
 * // Now all queries are automatically trace
 * await db.select().from(users)
 * ```
 */
/**
 * Helper: Trace a single database query
 *
 * @example
 * ```typescript
 * import { tracebQuery } from 'autotel/db'
 *
 * const users = await tracebQuery(
 *   'postgresql',
 *   'SELECT',
 *   () => db.query('SELECT * FROM users WHERE active = true')
 * )
 * ```
 */
declare function tracebQuery<T>(dbSystem: string, operation: string, fn: () => Promise<T>, attributes?: Record<string, string | number>): Promise<T>;
/**
 * Common database operation metrics
 */
declare const DB_OPERATIONS: {
    readonly SELECT: "SELECT";
    readonly INSERT: "INSERT";
    readonly UPDATE: "UPDATE";
    readonly DELETE: "DELETE";
    readonly COUNT: "COUNT";
    readonly AGGREGATE: "AGGREGATE";
};
/**
 * Common database systems
 */
declare const DB_SYSTEMS: {
    readonly POSTGRESQL: "postgresql";
    readonly MYSQL: "mysql";
    readonly MONGODB: "mongodb";
    readonly REDIS: "redis";
    readonly SQLITE: "sqlite";
    readonly MSSQL: "mssql";
};
/**
 * Options for instrumentDatabase
 */
interface InstrumentDatabaseOptions {
    /** Database system (e.g., 'postgresql', 'mysql') */
    dbSystem: string;
    /** Database name (optional) */
    dbName?: string;
    /** Method names to instrument (if not provided, instruments common patterns) */
    methods?: string[];
    /** Method names to skip */
    skipMethods?: string[];
    /** Sanitize queries (remove sensitive data) - default: true */
    sanitizeQuery?: boolean;
    /** Slow query threshold in milliseconds - default: 1000ms */
    slowQueryThresholdMs?: number;
}
/**
 * Instrument a database client instance with OpenTelemetry tracing
 *
 * This is a function-based alternative to @DbInstrumented decorator.
 * Modifies the client in-place and returns it (idempotent - safe to call multiple times).
 *
 * Inspired by otel-drizzle and other otel instrumentation packages.
 *
 * @example Drizzle ORM
 * ```typescript
 * import { drizzle } from 'drizzle-orm/node-postgres'
 * import { instrumentDatabase } from 'autotel/db'
 *
 * const db = drizzle(pool)
 * instrumentDatabase(db, { dbSystem: 'postgresql', dbName: 'myapp' })
 *
 * // Now all db queries are automatically trace
 * await db.select().from(users)
 * ```
 *
 * @example Prisma
 * ```typescript
 * import { PrismaClient } from '@prisma/client'
 * import { instrumentDatabase } from 'autotel/db'
 *
 * const prisma = new PrismaClient()
 * instrumentDatabase(prisma, {
 *   dbSystem: 'postgresql',
 *   methods: ['findMany', 'findUnique', 'create', 'update', 'delete']
 * })
 *
 * // All specified methods are trace
 * await prisma.user.findMany()
 * ```
 *
 * @example Generic database client
 * ```typescript
 * import { instrumentDatabase } from 'autotel/db'
 *
 * const db = createDatabaseClient()
 * instrumentDatabase(db, {
 *   dbSystem: 'mongodb',
 *   methods: ['find', 'findOne', 'insertOne', 'updateOne', 'deleteOne']
 * })
 * ```
 */
declare function instrumentDatabase<T extends object>(client: T, options: InstrumentDatabaseOptions): T;

export { DB_OPERATIONS, DB_SYSTEMS, type InstrumentDatabaseOptions, instrumentDatabase, tracebQuery };