@sentienguard/apm 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# @sentienguard/apm
+
+Minimal, production-safe APM SDK for Node.js applications. Zero-config setup with automatic instrumentation.
+
+## Installation
+
+```bash
+npm install @sentienguard/apm
+```
+
+## Quick Start
+
+```js
+// Add this as the FIRST import in your app
+import '@sentienguard/apm';
+
+// Your app code
+import express from 'express';
+const app = express();
+// ...
+```
+
+Set environment variables:
+
+```bash
+SENTIENGUARD_APM_KEY=your-app-key
+SENTIENGUARD_SERVICE=my-api
+```
+
+That's it. The SDK automatically instruments your application and sends metrics to SentienGuard.
+
+## Configuration
+
+All configuration is via environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SENTIENGUARD_APM_KEY` | Yes | - | Your application's APM key |
+| `SENTIENGUARD_SERVICE` | Yes | - | Service name (e.g., `orders-api`) |
+| `SENTIENGUARD_ENV` | No | `production` | Environment (`production`, `staging`, `development`) |
+| `SENTIENGUARD_ENDPOINT` | No | `https://sentienguard-dev.the-algo.com/api/v1` | SentienGuard backend URL |
+| `SENTIENGUARD_FLUSH_INTERVAL` | No | `10` | Metrics flush interval in seconds |
+
+> **Note:** If `SENTIENGUARD_APM_KEY` or `SENTIENGUARD_SERVICE` is missing, the SDK disables itself silently without affecting your application.
+
+## What Gets Tracked
+
+- **HTTP Requests** - Incoming requests with method, route, status, and latency
+- **Dependencies** - Outgoing HTTP/HTTPS calls to external services
+- **Errors** - Uncaught exceptions and unhandled rejections
+
+## Framework Integration
+
+### Express
+
+For better route extraction, add the middleware:
+
+```js
+import '@sentienguard/apm';
+import { expressMiddleware, expressErrorMiddleware } from '@sentienguard/apm';
+import express from 'express';
+
+const app = express();
+
+// Add early in middleware chain
+app.use(expressMiddleware());
+
+// Your routes
+app.get('/users/:id', (req, res) => { ... });
+
+// Add error middleware last
+app.use(expressErrorMiddleware());
+```
+
+### Fastify
+
+```js
+import '@sentienguard/apm';
+import { fastifyPlugin, fastifyErrorHandler } from '@sentienguard/apm';
+import Fastify from 'fastify';
+
+const app = Fastify();
+
+// Register plugin
+app.register(fastifyPlugin);
+
+// Add error handler
+app.setErrorHandler(fastifyErrorHandler);
+```
+
+## API Reference
+
+### Functions
+
+```js
+import {
+  shutdown,      // Graceful shutdown (flushes pending metrics)
+  getStatus,     // Get SDK status and stats
+  flush,         // Force flush metrics now
+  isEnabled      // Check if SDK is enabled
+} from '@sentienguard/apm';
+```
+
+### Graceful Shutdown
+
+The SDK automatically handles `SIGTERM` and `SIGINT` signals. For manual shutdown:
+
+```js
+import { shutdown } from '@sentienguard/apm';
+
+process.on('exit', async () => {
+  await shutdown();
+});
+```
+
+### Check Status
+
+```js
+import { getStatus } from '@sentienguard/apm';
+
+console.log(getStatus());
+// {
+//   enabled: true,
+//   initialized: true,
+//   config: { service: 'my-api', environment: 'production', flushInterval: 10 },
+//   stats: { requests: 150, dependencies: 45, errors: 2 }
+// }
+```
+
+## Requirements
+
+- Node.js >= 16.0.0
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sentienguard/apm",
+  "version": "1.0.0",
+  "description": "SentienGuard APM SDK - Minimal, production-safe application performance monitoring",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:load": "node tests/load.test.js"
+  },
+  "keywords": [
+    "apm",
+    "monitoring",
+    "performance",
+    "metrics",
+    "sentienguard"
+  ],
+  "author": "SentienGuard",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "files": [
+    "src/**/*"
+  ]
+}

package/src/aggregator.js

