@sentienguard/apm 1.0.0

package/src/errors.js

@@ -0,0 +1,132 @@
+/**
+ * Error Capture
+ * Captures unhandled exceptions and associates them with error counters.
+ *
+ * Stack traces are captured locally but NOT sent to backend in v1.
+ * Only error counters are aggregated and sent.
+ */
+
+import { getAggregator } from './aggregator.js';
+import { debug, warn } from './config.js';
+
+let isCapturing = false;
+let originalUncaughtException = null;
+let originalUnhandledRejection = null;
+
+/**
+ * Handle uncaught exception
+ */
+function handleUncaughtException(error) {
+  debug('Captured uncaught exception:', error.message);
+
+  const aggregator = getAggregator();
+  aggregator.recordError();
+
+  // Log locally but don't crash (let the original handler decide)
+  if (originalUncaughtException) {
+    // If there was a previous handler, call it
+    originalUncaughtException(error);
+  } else {
+    // Default behavior: log and continue
+    // We don't re-throw to avoid double handling
+    warn('Uncaught exception:', error.message);
+  }
+}
+
+/**
+ * Handle unhandled promise rejection
+ */
+function handleUnhandledRejection(reason, promise) {
+  const message = reason instanceof Error ? reason.message : String(reason);
+  debug('Captured unhandled rejection:', message);
+
+  const aggregator = getAggregator();
+  aggregator.recordError();
+
+  // Call previous handler if exists
+  if (originalUnhandledRejection) {
+    originalUnhandledRejection(reason, promise);
+  } else {
+    warn('Unhandled rejection:', message);
+  }
+}
+
+/**
+ * Start capturing unhandled errors
+ */
+export function startErrorCapture() {
+  if (isCapturing) {
+    debug('Error capture already active, skipping');
+    return;
+  }
+
+  // Store any existing handlers
+  const existingUncaught = process.listeners('uncaughtException');
+  const existingRejection = process.listeners('unhandledRejection');
+
+  if (existingUncaught.length > 0) {
+    originalUncaughtException = existingUncaught[existingUncaught.length - 1];
+  }
+  if (existingRejection.length > 0) {
+    originalUnhandledRejection = existingRejection[existingRejection.length - 1];
+  }
+
+  // Add our handlers
+  process.on('uncaughtException', handleUncaughtException);
+  process.on('unhandledRejection', handleUnhandledRejection);
+
+  isCapturing = true;
+  debug('Error capture enabled');
+}
+
+/**
+ * Stop capturing errors (for cleanup/testing)
+ */
+export function stopErrorCapture() {
+  if (!isCapturing) return;
+
+  process.removeListener('uncaughtException', handleUncaughtException);
+  process.removeListener('unhandledRejection', handleUnhandledRejection);
+
+  originalUncaughtException = null;
+  originalUnhandledRejection = null;
+
+  isCapturing = false;
+  debug('Error capture disabled');
+}
+
+/**
+ * Create Express error middleware
+ * Use this as the last middleware to capture Express errors
+ */
+export function expressErrorMiddleware() {
+  return function sentienguardErrorMiddleware(err, req, res, next) {
+    debug('Captured Express error:', err.message);
+
+    const aggregator = getAggregator();
+    aggregator.recordError();
+
+    // Pass to next error handler
+    next(err);
+  };
+}
+
+/**
+ * Create Fastify error handler hook
+ */
+export function fastifyErrorHandler(error, request, reply) {
+  debug('Captured Fastify error:', error.message);
+
+  const aggregator = getAggregator();
+  aggregator.recordError();
+
+  // Re-throw to let Fastify handle it
+  throw error;
+}
+
+export default {
+  startErrorCapture,
+  stopErrorCapture,
+  expressErrorMiddleware,
+  fastifyErrorHandler
+};

package/src/index.js

