@sentienguard/apm 1.0.0 → 1.0.3

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@sentienguard/apm",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "SentienGuard APM SDK - Minimal, production-safe application performance monitoring",
   "main": "src/index.js",
   "type": "module",
+  "browser": "./src/browser.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "browser": "./src/browser.js",
+      "default": "./src/index.js"
+    }
   },
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
@@ -16,7 +20,10 @@
     "monitoring",
     "performance",
     "metrics",
-    "sentienguard"
+    "sentienguard",
+    "mongodb",
+    "circuit-breaker",
+    "observability"
   ],
   "author": "SentienGuard",
   "license": "MIT",
@@ -26,7 +33,18 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "peerDependencies": {},
+  "peerDependencies": {
+    "mongoose": ">=6.0.0",
+    "opossum": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": true
+    },
+    "opossum": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "jest": "^29.7.0"
   },

package/src/aggregator.js

@@ -5,6 +5,7 @@
  *
  * Aggregation key: (service, method, route) for requests
  * Aggregation key: (service, name, type) for dependencies
+ * Aggregation key: (collection, operation) for MongoDB operations
  */
 
 import { RouteRegistry } from './normalizer.js';
@@ -24,6 +25,20 @@ function createDependencyKey(name, type) {
   return `${name}:${type}`;
 }
 
