API Reference

Complete type-safe API for @periodic/arsenic.

createMonitor

typescript

function createMonitor(config: MonitorConfig): Monitor

interface MonitorConfig {
  slowQueryThresholdMs?: number   // Default: 200
  exporter: Exporter              // Required
  emitPositiveSignals?: boolean   // Default: false
  includeDocs?: boolean           // Default: true
}

Option	Type	Default	Description
`slowQueryThresholdMs`	`number`	`200`	Threshold in ms for slow query detection
`exporter`	`Exporter`	`—`	Required. Function that receives all emitted events
`emitPositiveSignals`	`boolean`	`false`	Enable INFO-level healthy signals
`includeDocs`	`boolean`	`true`	Include signal explanations in events

Framework adapters

typescript

// Express — add BEFORE routes
function expressContext(
  monitor: Monitor,
  options?: { attachUser?: (req: Request) => string | undefined }
): RequestHandler

// Fastify — register as plugin
function fastifyContext(
  monitor: Monitor,
  options?: { attachUser?: (req: FastifyRequest) => string | undefined }
): FastifyPlugin

Database adapters

typescript

function mongooseAdapter(monitor: Monitor, mongoose: Mongoose): void
function prismaAdapter(monitor: Monitor, prisma: PrismaClient): void
function pgAdapter(monitor: Monitor, pool: Pool): void
function redisAdapter(monitor: Monitor, client: Redis | RedisClient): void

Redis utilities

typescript

function getRedisCommandInfo(command: string): {
  command: string
  category: 'dangerous' | 'blocking' | 'slow' | 'normal'
  docs: string
}

const SLOW_REDIS_COMMANDS: string[]
const REDIS_COMMAND_INFO: Record<string, { category: string; docs: string }>

Exporters

typescript

function createOtelExporter(options: {
  serviceName: string
  exportAsSpans?: boolean
  exportAsMetrics?: boolean
}): Exporter

ForgeEvent interface

typescript

interface ForgeEvent {
  type: 'db.query'
  db: string
  adapter: string
  model: string
  operation: string
  durationMs: number
  slow: boolean
  signals: ForgeSignal[]
  severity: SignalSeverity
  explanations: Record<string, {
    summary: string
    detail: string
    severity: 'critical' | 'warning' | 'info'
    docs?: string
  }>
  request?: {
    id: string
    method: string
    route: string
    userId?: string
  }
  callsite?: {
    file: string
    line: number
  }
  metadata?: {
    limit?: number | null
    query?: string
    rowsAffected?: number
    cpuUsage?: number
    memoryUsage?: number
    cacheHit?: boolean
    payloadSize?: number
    retryCount?: number
    connectionReused?: boolean
    indexUsed?: boolean
    command?: string
    commandCategory?: string
    commandDocs?: string
    args?: any
    error?: string
    [key: string]: any
  }
  timestamp: string
}

enum SignalSeverity {
  CRITICAL = 'critical',
  WARNING  = 'warning',
  INFO     = 'info',
}

TypeScript imports

typescript

import type {
  ForgeEvent,
  ForgeSignal,
  SignalSeverity,
  Exporter,
  MonitorConfig,
  QueryMetadata,
  RequestContext,
} from '@periodic/arsenic';