@@ -0,0 +1,175 @@
+/**
+ * SentienGuard APM SDK
+ *
+ * Minimal, production-safe APM that runs inside client applications
+ * and sends aggregated metrics to the SentienGuard backend.
+ *
+ * Usage:
+ *   import "@sentienguard/apm";
+ *
+ * That's it. No function calls, no setup code, no decorators.
+ *
+ * Configuration via environment variables:
+ *   SENTIENGUARD_APM_KEY=xxxx          (required)
+ *   SENTIENGUARD_SERVICE=my-api        (required)
+ *   SENTIENGUARD_ENV=production        (optional, default: production)
+ *   SENTIENGUARD_ENDPOINT=https://...  (optional)
+ *   SENTIENGUARD_FLUSH_INTERVAL=10     (optional, seconds)
+ *
+ * No config → SDK disables itself silently.
+ */
+
+import config, { isEnabled, debug, warn, getConfig } from './config.js';
+import { instrumentHttp, expressMiddleware, fastifyPlugin } from './instrumentation.js';
+import { instrumentDependencies } from './dependencies.js';
+import { startErrorCapture, expressErrorMiddleware, fastifyErrorHandler } from './errors.js';
+import { startFlushing, stopFlushing, finalFlush, flush } from './transport.js';
+import { getAggregator } from './aggregator.js';
+import { normalizeRoute, extractRoute, RouteRegistry } from './normalizer.js';
+
+let isInitialized = false;
+
+/**
+ * Initialize the SDK
+ * Called automatically on import
+ */
+function initialize() {
+  if (isInitialized) {
+    debug('SDK already initialized');
+    return;
+  }
+
+  // Check if SDK should be enabled
+  if (!isEnabled()) {
+    // Silently disable - this is expected behavior
+    debug('SDK disabled (missing API key or service name)');
+    return;
+  }
+
+  // Warn if this import is not first (other modules may have created servers already)
+  // We can't reliably detect this, so just log for debugging
+  debug(`Initializing SDK for service: ${config.service}`);
+  debug(`Environment: ${config.environment}`);
+  debug(`Endpoint: ${config.endpoint}`);
+  debug(`Flush interval: ${config.flushInterval}s`);
+
+  // Instrument HTTP (incoming requests)
+  instrumentHttp();
+
+  // Instrument dependencies (outgoing requests)
+  instrumentDependencies();
+
+  // Start error capture
+  startErrorCapture();
+
+  // Start periodic flush
+  startFlushing();
+
+  // Handle graceful shutdown
+  setupGracefulShutdown();
+
+  isInitialized = true;
+  debug('SDK initialized successfully');
+}
+
+/**
+ * Setup graceful shutdown handlers
+ */
+function setupGracefulShutdown() {
+  const shutdown = async (signal) => {
+    debug(`Received ${signal}, performing graceful shutdown`);
+
+    // Stop accepting new data
+    stopFlushing();
+
+    // Final flush
+    await finalFlush();
+
+    debug('Shutdown complete');
+  };
+
+  // Handle common shutdown signals
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+  process.once('SIGINT', () => shutdown('SIGINT'));
+
+  // Handle process exit
+  process.once('beforeExit', () => shutdown('beforeExit'));
+}
+
+/**
+ * Shutdown the SDK
+ * Call this before process exit for clean shutdown
+ */
+async function shutdown() {
+  if (!isInitialized) return;
+
+  debug('Shutting down SDK');
+
+  stopFlushing();
+  await finalFlush();
+
+  isInitialized = false;
+  debug('SDK shutdown complete');
+}
+
+/**
+ * Get current SDK status
+ */
+function getStatus() {
+  const aggregator = getAggregator();
+  const stats = aggregator.getStats();
+
+  return {
+    enabled: isEnabled(),
+    initialized: isInitialized,
+    config: {
+      service: config.service,
+      environment: config.environment,
+      flushInterval: config.flushInterval
+    },
+    stats
+  };
+}
+
+// Auto-initialize on import
+initialize();
+
+// Export for advanced usage
+export {
+  // Core functions
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+
+  // Config
+  getConfig,
+  isEnabled,
+
+  // Middleware for frameworks (optional, for better route extraction)
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+
+  // Utilities (for custom instrumentation)
+  normalizeRoute,
+  extractRoute,
+  RouteRegistry,
+  getAggregator
+};
+
+// Default export
+export default {
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  getAggregator
+};

package/src/instrumentation.js

