feat: Sentry error monitoring integration (#38) (#91)

* feat(sentry): add @sentry/node dependency

* feat(sentry): add Sentry initialization module with environment config

* feat(sentry): wire up error capture for Discord client, commands, shard disconnect, and shutdown flush

* feat(sentry): add Express error handler middleware for API error capture

* feat(sentry): capture database pool errors

* docs: add Sentry environment variables to .env.example

* test(sentry): add tests for Sentry module initialization

* refactor(sentry): use Winston transport instead of manual captureException calls

- Created SentryTransport (src/transports/sentry.js) that forwards error/warn logs to Sentry
- Added transport to logger.js — single integration point
- Removed all manual if(sentryEnabled) checks from index.js, server.js, db.js
- Metadata 'source', 'command', 'module' auto-promoted to Sentry tags
- Stack traces reconstructed for proper Sentry grouping

* fix(sentry): use Number.isFinite for trace rate parsing, update SDK version comment, add edge case tests

Author: BillChirico

.env.example

@@ -100,6 +100,18 @@ MEM0_API_KEY=your_mem0_api_key
 # URL to POST when guild config changes (optional — notifies dashboard, 5s timeout)
 # DASHBOARD_WEBHOOK_URL=https://example.com/hooks/dashboard-config-changed
 
+# ── Sentry (Error Monitoring) ────────────────
+
+# Sentry DSN — enables error tracking and alerting (optional)
+# Get yours at https://sentry.io → Create Project → Node.js
+# SENTRY_DSN=https://[email protected]/0
+
+# Sentry environment name (optional — default: NODE_ENV or 'production')
+# SENTRY_ENVIRONMENT=production
+
+# Sentry performance sampling rate 0-1 (optional — default: 0.1 = 10%)
+# SENTRY_TRACES_RATE=0.1
+
 # ── Logging ──────────────────────────────────
 
 # Logging level (optional: debug, info, warn, error — default: info)

package.json

@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-code": "^2.1.44",
+    "@sentry/node": "^10.40.0",
     "discord.js": "^14.25.1",
     "dotenv": "^17.3.1",
     "express": "^5.2.1",

pnpm-lock.yaml

@@ -104,7 +104,7 @@ export async function initDb() {
 
     // Prevent unhandled pool errors from crashing the process
     pool.on('error', (err) => {
-      logError('Unexpected database pool error', { error: err.message });
+      logError('Unexpected database pool error', { error: err.message, source: 'database_pool' });
     });
 
     try {

src/db.js

@@ -11,6 +11,9 @@
  * - Structured logging
  */
 
+// Sentry must be imported before all other modules to instrument them
+import './sentry.js';
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -218,7 +221,7 @@ client.on('interactionCreate', async (interaction) => {
     await command.execute(interaction);
     info('Command executed', { command: commandName, user: interaction.user.tag });
   } catch (err) {
-    error('Command error', { command: commandName, error: err.message, stack: err.stack });
+    error('Command error', { command: commandName, error: err.message, stack: err.stack, source: 'slash_command' });
 
     const errorMessage = {
       content: '❌ An error occurred while executing this command.',
@@ -283,11 +286,14 @@ async function gracefulShutdown(signal) {
     error('Failed to close database pool', { error: err.message });
   }
 
-  // 5. Destroy Discord client
+  // 5. Flush Sentry events before exit (no-op if Sentry disabled)
+  await import('./sentry.js').then(({ Sentry }) => Sentry.flush(2000)).catch(() => {});
+
+  // 6. Destroy Discord client
   info('Disconnecting from Discord');
   client.destroy();
 
-  // 6. Log clean exit
+  // 7. Log clean exit
   info('Shutdown complete');
   process.exit(0);
 }
@@ -302,9 +308,16 @@ client.on('error', (err) => {
     error: err.message,
     stack: err.stack,
     code: err.code,
+    source: 'discord_client',
   });
 });
 
+client.on('shardDisconnect', (event, shardId) => {
+  if (event.code !== 1000) {
+    warn('Shard disconnected unexpectedly', { shardId, code: event.code, source: 'discord_shard' });
+  }
+});
+
 // Start bot
 const token = process.env.DISCORD_TOKEN;
 if (!token) {
@@ -421,6 +434,15 @@ async function startup() {
   await loadCommands();
   await client.login(token);
 
+  // Set Sentry context now that we know the bot identity (no-op if disabled)
+  import('./sentry.js').then(({ Sentry, sentryEnabled }) => {
+    if (sentryEnabled) {
+      Sentry.setTag('bot.username', client.user?.tag || 'unknown');
+      Sentry.setTag('bot.version', BOT_VERSION);
+      info('Sentry error monitoring enabled', { environment: process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV || 'production' });
+    }
+  }).catch(() => {});
+
   // Start REST API server with WebSocket log streaming (non-fatal — bot continues without it)
   {
     let wsTransport = null;

src/index.js

@@ -14,6 +14,8 @@ import { fileURLToPath } from 'node:url';
 import winston from 'winston';
 import DailyRotateFile from 'winston-daily-rotate-file';
 import { PostgresTransport } from './transports/postgres.js';
+import { sentryEnabled } from './sentry.js';
+import { SentryTransport } from './transports/sentry.js';
 import { WebSocketTransport } from './transports/websocket.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -204,6 +206,11 @@ if (fileOutputEnabled) {
   );
 }
 
+// Add Sentry transport if enabled — all error/warn logs automatically go to Sentry
+if (sentryEnabled) {
+  transports.push(new SentryTransport({ level: 'warn' }));
+}
+
 const logger = winston.createLogger({
   level: logLevel,
   format: winston.format.combine(winston.format.errors({ stack: true }), winston.format.splat()),

src/logger.js

@@ -0,0 +1,58 @@
+/**
+ * Sentry Error Monitoring
+ *
+ * Initializes Sentry for error tracking, performance monitoring,
+ * and alerting. Must be imported before any other application code.
+ *
+ * Configure via environment variables:
+ *   SENTRY_DSN           - Sentry project DSN (required to enable)
+ *   SENTRY_ENVIRONMENT   - Environment name (default: 'production')
+ *   SENTRY_TRACES_RATE   - Performance sampling rate 0-1 (default: 0.1)
+ *   NODE_ENV             - Used as fallback for environment name
+ */
+
+import * as Sentry from '@sentry/node';
+
+const dsn = process.env.SENTRY_DSN;
+
+/**
+ * Whether Sentry is actively initialized.
+ * Use this to guard optional Sentry calls in hot paths.
+ */
+export const sentryEnabled = Boolean(dsn);
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    environment: process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV || 'production',
+
+    // Performance monitoring — sample 10% of transactions by default
+    // Use ?? so SENTRY_TRACES_RATE=0 explicitly disables tracing
+    tracesSampleRate: (() => {
+      const parsed = parseFloat(process.env.SENTRY_TRACES_RATE);
+      return Number.isFinite(parsed) ? parsed : 0.1;
+    })(),
+
+    // Automatically capture unhandled rejections and uncaught exceptions
+    autoSessionTracking: true,
+
+    // Filter out noisy/expected errors
+    beforeSend(event) {
+      // Skip AbortError from intentional request cancellations
+      const message = event.exception?.values?.[0]?.value || '';
+      if (message.includes('AbortError') || message.includes('The operation was aborted')) {
+        return null;
+      }
+      return event;
+    },
+
+    // Add useful default tags
+    initialScope: {
+      tags: {
+        service: 'volvox-bot',
+      },
+    },
+  });
+}
+
+export { Sentry };

src/sentry.js

@@ -0,0 +1,77 @@
+/**
+ * Sentry Winston Transport
+ *
+ * Forwards error and warn level logs to Sentry automatically.
+ * This is the single integration point — no need to call
+ * Sentry.captureException() manually throughout the codebase.
+ */
+
+import Transport from 'winston-transport';
+import { Sentry } from '../sentry.js';
+
+/**
+ * Winston transport that sends error/warn logs to Sentry.
+ *
+ * - 'error' level → Sentry.captureException (if Error) or captureMessage (if string)
+ * - 'warn' level → Sentry.captureMessage with 'warning' severity
+ *
+ * Metadata from the log entry is attached as Sentry extra context,
+ * and recognized tags (source, command, module) are promoted to Sentry tags.
+ */
+export class SentryTransport extends Transport {
+  /**
+   * @param {Object} [opts]
+   * @param {string} [opts.level='error'] - Minimum log level to forward
+   */
+  constructor(opts = {}) {
+    super({ level: opts.level || 'warn', ...opts });
+  }
+
+  /**
+   * Known metadata keys to promote to Sentry tags.
+   * Everything else goes into Sentry 'extra' context.
+   */
+  static TAG_KEYS = new Set(['source', 'command', 'module', 'code', 'shardId']);
+
+  /**
+   * @param {Object} info - Winston log info object
+   * @param {Function} callback
+   */
+  log(info, callback) {
+    const { level, message, timestamp, stack, ...meta } = info;
+
+    // Separate tags from extra context
+    const tags = {};
+    const extra = {};
+    for (const [key, value] of Object.entries(meta)) {
+      if (SentryTransport.TAG_KEYS.has(key) && (typeof value === 'string' || typeof value === 'number')) {
+        tags[key] = String(value);
+      } else if (key !== 'originalLevel' && key !== 'splat') {
+        extra[key] = value;
+      }
+    }
+
+    const context = {
+      tags,
+      extra,
+    };
+
+    if (level === 'error') {
+      // If we have a stack trace, reconstruct an Error for better Sentry grouping
+      if (stack) {
+        const err = new Error(message);
+        err.stack = stack;
+        Sentry.captureException(err, context);
+      } else if (meta.error && typeof meta.error === 'string') {
+        // Common pattern: error('Something failed', { error: err.message })
+        Sentry.captureMessage(`${message}: ${meta.error}`, { ...context, level: 'error' });
+      } else {
+        Sentry.captureMessage(message, { ...context, level: 'error' });
+      }
+    } else if (level === 'warn') {
+      Sentry.captureMessage(message, { ...context, level: 'warning' });
+    }
+
+    callback();
+  }
+}

src/transports/sentry.js

@@ -698,6 +698,7 @@ describe('index.js', () => {
       error: 'discord broke',
       stack: 'stack',
       code: 500,
+      source: 'discord_client',
     });
   });
 

tests/index.test.js

@@ -0,0 +1,50 @@
+/**
+ * Tests for Sentry integration module
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('sentry module', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('should export sentryEnabled as false when SENTRY_DSN is not set', async () => {
+    vi.stubEnv('SENTRY_DSN', '');
+    const mod = await import('../src/sentry.js');
+    expect(mod.sentryEnabled).toBe(false);
+  });
+
+  it('should export Sentry namespace', async () => {
+    vi.stubEnv('SENTRY_DSN', '');
+    const mod = await import('../src/sentry.js');
+    expect(mod.Sentry).toBeDefined();
+    expect(typeof mod.Sentry.captureException).toBe('function');
+    expect(typeof mod.Sentry.captureMessage).toBe('function');
+  });
+
+  it('should export sentryEnabled as true when SENTRY_DSN is set', async () => {
+    vi.stubEnv('SENTRY_DSN', 'https://[email protected]/0');
+    const mod = await import('../src/sentry.js');
+    expect(mod.sentryEnabled).toBe(true);
+  });
+
+  it('should allow SENTRY_TRACES_RATE=0 to disable tracing', async () => {
+    vi.stubEnv('SENTRY_DSN', '');
+    vi.stubEnv('SENTRY_TRACES_RATE', '0');
+    // Module parses rate independently of DSN — just verify it doesn't throw
+    const mod = await import('../src/sentry.js');
+    expect(mod.Sentry).toBeDefined();
+  });
+
+  it('should fall back to default trace rate for non-numeric values', async () => {
+    vi.stubEnv('SENTRY_DSN', '');
+    vi.stubEnv('SENTRY_TRACES_RATE', 'not-a-number');
+    const mod = await import('../src/sentry.js');
+    expect(mod.Sentry).toBeDefined();
+  });
+});