@sentienguard/apm 1.0.8 → 1.0.9

package/src/index.js

@@ -1,225 +1,233 @@
-/**
- * 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
-};
+/**
+ * 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)
+ *   SENTIENGUARD_TRACING=false          (optional, disable OpenTelemetry / W3C propagation; use legacy HTTP patches)
+ *   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';
+
+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();
+
+    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();
+
+  // 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/instrumentation.js

@@ -15,6 +15,7 @@ import https from 'https';
 import { extractRoute } from './normalizer.js';
 import { getAggregator } from './aggregator.js';
 import { debug } from './config.js';
+import { isTracingActive } from './tracing.js';
 
 let isInstrumented = false;
 let originalHttpCreateServer = null;
@@ -130,6 +131,10 @@ export function instrumentHttp() {
  */
 export function expressMiddleware() {
   return function sentienguardMiddleware(req, res, next) {
+    if (isTracingActive()) {
+      return next();
+    }
+
     const startTime = process.hrtime.bigint();
 
     // Use res.on('finish') for Express
@@ -157,6 +162,11 @@ export function expressMiddleware() {
  * Create Fastify plugin for instrumentation
  */
 export function fastifyPlugin(fastify, options, done) {
+  if (isTracingActive()) {
+    done();
+    return;
+  }
+
   fastify.addHook('onRequest', async (request, reply) => {
     request.sentienguardStart = process.hrtime.bigint();
   });