@@ -0,0 +1,208 @@
+/**
+ * HTTP Request Auto-Instrumentation
+ * Automatically instruments incoming HTTP requests for Express, Fastify, and plain Node.js http.
+ *
+ * Captures:
+ * - Method
+ * - Normalized route
+ * - Status code
+ * - Response time
+ * - Error flag
+ */
+
+import http from 'http';
+import https from 'https';
+import { extractRoute, normalizeRoute } from './normalizer.js';
+import { getAggregator } from './aggregator.js';
+import { debug } from './config.js';
+
+let isInstrumented = false;
+let originalHttpCreateServer = null;
+let originalHttpsCreateServer = null;
+
+/**
+ * Wrap a request handler to capture metrics
+ */
+function wrapRequestHandler(handler) {
+  return function wrappedHandler(req, res) {
+    const startTime = process.hrtime.bigint();
+
+    // Store original end method
+    const originalEnd = res.end;
+
+    // Override res.end to capture timing
+    res.end = function (...args) {
+      const endTime = process.hrtime.bigint();
+      const latencyMs = Number(endTime - startTime) / 1e6; // Convert nanoseconds to milliseconds
+
+      // Extract route (after response, frameworks may have populated route info)
+      const route = extractRoute(req);
+      const method = req.method || 'GET';
+      const statusCode = res.statusCode || 200;
+      const isError = statusCode >= 400;
+
+      // Record the metric
+      const aggregator = getAggregator();
+      aggregator.recordRequest(method, route, latencyMs, isError);
+
+      debug(`Request: ${method} ${route} ${statusCode} ${latencyMs.toFixed(2)}ms`);
+
+      // Call original end
+      return originalEnd.apply(this, args);
+    };
+
+    // Call original handler
+    return handler.call(this, req, res);
+  };
+}
+
+/**
+ * Wrap a server's request listener
+ */
+function wrapServer(server) {
+  const listeners = server.listeners('request');
+
+  // Remove existing listeners
+  server.removeAllListeners('request');
+
+  // Re-add wrapped listeners
+  for (const listener of listeners) {
+    server.on('request', wrapRequestHandler(listener));
+  }
+
+  // Also wrap future listeners
+  const originalOn = server.on.bind(server);
+  server.on = function (event, listener) {
+    if (event === 'request') {
+      return originalOn(event, wrapRequestHandler(listener));
+    }
+    return originalOn(event, listener);
+  };
+
+  return server;
+}
+
+/**
+ * Create instrumented http.createServer
+ */
+function createInstrumentedCreateServer(original, protocol) {
+  return function instrumentedCreateServer(...args) {
+    const server = original.apply(this, args);
+
+    // If a request handler was passed, it's already attached
+    // We need to wrap the server after creation
+    setImmediate(() => {
+      wrapServer(server);
+      debug(`${protocol} server instrumented`);
+    });
+
+    return server;
+  };
+}
+
+/**
+ * Instrument Node.js HTTP module
+ * This is the core instrumentation that works with any framework
+ */
+export function instrumentHttp() {
+  if (isInstrumented) {
+    debug('HTTP already instrumented, skipping');
+    return;
+  }
+
+  // Store originals for cleanup
+  originalHttpCreateServer = http.createServer;
+  originalHttpsCreateServer = https.createServer;
+
+  // Patch http.createServer
+  http.createServer = createInstrumentedCreateServer(originalHttpCreateServer, 'HTTP');
+
+  // Patch https.createServer
+  https.createServer = createInstrumentedCreateServer(originalHttpsCreateServer, 'HTTPS');
+
+  isInstrumented = true;
+  debug('HTTP instrumentation enabled');
+}
+
+/**
+ * Create Express middleware for more accurate route extraction
+ * This is optional but provides better route patterns
+ */
+export function expressMiddleware() {
+  return function sentienguardMiddleware(req, res, next) {
+    const startTime = process.hrtime.bigint();
+
+    // Use res.on('finish') for Express
+    res.on('finish', () => {
+      const endTime = process.hrtime.bigint();
+      const latencyMs = Number(endTime - startTime) / 1e6;
+
+      // Express populates req.route after routing
+      const route = extractRoute(req);
+      const method = req.method || 'GET';
+      const statusCode = res.statusCode || 200;
+      const isError = statusCode >= 400;
+
+      const aggregator = getAggregator();
+      aggregator.recordRequest(method, route, latencyMs, isError);
+
+      debug(`Express: ${method} ${route} ${statusCode} ${latencyMs.toFixed(2)}ms`);
+    });
+
+    next();
+  };
+}
+
+/**
+ * Create Fastify plugin for instrumentation
+ */
+export function fastifyPlugin(fastify, options, done) {
+  fastify.addHook('onRequest', async (request, reply) => {
+    request.sentienguardStart = process.hrtime.bigint();
+  });
+
+  fastify.addHook('onResponse', async (request, reply) => {
+    const endTime = process.hrtime.bigint();
+    const startTime = request.sentienguardStart || endTime;
+    const latencyMs = Number(endTime - startTime) / 1e6;
+
+    const route = extractRoute(request);
+    const method = request.method || 'GET';
+    const statusCode = reply.statusCode || 200;
+    const isError = statusCode >= 400;
+
+    const aggregator = getAggregator();
+    aggregator.recordRequest(method, route, latencyMs, isError);
+
+    debug(`Fastify: ${method} ${route} ${statusCode} ${latencyMs.toFixed(2)}ms`);
+  });
+
+  done();
+}
+
+// Mark as fastify plugin
+fastifyPlugin[Symbol.for('skip-override')] = true;
+
+/**
+ * Remove instrumentation (for testing/cleanup)
+ */
+export function uninstrumentHttp() {
+  if (!isInstrumented) return;
+
+  if (originalHttpCreateServer) {
+    http.createServer = originalHttpCreateServer;
+  }
+  if (originalHttpsCreateServer) {
+    https.createServer = originalHttpsCreateServer;
+  }
+
+  isInstrumented = false;
+  debug('HTTP instrumentation disabled');
+}
+
+export default {
+  instrumentHttp,
+  expressMiddleware,
+  fastifyPlugin,
+  uninstrumentHttp
+};

