@sentienguard/apm 1.0.19 → 1.0.20

package/src/index.js

@@ -1,242 +1,248 @@
-/**
- * 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_TRACES_ENDPOINT=https://... (optional, raw span ingest; default derived from SENTIENGUARD_ENDPOINT)
- *   SENTIENGUARD_FLUSH_INTERVAL=10     (optional, seconds)
- *   SENTIENGUARD_TRACING=false          (optional, disable OpenTelemetry / W3C propagation; use legacy HTTP patches)
- *   SENTIENGUARD_TRACE_SAMPLE_RATE=0.05 (optional, export sampling for raw traces only; metrics are not sampled)
- *   SENTIENGUARD_TRACE_MAX_QUEUE_SIZE=2048 (optional, drop-on-pressure queue size for raw spans)
- *   SENTIENGUARD_TRACE_MAX_BATCH_SIZE=256  (optional, batch size for raw span export)
- *   SENTIENGUARD_TRACE_LOCAL_HTTP=true  (optional, record outgoing HTTP to localhost as dependencies; use with SENTIENGUARD_PEER_SERVICE_MAP)
- *   SENTIENGUARD_PEER_SERVICE_MAP=3001:service-b,3002:other  (optional, port -> callee name for local peers)
- *
- * No config → SDK disables itself silently.
- */
-
-import config, { isEnabled, debug, getConfig, loadConfig } from './config.js';
-import { instrumentHttp, expressMiddleware, fastifyPlugin } from './instrumentation.js';
-import { instrumentDependencies, instrumentFetch } 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';
-import { startTracing, shutdownTracing, getActiveTraceId, isTracingActive } from './tracing.js';
-import { flushTraceQueue } from './traceTransport.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`);
-
-  // OpenTelemetry: W3C propagation + span → metrics (same ingest as before); legacy patches if this fails or is off
-  const tracingOn = startTracing();
-  // Ensure fetch() dependency edges are captured (works in both tracing and legacy modes)
-  instrumentFetch();
-  if (!tracingOn) {
-    instrumentHttp();
-    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();
-    // Best-effort flush of queued raw spans
-    await flushTraceQueue();
-
-    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');
-
-  await shutdownTracing();
-  // After OTel shutdown, best-effort drain any serialized spans still queued in transport.
-  await flushTraceQueue();
-
-  // 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,
-    tracing: isTracingActive(),
-    config: {
-      service: config.service,
-      environment: config.environment,
-      flushInterval: config.flushInterval
-    },
-    stats
-  };
-}
-
-// Initialize when import runs (retry on nextTick if dotenv loads env vars later)
-initialize();
-
-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,
-
-  // Tracing (W3C context + optional log correlation)
-  getActiveTraceId
-};
-
-// Default export
-export default {
-  initialize,
-  shutdown,
-  getStatus,
-  flush,
-  expressMiddleware,
-  expressErrorMiddleware,
-  fastifyPlugin,
-  fastifyErrorHandler,
-  normalizeRoute,
-  extractRoute,
-  getAggregator,
-  // MongoDB
-  instrumentMongoDB,
-  // OpenAI
-  instrumentOpenAI,
-  // Circuit breaker
-  createBreaker,
-  wrapMongoOperation,
-  getBreakerStats,
-  getActiveTraceId
-};
+/**
+ * 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_TRACES_ENDPOINT=https://... (optional, raw span ingest; default derived from SENTIENGUARD_ENDPOINT)
+ *   SENTIENGUARD_FLUSH_INTERVAL=10     (optional, seconds)
+ *   SENTIENGUARD_TRACING=false          (optional, disable OpenTelemetry / W3C propagation; use legacy HTTP patches)
+ *   SENTIENGUARD_TRACE_SAMPLE_RATE=0.05 (optional, export sampling for raw traces only; metrics are not sampled)
+ *   SENTIENGUARD_TRACE_MAX_QUEUE_SIZE=2048 (optional, drop-on-pressure queue size for raw spans)
+ *   SENTIENGUARD_TRACE_MAX_BATCH_SIZE=256  (optional, batch size for raw span export)
+ *   SENTIENGUARD_TRACE_LOCAL_HTTP=true  (optional, record outgoing HTTP to localhost as dependencies; use with SENTIENGUARD_PEER_SERVICE_MAP)
+ *   SENTIENGUARD_PEER_SERVICE_MAP=3001:service-b,3002:other  (optional, port -> callee name for local peers)
+ *
+ * No config → SDK disables itself silently.
+ */
+
+import config, { isEnabled, debug, getConfig, loadConfig } from './config.js';
+import { instrumentHttp, expressMiddleware, fastifyPlugin } from './instrumentation.js';
+import { instrumentDependencies, instrumentFetch } 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';
+import { startTracing, shutdownTracing, getActiveTraceId, isTracingActive } from './tracing.js';
+import { flushTraceQueue } from './traceTransport.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`);
+
+  // OpenTelemetry: W3C propagation + span → metrics (same ingest as before); legacy patches if this fails or is off
+  const tracingOn = startTracing();
+  // Ensure fetch() dependency edges are captured (works in both tracing and legacy modes)
+  instrumentFetch();
+  if (!tracingOn) {
+    instrumentHttp();
+    instrumentDependencies();
+  }
+
+  // #region agent log
+  try {
+    console.log('[SG-APM-DBG]', JSON.stringify({sessionId:'ecc573',runId:'init',hypothesisId:'A,B',location:'index.js:initialize',message:'SDK init runtime + instrumentation flow',data:{isBun:typeof globalThis.Bun!=='undefined',bunVersion:globalThis.Bun?.version||null,nodeVersion:process.versions?.node||null,tracingOn,legacyHttpInstalled:!tracingOn,service:config.service,endpoint:config.endpoint,argv0:process.argv0,execPath:process.execPath},timestamp:Date.now()}));
+  } catch {}
+  // #endregion
+
+  // 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();
+    // Best-effort flush of queued raw spans
+    await flushTraceQueue();
+
+    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');
+
+  await shutdownTracing();
+  // After OTel shutdown, best-effort drain any serialized spans still queued in transport.
+  await flushTraceQueue();
+
+  // 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,
+    tracing: isTracingActive(),
+    config: {
+      service: config.service,
+      environment: config.environment,
+      flushInterval: config.flushInterval
+    },
+    stats
+  };
+}
+
+// Initialize when import runs (retry on nextTick if dotenv loads env vars later)
+initialize();
+
+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,
+
+  // Tracing (W3C context + optional log correlation)
+  getActiveTraceId
+};
+
+// Default export
+export default {
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  getAggregator,
+  // MongoDB
+  instrumentMongoDB,
+  // OpenAI
+  instrumentOpenAI,
+  // Circuit breaker
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats,
+  getActiveTraceId
+};

