Setup Guide

Complete setup guide for development and production environments.

Development setup

src/monitoring.ts

typescript

import { createMonitor, SignalSeverity } from '@periodic/arsenic';

export const monitor = createMonitor({
  slowQueryThresholdMs: 100,   // Lower threshold for dev
  includeDocs: true,
  emitPositiveSignals: true,   // Learn healthy patterns in dev

  exporter: (event) => {
    const emoji = { critical: '🔴', warning: '⚠️', info: '✅' }[event.severity];
    console.log(emoji + ' [' + event.severity.toUpperCase() + ']', {
      query: event.model + '.' + event.operation,
      duration: event.durationMs + 'ms',
      signals: event.signals,
      callsite: event.callsite,
    });
    if (event.severity === SignalSeverity.CRITICAL) {
      console.log(JSON.stringify(event, null, 2));
    }
  },
});

Production setup

src/config/monitoring.ts

typescript

import { createMonitor, createOtelExporter, SignalSeverity } from '@periodic/arsenic';

const isProd = process.env.NODE_ENV === 'production';

export const monitor = createMonitor({
  slowQueryThresholdMs: isProd ? 300 : 100,
  includeDocs: !isProd,
  emitPositiveSignals: !isProd,

  exporter: async (event) => {
    logger.info(event, 'arsenic.query');
    if (isProd && event.severity === SignalSeverity.CRITICAL) {
      await sendToPagerDuty(event);
    }
    if (event.severity === SignalSeverity.WARNING) {
      await sendToSlack(event);
    }
  },
});

Docker setup

bash

version: '3.8'
services:
  app:
    build: .
    environment:
      - NODE_ENV=production
      - MONGODB_URI=mongodb://mongo:27017/myapp
      - REDIS_HOST=redis
    depends_on: [mongo, redis]
  mongo:
    image: mongo:6
    volumes: [mongo-data:/data/db]
  redis:
    image: redis:7-alpine
volumes:
  mongo-data:

Common troubleshooting

No events being emitted

Check adapter is attached

The monitor alone does nothing. You must call the adapter: mongooseAdapter(monitor, mongoose).

Missing request context

Middleware must be before routes

app.use(expressContext(monitor)) must come before any route handlers. Queries from routes registered before the middleware will have no request context.

typescript

// ✅ Correct
app.use(expressContext(monitor));
app.get('/api/users', handler);

// ❌ Wrong — context never runs for this route
app.get('/api/users', handler);
app.use(expressContext(monitor));

TypeScript errors

json

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}