package/src/normalizer.js

@@ -0,0 +1,147 @@
+/**
+ * Route Normalizer
+ * Normalizes dynamic routes before aggregation to prevent cardinality explosion.
+ *
+ * Examples:
+ *   /api/users/123        → /api/users/:id
+ *   /api/orders/ab23f9    → /api/orders/:id
+ *   /api/users/123/posts/456 → /api/users/:id/posts/:id
+ */
+
+// Patterns for ID detection
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MONGO_ID_PATTERN = /^[0-9a-f]{24}$/i;
+const NUMERIC_PATTERN = /^\d+$/;
+const SHORT_HEX_PATTERN = /^[0-9a-f]{6,}$/i;
+
+// Max route length to prevent abuse
+const MAX_ROUTE_LENGTH = 200;
+
+/**
+ * Check if a path segment looks like a dynamic ID
+ */
+function isIdSegment(segment) {
+  if (!segment) return false;
+
+  // Check for common ID patterns
+  if (NUMERIC_PATTERN.test(segment)) return true;
+  if (UUID_PATTERN.test(segment)) return true;
+  if (MONGO_ID_PATTERN.test(segment)) return true;
+  if (SHORT_HEX_PATTERN.test(segment)) return true;
+
+  return false;
+}
+
+/**
+ * Normalize a route path by replacing dynamic segments with :id
+ *
+ * @param {string} path - The URL path to normalize
+ * @returns {string} Normalized route path
+ */
+export function normalizeRoute(path) {
+  if (!path || typeof path !== 'string') {
+    return '/unknown';
+  }
+
+  // Remove query string and hash
+  let cleanPath = path.split('?')[0].split('#')[0];
+
+  // Ensure path starts with /
+  if (!cleanPath.startsWith('/')) {
+    cleanPath = '/' + cleanPath;
+  }
+
+  // Truncate overly long paths
+  if (cleanPath.length > MAX_ROUTE_LENGTH) {
+    return '/unknown';
+  }
+
+  // Split into segments and normalize
+  const segments = cleanPath.split('/');
+  const normalizedSegments = segments.map(segment => {
+    if (isIdSegment(segment)) {
+      return ':id';
+    }
+    return segment;
+  });
+
+  const normalized = normalizedSegments.join('/');
+
+  // Clean up multiple slashes
+  return normalized.replace(/\/+/g, '/') || '/';
+}
+
+/**
+ * Extract route pattern from Express/Fastify request
+ * Prefers the framework's route pattern if available
+ *
+ * @param {object} req - HTTP request object
+ * @returns {string} Route pattern
+ */
+export function extractRoute(req) {
+  // Express stores the matched route pattern
+  if (req.route && req.route.path) {
+    return req.baseUrl ? req.baseUrl + req.route.path : req.route.path;
+  }
+
+  // Fastify stores route info differently
+  if (req.routerPath) {
+    return req.routerPath;
+  }
+
+  // Fastify alternative
+  if (req.routeOptions && req.routeOptions.url) {
+    return req.routeOptions.url;
+  }
+
+  // Fall back to normalizing the URL
+  return normalizeRoute(req.url || req.originalUrl || '/');
+}
+
+/**
+ * Route registry to track and limit unique routes
+ */
+export class RouteRegistry {
+  constructor(maxRoutes = 100) {
+    this.maxRoutes = maxRoutes;
+    this.routes = new Set();
+  }
+
+  /**
+   * Register a route and check if it should be tracked
+   * Returns the route if under limit, '/unknown' if limit exceeded
+   */
+  register(route) {
+    if (this.routes.has(route)) {
+      return route;
+    }
+
+    if (this.routes.size >= this.maxRoutes) {
+      // Bucket overflow routes as /unknown
+      return '/unknown';
+    }
+
+    this.routes.add(route);
+    return route;
+  }
+
+  /**
+   * Get count of unique routes
+   */
+  get size() {
+    return this.routes.size;
+  }
+
+  /**
+   * Reset the registry
+   */
+  clear() {
+    this.routes.clear();
+  }
+}
+
+export default {
+  normalizeRoute,
+  extractRoute,
+  RouteRegistry
+};