package/src/mongodb.js

@@ -106,6 +106,12 @@ function handleCommandStarted(event) {
 
   const commandName = event.commandName;
 
+  // #region agent log
+  try {
+    console.log('[SG-APM-DBG]', JSON.stringify({sessionId:'ecc573',runId:'mongo-cmd',hypothesisId:'C',location:'mongodb.js:handleCommandStarted',message:'commandStarted event fired',data:{commandName,databaseName:event.databaseName,ignored:IGNORED_COMMANDS.has(commandName),requestId:String(event.requestId||'')},timestamp:Date.now()}));
+  } catch {}
+  // #endregion
+
   // Skip ignored commands
   if (IGNORED_COMMANDS.has(commandName)) {
     return;
@@ -263,26 +269,42 @@ function collectPoolStats() {
  * also populate require.cache via the CJS interop layer.
  */
 function tryDetectMongoose() {
+  let cacheKeyCount = 0;
+  let mongooseKeyMatched = null;
+  let cacheError = null;
   try {
     // Strategy 1: Scan require.cache for mongoose
     const cache = require.cache || {};
     const cacheKeys = Object.keys(cache);
+    cacheKeyCount = cacheKeys.length;
     const mongooseKey = cacheKeys.find(
       k => /[\\/]mongoose[\\/](?:lib[\\/])?index\.js$/.test(k) &&
            !k.includes('node_modules/mongoose/node_modules')
     );
+    mongooseKeyMatched = mongooseKey || null;
     if (mongooseKey && cache[mongooseKey]?.exports) {
       const mod = cache[mongooseKey].exports;
       // Verify it's actually mongoose (has connection property)
       if (mod.connection) {
         debug('Detected mongoose via require.cache');
+        // #region agent log
+        try {
+          console.log('[SG-APM-DBG]', JSON.stringify({sessionId:'ecc573',runId:'mongo-detect',hypothesisId:'D',location:'mongodb.js:tryDetectMongoose',message:'mongoose detected via require.cache',data:{isBun:typeof globalThis.Bun!=='undefined',cacheKeyCount,matchedKey:mongooseKey,readyState:mod.connection?.readyState??null},timestamp:Date.now()}));
+        } catch {}
+        // #endregion
         return mod;
       }
     }
   } catch (e) {
-    // require.cache not available (unlikely in Node.js)
+    cacheError = e?.message || String(e);
   }
 
+  // #region agent log
+  try {
+    console.log('[SG-APM-DBG]', JSON.stringify({sessionId:'ecc573',runId:'mongo-detect',hypothesisId:'D',location:'mongodb.js:tryDetectMongoose',message:'mongoose NOT detected (require.cache scan)',data:{isBun:typeof globalThis.Bun!=='undefined',hasRequire:typeof require!=='undefined',hasRequireCache:typeof require!=='undefined' && !!require.cache,cacheKeyCount,mongooseKeyMatched,cacheError,globalThisMongoose:!!globalThis.mongoose},timestamp:Date.now()}));
+  } catch {}
+  // #endregion
+
   // Strategy 2: Fallback — check globalThis (in case user set it manually)
   try {
     if (globalThis.mongoose?.connection) {
@@ -306,6 +328,14 @@ function ensureMonitorCommands(client) {
       client.options?.monitorCommands ||
       client.s?.options?.monitorCommands;
 
+    // #region agent log
+    try {
+      const optsRoot = client.options ? Object.keys(client.options).slice(0, 30) : null;
+      const optsS = client.s?.options ? Object.keys(client.s.options).slice(0, 30) : null;
+      console.log('[SG-APM-DBG]', JSON.stringify({sessionId:'ecc573',runId:'mongo-init',hypothesisId:'C',location:'mongodb.js:ensureMonitorCommands',message:'monitorCommands inspection on live MongoClient',data:{alreadyEnabled:!!alreadyEnabled,hasClientOptions:!!client.options,hasClientSOptions:!!client.s?.options,clientOptionsFrozen:client.options ? Object.isFrozen(client.options) : null,clientSOptionsFrozen:client.s?.options ? Object.isFrozen(client.s.options) : null,optsRootKeys:optsRoot,optsSKeys:optsS},timestamp:Date.now()}));
+    } catch {}
+    // #endregion
+
     if (alreadyEnabled) {
       debug('monitorCommands already enabled');
       return true;