+/**
+ * Create an aggregation key for MongoDB operation metrics
+ */
+function createMongoKey(collection, operation) {
+  return `${collection}:${operation}`;
+}
+
+/**
+ * Create an aggregation key for OpenAI operation metrics
+ */
+function createOpenAIKey(operation, model) {
+  return `${operation}:${model}`;
+}
+
 /**
  * Metrics Aggregator class
  * Maintains in-memory aggregated metrics that are flushed periodically
@@ -44,6 +59,28 @@ export class MetricsAggregator {
     // Dependency metrics: Map<key, {name, type, count, errorCount, latency: {sum, min, max}}>
     this.dependencies = new Map();
 
+    // MongoDB operation metrics: Map<key, {collection, operation, count, errorCount, latency: {sum, min, max}}>
+    this.mongodbOperations = new Map();
+
+    // MongoDB slow queries: Array<{collection, operation, latency, timestamp}>
+    this.slowQueries = [];
+
+    // OpenAI operation metrics: Map<key, {operation, model, count, errorCount, latency, tokens, cost}>
+    this.openaiOperations = new Map();
+
+    // MongoDB connection pool stats (updated periodically, not reset)
+    if (!this.mongodbPoolStats) {
+      this.mongodbPoolStats = {
+        active: 0,
+        idle: 0,
+        waitQueueSize: 0,
+        lastUpdated: null
+      };
+    }
+
+    // Circuit breaker state changes: Array<{service, state, timestamp}>
+    this.circuitBreakerStates = [];
+
     // Error counter for unhandled exceptions
     this.unhandledErrors = 0;
   }
@@ -131,11 +168,162 @@ export class MetricsAggregator {
     this.unhandledErrors++;
   }
 
+  /**
+   * Record a MongoDB operation
+   *
+   * @param {string} collection - Collection name
+   * @param {string} operation - Operation type (find, insert, update, delete, aggregate)
+   * @param {number} latency - Response time in milliseconds
+   * @param {boolean} isError - Whether the operation resulted in an error
+   */
+  recordMongoOperation(collection, operation, latency, isError = false) {
+    const key = createMongoKey(collection, operation);
+
+    let metric = this.mongodbOperations.get(key);
+    if (!metric) {
+      metric = {
+        collection,
+        operation,
+        count: 0,
+        errorCount: 0,
+        latency: {
+          sum: 0,
+          min: Infinity,
+          max: 0
+        }
+      };
+      this.mongodbOperations.set(key, metric);
+    }
+
+    metric.count++;
+    if (isError) {
+      metric.errorCount++;
+    }
+
+    metric.latency.sum += latency;
+    metric.latency.min = Math.min(metric.latency.min, latency);
+    metric.latency.max = Math.max(metric.latency.max, latency);
+  }
+
+  /**
+   * Record a slow MongoDB query
+   *
+   * @param {string} collection - Collection name
+   * @param {string} operation - Operation type
+   * @param {number} latency - Response time in milliseconds
+   */
+  recordSlowQuery(collection, operation, latency) {
+    // Keep only the most recent slow queries (max 100 per interval)
+    if (this.slowQueries.length >= 100) {
+      this.slowQueries.shift();
+    }
+
+    this.slowQueries.push({
+      collection,
+      operation,
+      latency: Math.round(latency),
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Record an OpenAI API operation
+   *
+   * @param {Object} data - Operation data
+   * @param {string} data.operation - Operation type (chat.completions, embeddings, images.generate, etc.)
+   * @param {string} data.model - Model used (gpt-4, gpt-3.5-turbo, etc.)
+   * @param {number} data.latency - Response time in milliseconds
+   * @param {number} data.promptTokens - Number of prompt tokens used
+   * @param {number} data.completionTokens - Number of completion tokens used
+   * @param {number} data.totalTokens - Total tokens used
+   * @param {number} data.cost - Estimated cost in USD
+   * @param {string|null} data.error - Error message if failed
+   * @param {number} data.statusCode - HTTP status code
+   */
+  recordOpenAIOperation(data) {
+    const key = createOpenAIKey(data.operation, data.model);
+
+    let metric = this.openaiOperations.get(key);
+    if (!metric) {
+      metric = {
+        operation: data.operation,
+        model: data.model,
+        count: 0,
+        errorCount: 0,
+        latency: {
+          sum: 0,
+          min: Infinity,
+          max: 0
+        },
+        tokens: {
+          prompt: 0,
+          completion: 0,
+          total: 0
+        },
+        cost: 0
+      };
+      this.openaiOperations.set(key, metric);
+    }
+
+    metric.count++;
+    if (data.error) {
+      metric.errorCount++;
+    }
+
+    metric.latency.sum += data.latency;
+    metric.latency.min = Math.min(metric.latency.min, data.latency);
+    metric.latency.max = Math.max(metric.latency.max, data.latency);
+
+    metric.tokens.prompt += data.promptTokens || 0;
+    metric.tokens.completion += data.completionTokens || 0;
+    metric.tokens.total += data.totalTokens || 0;
+
+    metric.cost += data.cost || 0;
+  }
+
+  /**
+   * Update MongoDB connection pool statistics
+   *
+   * @param {Object} stats - Pool statistics
+   * @param {number} stats.active - Active connections (checked out)
+   * @param {number} stats.idle - Idle connections (available in pool)
+   * @param {number} stats.waitQueueSize - Wait queue size
+   * @param {number} stats.total - Total connections in pool
+   */
+  updatePoolStats(stats) {
+    this.mongodbPoolStats = {
+      active: stats.active || 0,
+      idle: stats.idle || 0,
+      waitQueueSize: stats.waitQueueSize || 0,
+      total: stats.total || (stats.active || 0) + (stats.idle || 0),
+      lastUpdated: Date.now()
+    };
+  }
+
+  /**
+   * Record a circuit breaker state change
+   *
+   * @param {string} service - Service/dependency name (e.g., 'mongodb')
+   * @param {string} state - New state ('open', 'halfOpen', 'close')
+   */
+  recordCircuitState(service, state) {
+    this.circuitBreakerStates.push({
+      service,
+      state,
+      timestamp: Date.now()
+    });
+  }
+
   /**
    * Check if there's data to flush
    */
   hasData() {
-    return this.requests.size > 0 || this.dependencies.size > 0;
+    return this.requests.size > 0 ||
+           this.dependencies.size > 0 ||
+           this.mongodbOperations.size > 0 ||
+           this.slowQueries.length > 0 ||
+           this.circuitBreakerStates.length > 0 ||
+           this.openaiOperations.size > 0;
   }
 
   /**
@@ -148,7 +336,12 @@ export class MetricsAggregator {
       service: config.service,
       environment: config.environment,
       requests: [],
-      dependencies: []
+      dependencies: [],
+      mongodb: [],
+      mongodbPool: null,
+      slowQueries: [],
+      circuitBreaker: [],
+      openai: []
     };
 
     // Convert request metrics to array
@@ -181,6 +374,53 @@ export class MetricsAggregator {
       });
     }
 
+    // Convert MongoDB operation metrics to array
+    for (const metric of this.mongodbOperations.values()) {
+      payload.mongodb.push({
+        collection: metric.collection,
+        operation: metric.operation,
+        count: metric.count,
+        errorCount: metric.errorCount,
+        latency: {
+          sum: Math.round(metric.latency.sum),
+          min: metric.latency.min === Infinity ? 0 : Math.round(metric.latency.min),
+          max: Math.round(metric.latency.max)
+        }
+      });
+    }
+
+    // Include MongoDB pool stats if available
+    if (this.mongodbPoolStats && this.mongodbPoolStats.lastUpdated) {
+      payload.mongodbPool = { ...this.mongodbPoolStats };
+    }
+
+    // Include slow queries
+    payload.slowQueries = [...this.slowQueries];
+
+    // Include circuit breaker state changes
+    payload.circuitBreaker = [...this.circuitBreakerStates];
+
+    // Convert OpenAI operation metrics to array
+    for (const metric of this.openaiOperations.values()) {
+      payload.openai.push({
+        operation: metric.operation,
+        model: metric.model,
+        count: metric.count,
+        errorCount: metric.errorCount,
+        latency: {
+          sum: Math.round(metric.latency.sum),
+          min: metric.latency.min === Infinity ? 0 : Math.round(metric.latency.min),
+          max: Math.round(metric.latency.max)
+        },
+        tokens: {
+          prompt: metric.tokens.prompt,
+          completion: metric.tokens.completion,
+          total: metric.tokens.total
+        },
+        cost: Math.round(metric.cost * 1000000) / 1000000 // 6 decimal places
+      });
+    }
+
     // Reset for next interval
     this.reset();
 
@@ -194,6 +434,10 @@ export class MetricsAggregator {
     return {
       requestMetrics: this.requests.size,
       dependencyMetrics: this.dependencies.size,
+      mongodbMetrics: this.mongodbOperations.size,
+      openaiMetrics: this.openaiOperations.size,
+      slowQueries: this.slowQueries.length,
+      circuitBreakerEvents: this.circuitBreakerStates.length,
       uniqueRoutes: this.routeRegistry.size,
       unhandledErrors: this.unhandledErrors
     };

package/src/browser.js

@@ -0,0 +1,107 @@
+/**
+ * SentienGuard APM SDK - Browser No-Op
+ *
+ * This module is automatically used when the SDK is imported in a browser
+ * environment (via bundlers like Webpack, Vite, Rsbuild, etc.).
+ *
+ * The APM SDK only works in Node.js (it patches http/https modules),
+ * so in the browser we export no-op stubs to avoid build errors.
+ */
+
+const noop = () => {};
+const asyncNoop = async () => {};
+const noopMiddleware = (_req, _res, next) => next?.();
+
+function initialize() {}
+async function shutdown() {}
+function getStatus() {
+  return {
+    enabled: false,
+    initialized: false,
+    config: { service: '', environment: '', flushInterval: 0 },
+    stats: {}
+  };
+}
+function flush() {}
+function getConfig() {
+  return {};
+}
+function isEnabled() {
+  return false;
+}
+function normalizeRoute(route) {
+  return route;
+}
+function extractRoute(req) {
+  return req?.url || '/';
+}
+function getAggregator() {
+  return {
+    getStats: () => ({}),
+    recordRequest: noop,
+    recordDependency: noop,
+    recordError: noop
+  };
+}
+function instrumentMongoDB() {}
+function instrumentOpenAI() {}
+function createBreaker(fn) {
+  return fn;
+}
+function wrapMongoOperation(fn) {
+  return fn;
+}
+function getBreakerStats() {
+  return {};
+}
+
+const RouteRegistry = {
+  register: noop,
+  match: () => null
+};
+
+const expressMiddleware = noopMiddleware;
+const expressErrorMiddleware = (_err, _req, _res, next) => next?.();
+const fastifyPlugin = noop;
+const fastifyErrorHandler = noop;
+
+export {
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+  getConfig,
+  isEnabled,
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  RouteRegistry,
+  getAggregator,
+  instrumentMongoDB,
+  instrumentOpenAI,
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats
+};
+
+export default {
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  getAggregator,
+  instrumentMongoDB,
+  instrumentOpenAI,
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats
+};

package/src/circuitBreaker.js

@@ -0,0 +1,254 @@
+/**
+ * Circuit Breaker Module
+ *
+ * Provides circuit breaker functionality using Opossum library.
+ * Wraps operations (especially database calls) to prevent cascade failures.
+ *
+ * Circuit States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped due to failures, requests fail fast
+ * - HALF-OPEN: Testing if service recovered, limited requests allowed
+ *
+ * Usage:
+ *   import { createBreaker, wrapMongoOperation } from './circuitBreaker.js';
+ *
+ *   // Wrap an async operation
+ *   const breaker = createBreaker(async () => await db.query(), { name: 'db-query' });
+ *   const result = await breaker.fire();
+ *
+ *   // Or use the MongoDB helper
+ *   const findUsers = wrapMongoOperation('User.find', async () => User.find());
+ *   const users = await findUsers();
+ */
+
+import config, { debug, warn } from './config.js';
+import { getAggregator } from './aggregator.js';
+
+// Store active circuit breakers
+const breakers = new Map();
+
+// Check if opossum is available
+let CircuitBreaker = null;
+
+/**
+ * Initialize Opossum (lazy load)
+ */
+async function initOpossum() {
+  if (CircuitBreaker) return true;
+
+  try {
+    const opossum = await import('opossum');
+    CircuitBreaker = opossum.default || opossum;
+    debug('Opossum circuit breaker loaded');
+    return true;
+  } catch (err) {
+    debug('Opossum not installed. Circuit breaker disabled. Install with: npm install opossum');
+    return false;
+  }
+}
+
+/**
+ * Default circuit breaker options
+ */
+function getDefaultOptions() {
+  return {
+    timeout: config.circuitBreaker.timeout,
+    errorThresholdPercentage: config.circuitBreaker.errorThresholdPercentage,
+    resetTimeout: config.circuitBreaker.resetTimeout,
+    volumeThreshold: config.circuitBreaker.volumeThreshold
+  };
+}
+
+/**
+ * Create a circuit breaker for an async operation
+ *
+ * @param {Function} asyncFn - The async function to wrap
+ * @param {Object} options - Circuit breaker options
+ * @param {string} options.name - Name for the circuit (used for metrics)
+ * @param {number} options.timeout - Timeout in ms
+ * @param {number} options.errorThresholdPercentage - Error threshold to trip
+ * @param {number} options.resetTimeout - Time before attempting recovery
+ * @param {Function} options.fallback - Fallback function when circuit is open
+ * @returns {Object} Circuit breaker instance or wrapped function if opossum unavailable
+ */
+export async function createBreaker(asyncFn, options = {}) {
+  if (!config.circuitBreaker.enabled) {
+    debug('Circuit breaker disabled, returning passthrough');
+    return createPassthrough(asyncFn);
+  }
+
+  const initialized = await initOpossum();
+  if (!initialized) {
+    return createPassthrough(asyncFn);
+  }
+
+  const name = options.name || 'unnamed';
+  const breakerOptions = {
+    ...getDefaultOptions(),
+    ...options,
+    name
+  };
+
+  const breaker = new CircuitBreaker(asyncFn, breakerOptions);
+  const aggregator = getAggregator();
+
+  // Attach event listeners for metrics
+  breaker.on('open', () => {
+    aggregator.recordCircuitState(name, 'open');
+    warn(`Circuit breaker OPEN: ${name}`);
+  });
+
+  breaker.on('halfOpen', () => {
+    aggregator.recordCircuitState(name, 'halfOpen');
+    debug(`Circuit breaker HALF-OPEN: ${name}`);
+  });
+
+  breaker.on('close', () => {
+    aggregator.recordCircuitState(name, 'close');
+    debug(`Circuit breaker CLOSED: ${name}`);
+  });
+
+  breaker.on('fallback', (result) => {
+    debug(`Circuit breaker fallback executed: ${name}`);
+  });
+
+  breaker.on('timeout', () => {
+    debug(`Circuit breaker timeout: ${name}`);
+  });
+
+  breaker.on('reject', () => {
+    debug(`Circuit breaker rejected (circuit open): ${name}`);
+  });
+
+  // Register fallback if provided
+  if (options.fallback) {
+    breaker.fallback(options.fallback);
+  }
+
+  // Store reference
+  breakers.set(name, breaker);
+
+  return breaker;
+}
+
+/**
+ * Create a passthrough wrapper when circuit breaker is disabled
+ */
+function createPassthrough(asyncFn) {
+  return {
+    fire: (...args) => asyncFn(...args),
+    fallback: () => {},
+    on: () => {},
+    isOpen: () => false,
+    isClosed: () => true,
+    stats: { fires: 0, failures: 0, successes: 0 }
+  };
+}
+
+/**
+ * Create a circuit breaker specifically for MongoDB operations
+ *
+ * @param {string} operationName - Name of the operation (e.g., 'User.find')
+ * @param {Function} mongoOperation - The MongoDB operation function
+ * @param {Object} options - Additional options
+ * @returns {Function} Wrapped function that uses circuit breaker
+ */
+export async function wrapMongoOperation(operationName, mongoOperation, options = {}) {
+  const breaker = await createBreaker(mongoOperation, {
+    name: `mongodb:${operationName}`,
+    // MongoDB-specific defaults
+    timeout: options.timeout || config.circuitBreaker.timeout,
+    errorThresholdPercentage: options.errorThresholdPercentage || 50,
+    resetTimeout: options.resetTimeout || 30000,
+    ...options
+  });
+
+  // Return a function that fires the breaker
+  return async function wrappedOperation(...args) {
+    return breaker.fire(...args);
+  };
+}
+
+/**
+ * Get a registered circuit breaker by name
+ *
+ * @param {string} name - Circuit breaker name
+ * @returns {Object|null} Circuit breaker instance or null
+ */
+export function getBreaker(name) {
+  return breakers.get(name) || null;
+}
+
+/**
+ * Get all registered circuit breakers
+ *
+ * @returns {Map} Map of circuit breaker instances
+ */
+export function getAllBreakers() {
+  return new Map(breakers);
+}
+
+/**
+ * Get circuit breaker statistics
+ *
+ * @param {string} name - Circuit breaker name (optional, returns all if not provided)
+ * @returns {Object} Statistics object
+ */
+export function getBreakerStats(name) {
+  if (name) {
+    const breaker = breakers.get(name);
+    if (!breaker) return null;
+
+    return {
+      name,
+      state: breaker.opened ? 'open' : (breaker.halfOpen ? 'halfOpen' : 'closed'),
+      stats: breaker.stats
+    };
+  }
+
+  // Return stats for all breakers
+  const allStats = {};
+  for (const [breakerName, breaker] of breakers) {
+    allStats[breakerName] = {
+      state: breaker.opened ? 'open' : (breaker.halfOpen ? 'halfOpen' : 'closed'),
+      stats: breaker.stats
+    };
+  }
+  return allStats;
+}
+
+/**
+ * Reset a circuit breaker (close it)
+ *
+ * @param {string} name - Circuit breaker name
+ */
+export function resetBreaker(name) {
+  const breaker = breakers.get(name);
+  if (breaker && typeof breaker.close === 'function') {
+    breaker.close();
+    debug(`Circuit breaker reset: ${name}`);
+  }
+}
+
+/**
+ * Shutdown all circuit breakers
+ */
+export function shutdownBreakers() {
+  for (const [name, breaker] of breakers) {
+    if (typeof breaker.shutdown === 'function') {
+      breaker.shutdown();
+    }
+  }
+  breakers.clear();
+  debug('All circuit breakers shutdown');
+}
+
+export default {
+  createBreaker,
+  wrapMongoOperation,
+  getBreaker,
+  getAllBreakers,
+  getBreakerStats,
+  resetBreaker,
+  shutdownBreakers
+};