@sentienguard/apm 1.0.5 → 1.0.7

package/src/index.js

@@ -1,209 +1,225 @@
-/**
- * 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';
-import { instrumentMongoDB, autoInstrumentMongoDB, stopMongoDBInstrumentation } from './mongodb.js';
-import { instrumentOpenAI, stopOpenAIInstrumentation } from './openai.js';
-import { createBreaker, wrapMongoOperation, getBreakerStats, shutdownBreakers } from './circuitBreaker.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();
-
-  // Auto-instrument MongoDB if available
-  autoInstrumentMongoDB();
-
-  // 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');
-
-  // Stop MongoDB instrumentation
-  stopMongoDBInstrumentation();
-
-  // Stop OpenAI instrumentation
-  stopOpenAIInstrumentation();
-
-  // Shutdown circuit breakers
-  shutdownBreakers();
-
-  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,
-
-  // MongoDB instrumentation
-  instrumentMongoDB,
-
-  // OpenAI instrumentation
-  instrumentOpenAI,
-
-  // Circuit breaker
-  createBreaker,
-  wrapMongoOperation,
-  getBreakerStats
-};
-
-// Default export
-export default {
-  initialize,
-  shutdown,
-  getStatus,
-  flush,
-  expressMiddleware,
-  expressErrorMiddleware,
-  fastifyPlugin,
-  fastifyErrorHandler,
-  normalizeRoute,
-  extractRoute,
-  getAggregator,
-  // MongoDB
-  instrumentMongoDB,
-  // OpenAI
-  instrumentOpenAI,
-  // Circuit breaker
-  createBreaker,
-  wrapMongoOperation,
-  getBreakerStats
-};
+/**
+ * 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, getConfig, loadConfig } 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';
+import { instrumentMongoDB, autoInstrumentMongoDB, stopMongoDBInstrumentation } from './mongodb.js';
+import { instrumentOpenAI, stopOpenAIInstrumentation } from './openai.js';
+import { createBreaker, wrapMongoOperation, getBreakerStats, shutdownBreakers } from './circuitBreaker.js';
+
+let isInitialized = false;
+
+/**
+ * Initialize the SDK
+ * Called automatically on import
+ */
+function initialize() {
+  if (isInitialized) {
+    debug('SDK already initialized');
+    return;
+  }
+
+  // Load config from env vars (lazy — allows dotenv to load first)
+  loadConfig();
+
+  // 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();
+
+  // Auto-instrument MongoDB if available
+  autoInstrumentMongoDB();
+
+  // 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');
+
+  // Stop MongoDB instrumentation
+  stopMongoDBInstrumentation();
+
+  // Stop OpenAI instrumentation
+  stopOpenAIInstrumentation();
+
+  // Shutdown circuit breakers
+  shutdownBreakers();
+
+  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
+  };
+}
+
+// Phase 1: Immediately patch http/https (config-independent, must happen before servers are created)
+instrumentHttp();
+instrumentDependencies();
+
+// Phase 2: Try full initialization (works if env vars are already set at system/process level)
+initialize();
+
+// Phase 3: If init failed (env vars not loaded yet, e.g. dotenv.config() hasn't run),
+// retry after the importing module's synchronous code completes
+if (!isInitialized) {
+  process.nextTick(() => {
+    loadConfig({ force: true });
+    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,
+
+  // MongoDB instrumentation
+  instrumentMongoDB,
+
+  // OpenAI instrumentation
+  instrumentOpenAI,
+
+  // Circuit breaker
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats
+};
+
+// Default export
+export default {
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  getAggregator,
+  // MongoDB
+  instrumentMongoDB,
+  // OpenAI
+  instrumentOpenAI,
+  // Circuit breaker
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats
+};