@@ -0,0 +1,219 @@
+/**
+ * Metrics Aggregator
+ * Aggregates metrics in memory per interval.
+ * Never streams raw events - only sends aggregated data.
+ *
+ * Aggregation key: (service, method, route) for requests
+ * Aggregation key: (service, name, type) for dependencies
+ */
+
+import { RouteRegistry } from './normalizer.js';
+import config from './config.js';
+
+/**
+ * Create an aggregation key for request metrics
+ */
+function createRequestKey(method, route) {
+  return `${method}:${route}`;
+}
+
+/**
+ * Create an aggregation key for dependency metrics
+ */
+function createDependencyKey(name, type) {
+  return `${name}:${type}`;
+}
+
+/**
+ * Metrics Aggregator class
+ * Maintains in-memory aggregated metrics that are flushed periodically
+ */
+export class MetricsAggregator {
+  constructor() {
+    this.routeRegistry = new RouteRegistry(config.maxRoutes);
+    this.reset();
+  }
+
+  /**
+   * Reset all aggregated metrics (called after flush)
+   */
+  reset() {
+    // Request metrics: Map<key, {count, errorCount, latency: {sum, min, max}}>
+    this.requests = new Map();
+
+    // Dependency metrics: Map<key, {name, type, count, errorCount, latency: {sum, min, max}}>
+    this.dependencies = new Map();
+
+    // Error counter for unhandled exceptions
+    this.unhandledErrors = 0;
+  }
+
+  /**
+   * Record an incoming HTTP request
+   *
+   * @param {string} method - HTTP method (GET, POST, etc.)
+   * @param {string} route - Normalized route path
+   * @param {number} latency - Response time in milliseconds
+   * @param {boolean} isError - Whether the request resulted in an error (4xx/5xx)
+   */
+  recordRequest(method, route, latency, isError = false) {
+    // Register route with limit enforcement
+    const registeredRoute = this.routeRegistry.register(route);
+    const key = createRequestKey(method.toUpperCase(), registeredRoute);
+
+    let metric = this.requests.get(key);
+    if (!metric) {
+      metric = {
+        method: method.toUpperCase(),
+        route: registeredRoute,
+        count: 0,
+        errorCount: 0,
+        latency: {
+          sum: 0,
+          min: Infinity,
+          max: 0
+        }
+      };
+      this.requests.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 an outgoing dependency call
+   *
+   * @param {string} name - Dependency name (e.g., "OpenAI API", "MongoDB")
+   * @param {string} type - Dependency type (http, db, cache)
+   * @param {number} latency - Response time in milliseconds
+   * @param {boolean} isError - Whether the call resulted in an error
+   */
+  recordDependency(name, type, latency, isError = false) {
+    const key = createDependencyKey(name, type);
+
+    let metric = this.dependencies.get(key);
+    if (!metric) {
+      metric = {
+        name,
+        type,
+        count: 0,
+        errorCount: 0,
+        latency: {
+          sum: 0,
+          min: Infinity,
+          max: 0
+        }
+      };
+      this.dependencies.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 an unhandled error
+   */
+  recordError() {
+    this.unhandledErrors++;
+  }
+
+  /**
+   * Check if there's data to flush
+   */
+  hasData() {
+    return this.requests.size > 0 || this.dependencies.size > 0;
+  }
+
+  /**
+   * Get aggregated data for flushing to backend
+   * Returns the payload in the expected format and resets counters
+   */
+  flush() {
+    const payload = {
+      interval: `${config.flushInterval}s`,
+      service: config.service,
+      environment: config.environment,
+      requests: [],
+      dependencies: []
+    };
+
+    // Convert request metrics to array
+    for (const metric of this.requests.values()) {
+      payload.requests.push({
+        method: metric.method,
+        route: metric.route,
+        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)
+        }
+      });
+    }
+
+    // Convert dependency metrics to array
+    for (const metric of this.dependencies.values()) {
+      payload.dependencies.push({
+        name: metric.name,
+        type: metric.type,
+        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)
+        }
+      });
+    }
+
+    // Reset for next interval
+    this.reset();
+
+    return payload;
+  }
+
+  /**
+   * Get current metrics count (for monitoring/testing)
+   */
+  getStats() {
+    return {
+      requestMetrics: this.requests.size,
+      dependencyMetrics: this.dependencies.size,
+      uniqueRoutes: this.routeRegistry.size,
+      unhandledErrors: this.unhandledErrors
+    };
+  }
+}
+
+// Singleton instance
+let instance = null;
+
+/**
+ * Get the singleton aggregator instance
+ */
+export function getAggregator() {
+  if (!instance) {
+    instance = new MetricsAggregator();
+  }
+  return instance;
+}
+
+export default {
+  MetricsAggregator,
+  getAggregator
+};

package/src/config.js

@@ -0,0 +1,67 @@
+/**
+ * SDK Configuration
+ * Environment-driven configuration with sensible defaults.
+ * No config → SDK disables itself silently.
+ */
+
+const config = {
+  // API key for authentication (required)
+  apiKey: process.env.SENTIENGUARD_APM_KEY || '',
+
+  // Service name (required for data to be meaningful)
+  service: process.env.SENTIENGUARD_SERVICE || '',
+
+  // Environment (production, staging, development)
+  environment: process.env.SENTIENGUARD_ENV || 'production',
+
+  // Backend endpoint for data ingestion
+  endpoint: process.env.SENTIENGUARD_ENDPOINT || 'https://api.sentienguard.io/apm/ingest',
+
+  // Flush interval in seconds (default: 10s)
+  flushInterval: parseInt(process.env.SENTIENGUARD_FLUSH_INTERVAL, 10) || 10,
+
+  // Max unique routes to track per service (prevents memory bloat)
+  maxRoutes: parseInt(process.env.SENTIENGUARD_MAX_ROUTES, 10) || 100,
+
+  // Max payload size in bytes (prevent oversized payloads)
+  maxPayloadSize: parseInt(process.env.SENTIENGUARD_MAX_PAYLOAD_SIZE, 10) || 1024 * 1024, // 1MB
+
+  // Enable/disable SDK (auto-disabled if no API key)
+  enabled: process.env.SENTIENGUARD_ENABLED !== 'false',
+
+  // Debug mode (logs SDK activity)
+  debug: process.env.SENTIENGUARD_DEBUG === 'true'
+};
+
+/**
+ * Check if SDK is properly configured and should be active
+ */
+export function isEnabled() {
+  // SDK disables itself silently if no API key or service name
+  return config.enabled && !!config.apiKey && !!config.service;
+}
+
+/**
+ * Get validated configuration
+ */
+export function getConfig() {
+  return { ...config };
+}
+
+/**
+ * Log debug message if debug mode is enabled
+ */
+export function debug(...args) {
+  if (config.debug) {
+    console.log('[SentienGuard APM]', ...args);
+  }
+}
+
+/**
+ * Log warning (always shown)
+ */
+export function warn(...args) {
+  console.warn('[SentienGuard APM]', ...args);
+}
+
+export default config;

package/src/dependencies.js

@@ -0,0 +1,236 @@
+/**
+ * Dependency Tracking
+ * Automatically times outgoing HTTP calls (fetch, axios, node http/https).
+ *
+ * For each dependency:
+ * - name (e.g., "OpenAI API", "api.example.com")
+ * - type (http, db, cache)
+ * - response time
+ * - error flag
+ */
+
+import http from 'http';
+import https from 'https';
+import { getAggregator } from './aggregator.js';
+import { debug, getConfig } from './config.js';
+
+let isInstrumented = false;
+let originalHttpRequest = null;
+let originalHttpsRequest = null;
+
+// Known service patterns for better naming
+const KNOWN_SERVICES = [
+  { pattern: /openai\.com/i, name: 'OpenAI API' },
+  { pattern: /anthropic\.com/i, name: 'Anthropic API' },
+  { pattern: /api\.stripe\.com/i, name: 'Stripe API' },
+  { pattern: /api\.sendgrid\.com/i, name: 'SendGrid' },
+  { pattern: /api\.twilio\.com/i, name: 'Twilio API' },
+  { pattern: /s3\.amazonaws\.com/i, name: 'AWS S3' },
+  { pattern: /dynamodb\..+\.amazonaws\.com/i, name: 'DynamoDB' },
+  { pattern: /sqs\..+\.amazonaws\.com/i, name: 'AWS SQS' },
+  { pattern: /sns\..+\.amazonaws\.com/i, name: 'AWS SNS' },
+  { pattern: /mongodb\.net/i, name: 'MongoDB Atlas' },
+  { pattern: /redis/i, name: 'Redis' },
+  { pattern: /postgresql|postgres/i, name: 'PostgreSQL' },
+  { pattern: /mysql/i, name: 'MySQL' }
+];
+
+/**
+ * Extract a friendly name from hostname
+ */
+function getServiceName(hostname) {
+  if (!hostname) return 'unknown';
+
+  // Check known services
+  for (const service of KNOWN_SERVICES) {
+    if (service.pattern.test(hostname)) {
+      return service.name;
+    }
+  }
+
+  // Default to hostname
+  return hostname;
+}
+
+/**
+ * Determine dependency type from hostname/path
+ */
+function getDependencyType(hostname, path) {
+  const lowerHost = (hostname || '').toLowerCase();
+  const lowerPath = (path || '').toLowerCase();
+
+  // Database indicators
+  if (/mongodb|postgres|mysql|dynamodb|redis|memcache/i.test(lowerHost)) {
+    return 'db';
+  }
+
+  // Cache indicators
+  if (/redis|memcache|elasticache/i.test(lowerHost)) {
+    return 'cache';
+  }
+
+  // Storage indicators
+  if (/s3\.amazonaws|storage\.googleapis|blob\.core\.windows/i.test(lowerHost)) {
+    return 'storage';
+  }
+
+  // Default to HTTP
+  return 'http';
+}
+
+/**
+ * Check if this request should be excluded from tracking
+ */
+function shouldExclude(hostname) {
+  const config = getConfig();
+
+  // Don't track our own APM endpoint
+  if (config.endpoint) {
+    try {
+      const endpointUrl = new URL(config.endpoint);
+      if (hostname === endpointUrl.hostname) {
+        return true;
+      }
+    } catch {
+      // Invalid endpoint URL, continue
+    }
+  }
+
+  // Exclude localhost by default (internal services)
+  if (hostname === 'localhost' || hostname === '127.0.0.1') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Wrap http/https request to track dependencies
+ */
+function wrapRequest(original, protocol) {
+  return function instrumentedRequest(options, callback) {
+    // Parse options to get hostname
+    let hostname = '';
+    let path = '/';
+
+    if (typeof options === 'string') {
+      try {
+        const url = new URL(options);
+        hostname = url.hostname;
+        path = url.pathname;
+      } catch {
+        // Invalid URL
+      }
+    } else if (options) {
+      hostname = options.hostname || options.host || '';
+      path = options.path || '/';
+      // Remove port from host if present
+      hostname = hostname.split(':')[0];
+    }
+
+    // Check exclusions
+    if (shouldExclude(hostname)) {
+      return original.apply(this, arguments);
+    }
+
+    const startTime = process.hrtime.bigint();
+    const serviceName = getServiceName(hostname);
+    const depType = getDependencyType(hostname, path);
+
+    // Call original
+    const req = original.apply(this, arguments);
+
+    // Track response
+    req.on('response', (res) => {
+      const endTime = process.hrtime.bigint();
+      const latencyMs = Number(endTime - startTime) / 1e6;
+      const isError = res.statusCode >= 400;
+
+      const aggregator = getAggregator();
+      aggregator.recordDependency(serviceName, depType, latencyMs, isError);
+
+      debug(`Dependency: ${serviceName} (${depType}) ${res.statusCode} ${latencyMs.toFixed(2)}ms`);
+    });
+
+    // Track errors
+    req.on('error', () => {
+      const endTime = process.hrtime.bigint();
+      const latencyMs = Number(endTime - startTime) / 1e6;
+
+      const aggregator = getAggregator();
+      aggregator.recordDependency(serviceName, depType, latencyMs, true);
+
+      debug(`Dependency error: ${serviceName} (${depType}) ${latencyMs.toFixed(2)}ms`);
+    });
+
+    return req;
+  };
+}
+
+/**
+ * Instrument outgoing HTTP requests
+ */
+export function instrumentDependencies() {
+  if (isInstrumented) {
+    debug('Dependencies already instrumented, skipping');
+    return;
+  }
+
+  // Store originals
+  originalHttpRequest = http.request;
+  originalHttpsRequest = https.request;
+
+  // Patch http.request
+  http.request = wrapRequest(originalHttpRequest, 'http');
+  http.get = function (options, callback) {
+    const req = http.request(options, callback);
+    req.end();
+    return req;
+  };
+
+  // Patch https.request
+  https.request = wrapRequest(originalHttpsRequest, 'https');
+  https.get = function (options, callback) {
+    const req = https.request(options, callback);
+    req.end();
+    return req;
+  };
+
+  isInstrumented = true;
+  debug('Dependency instrumentation enabled');
+}
+
+/**
+ * Remove instrumentation (for testing/cleanup)
+ */
+export function uninstrumentDependencies() {
+  if (!isInstrumented) return;
+
+  if (originalHttpRequest) {
+    http.request = originalHttpRequest;
+    http.get = function (options, callback) {
+      const req = http.request(options, callback);
+      req.end();
+      return req;
+    };
+  }
+
+  if (originalHttpsRequest) {
+    https.request = originalHttpsRequest;
+    https.get = function (options, callback) {
+      const req = https.request(options, callback);
+      req.end();
+      return req;
+    };
+  }
+
+  isInstrumented = false;
+  debug('Dependency instrumentation disabled');
+}
+
+export default {
+  instrumentDependencies,
+  uninstrumentDependencies,
+  getServiceName,
+  getDependencyType
+};