@sentienguard/apm 1.0.19 → 1.0.21

package/src/tracing.js

@@ -1,230 +1,230 @@
-/**
- * OpenTelemetry bootstrap: W3C trace context propagation + HTTP/Express spans.
- * Spans are exported through SentienGuardSpanExporter into the existing metrics aggregator.
- */
-
-import { trace } from '@opentelemetry/api';
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { Resource } from '@opentelemetry/resources';
-import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT } from '@opentelemetry/semantic-conventions';
-import { W3CTraceContextPropagator } from '@opentelemetry/core';
-import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
-import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
-import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb';
-import { MongooseInstrumentation } from '@opentelemetry/instrumentation-mongoose';
-import { AlwaysOnSampler, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { getConfig, debug } from './config.js';
-import { SentienGuardSpanExporter } from './spanExporter.js';
-import { SentienGuardTraceSpanExporter } from './traceSpanExporter.js';
-
-let sdk = null;
-let tracingActive = false;
-
-function setAttr(span, key, value) {
-  try {
-    if (!span || typeof span.setAttribute !== 'function') return;
-    if (value == null) return;
-    const v = typeof value === 'string' ? value : String(value);
-    if (!v) return;
-    span.setAttribute(key, v);
-  } catch {
-    // ignore
-  }
-}
-
-function setAttrNumber(span, key, value) {
-  try {
-    if (!span || typeof span.setAttribute !== 'function') return;
-    const n = Number(value);
-    if (!Number.isFinite(n)) return;
-    span.setAttribute(key, n);
-  } catch {
-    // ignore
-  }
-}
-
-function safeUrlFromOutgoingRequest(requestOptions) {
-  try {
-    if (!requestOptions) return '';
-    if (typeof requestOptions === 'string') return requestOptions;
-    if (requestOptions instanceof URL) return requestOptions.toString();
-    const protocol = requestOptions.protocol || 'http:';
-    const hostRaw = requestOptions.hostname || requestOptions.host || '';
-    const host = String(hostRaw).trim();
-    const path = requestOptions.path || requestOptions.pathname || '/';
-    if (!host) return '';
-    return `${protocol}//${host}${path}`;
-  } catch {
-    return '';
-  }
-}
-
-function safeHostFromIncoming(req) {
-  try {
-    const h = req?.headers?.host;
-    return h ? String(h).split(',')[0].trim() : '';
-  } catch {
-    return '';
-  }
-}
-
-function shouldIgnoreOutgoingHost(hostname) {
-  if (!hostname) return false;
-  const host = hostname.split(':')[0];
-  const cfg = getConfig();
-  if (cfg.tracing?.traceLocalHttp && (host === 'localhost' || host === '127.0.0.1' || host === '::1')) {
-    return false;
-  }
-  if (host === 'localhost' || host === '127.0.0.1' || host === '::1') return true;
-  try {
-    if (cfg.endpoint) {
-      const h = new URL(cfg.endpoint).hostname;
-      if (host === h) return true;
-    }
-  } catch {
-    // ignore
-  }
-  return false;
-}
-
-/**
- * Start OpenTelemetry when enabled in config. Returns true if tracing owns HTTP instrumentation.
- */
-export function startTracing() {
-  const cfg = getConfig();
-  if (!cfg.tracing?.enabled) {
-    debug('OpenTelemetry tracing disabled (SENTIENGUARD_TRACING=false)');
-    return false;
-  }
-
-  if (tracingActive) {
-    return true;
-  }
-
-  try {
-    const resource = new Resource({
-      [SEMRESATTRS_SERVICE_NAME]: cfg.service,
-      [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: cfg.environment
-    });
-
-    const metricsExporter = new SentienGuardSpanExporter();
-    const traceExporter = new SentienGuardTraceSpanExporter();
-
-    const httpInstrumentation = new HttpInstrumentation({
-      ignoreOutgoingRequestHook: (requestOptions) => {
-        const host = requestOptions.hostname || (requestOptions.host ? String(requestOptions.host).split(':')[0] : '');
-        return shouldIgnoreOutgoingHost(host);
-      },
-      /**
-       * Ensure we always attach basic HTTP attributes.
-       * This protects us from cases where the underlying instrumentation
-       * doesn't populate attributes (common in some Node/Jest/undici combos).
-       */
-      requestHook: (span, request) => {
-        // Incoming request (SERVER)
-        if (request && typeof request === 'object' && 'headers' in request && 'method' in request) {
-          setAttr(span, 'http.method', request.method);
-          setAttr(span, 'http.target', request.url);
-          setAttr(span, 'http.host', safeHostFromIncoming(request));
-          return;
-        }
-
-        // Outgoing request (CLIENT) — requestOptions
-        setAttr(span, 'http.method', request?.method);
-        const url = safeUrlFromOutgoingRequest(request);
-        if (url) setAttr(span, 'http.url', url);
-        const host = request?.hostname || (request?.host ? String(request.host).split(':')[0] : '');
-        if (host) setAttr(span, 'net.peer.name', host);
-        if (request?.port) setAttrNumber(span, 'net.peer.port', request.port);
-      },
-      responseHook: (span, response) => {
-        // Incoming response (SERVER): ServerResponse
-        if (response && typeof response === 'object' && 'statusCode' in response) {
-          setAttrNumber(span, 'http.status_code', response.statusCode);
-        }
-      }
-      ,
-      /**
-       * More reliable cross-version hook that runs with both request+response context.
-       * Used as a safety net to guarantee basic attributes exist on spans.
-       */
-      applyCustomAttributesOnSpan: (span, request, response) => {
-        // Incoming request (SERVER)
-        if (request && typeof request === 'object' && 'headers' in request && 'method' in request) {
-          setAttr(span, 'http.method', request.method);
-          setAttr(span, 'http.target', request.url);
-          setAttr(span, 'http.host', safeHostFromIncoming(request));
-        } else {
-          // Outgoing request (CLIENT)
-          setAttr(span, 'http.method', request?.method);
-          const url = safeUrlFromOutgoingRequest(request);
-          if (url) setAttr(span, 'http.url', url);
-          const host = request?.hostname || (request?.host ? String(request.host).split(':')[0] : '');
-          if (host) setAttr(span, 'net.peer.name', host);
-          if (request?.port) setAttrNumber(span, 'net.peer.port', request.port);
-        }
-
-        if (response && typeof response === 'object' && 'statusCode' in response) {
-          setAttrNumber(span, 'http.status_code', response.statusCode);
-        }
-      }
-    });
-
-    const expressInstrumentation = new ExpressInstrumentation();
-    const mongoInstrumentation = new MongoDBInstrumentation();
-    const mongooseInstrumentation = new MongooseInstrumentation();
-
-    sdk = new NodeSDK({
-      resource,
-      // Important: keep span recording ON so APM metrics derived from spans are not undersampled.
-      // Raw trace export sampling is handled inside SentienGuardTraceSpanExporter instead.
-      sampler: new AlwaysOnSampler(),
-      textMapPropagator: new W3CTraceContextPropagator(),
-      // Include MongoDB/Mongoose instrumentations for "zero-code" DB spans.
-      // These are safe even when the app doesn't use MongoDB; they patch when modules are loaded.
-      instrumentations: [httpInstrumentation, expressInstrumentation, mongoInstrumentation, mongooseInstrumentation],
-      spanProcessors: [
-        new BatchSpanProcessor(metricsExporter),
-        new BatchSpanProcessor(traceExporter)
-      ],
-      autoDetectResources: false
-    });
-
-    sdk.start();
-    tracingActive = true;
-    debug('OpenTelemetry tracing started (W3C Trace Context + HTTP/Express)');
-    return true;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    debug(`OpenTelemetry failed to start, falling back to legacy instrumentation: ${msg}`);
-    sdk = null;
-    tracingActive = false;
-    return false;
-  }
-}
-
-export function isTracingActive() {
-  return tracingActive;
-}
-
-/** Hex trace id for the active span (log correlation); undefined if none. */
-export function getActiveTraceId() {
-  const s = trace.getActiveSpan();
-  if (!s) return undefined;
-  const c = s.spanContext();
-  return c.traceId && c.traceFlags !== undefined ? c.traceId : undefined;
-}
-
-export async function shutdownTracing() {
-  if (!sdk) return;
-  try {
-    await sdk.shutdown();
-    debug('OpenTelemetry tracing shut down');
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    debug(`OpenTelemetry shutdown error: ${msg}`);
-  } finally {
-    sdk = null;
-    tracingActive = false;
-  }
-}
+/**
+ * OpenTelemetry bootstrap: W3C trace context propagation + HTTP/Express spans.
+ * Spans are exported through SentienGuardSpanExporter into the existing metrics aggregator.
+ */
+
+import { trace } from '@opentelemetry/api';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { Resource } from '@opentelemetry/resources';
+import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT } from '@opentelemetry/semantic-conventions';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
+import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb';
+import { MongooseInstrumentation } from '@opentelemetry/instrumentation-mongoose';
+import { AlwaysOnSampler, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { getConfig, debug } from './config.js';
+import { SentienGuardSpanExporter } from './spanExporter.js';
+import { SentienGuardTraceSpanExporter } from './traceSpanExporter.js';
+
+let sdk = null;
+let tracingActive = false;
+
+function setAttr(span, key, value) {
+  try {
+    if (!span || typeof span.setAttribute !== 'function') return;
+    if (value == null) return;
+    const v = typeof value === 'string' ? value : String(value);
+    if (!v) return;
+    span.setAttribute(key, v);
+  } catch {
+    // ignore
+  }
+}
+
+function setAttrNumber(span, key, value) {
+  try {
+    if (!span || typeof span.setAttribute !== 'function') return;
+    const n = Number(value);
+    if (!Number.isFinite(n)) return;
+    span.setAttribute(key, n);
+  } catch {
+    // ignore
+  }
+}
+
+function safeUrlFromOutgoingRequest(requestOptions) {
+  try {
+    if (!requestOptions) return '';
+    if (typeof requestOptions === 'string') return requestOptions;
+    if (requestOptions instanceof URL) return requestOptions.toString();
+    const protocol = requestOptions.protocol || 'http:';
+    const hostRaw = requestOptions.hostname || requestOptions.host || '';
+    const host = String(hostRaw).trim();
+    const path = requestOptions.path || requestOptions.pathname || '/';
+    if (!host) return '';
+    return `${protocol}//${host}${path}`;
+  } catch {
+    return '';
+  }
+}
+
+function safeHostFromIncoming(req) {
+  try {
+    const h = req?.headers?.host;
+    return h ? String(h).split(',')[0].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+function shouldIgnoreOutgoingHost(hostname) {
+  if (!hostname) return false;
+  const host = hostname.split(':')[0];
+  const cfg = getConfig();
+  if (cfg.tracing?.traceLocalHttp && (host === 'localhost' || host === '127.0.0.1' || host === '::1')) {
+    return false;
+  }
+  if (host === 'localhost' || host === '127.0.0.1' || host === '::1') return true;
+  try {
+    if (cfg.endpoint) {
+      const h = new URL(cfg.endpoint).hostname;
+      if (host === h) return true;
+    }
+  } catch {
+    // ignore
+  }
+  return false;
+}
+
+/**
+ * Start OpenTelemetry when enabled in config. Returns true if tracing owns HTTP instrumentation.
+ */
+export function startTracing() {
+  const cfg = getConfig();
+  if (!cfg.tracing?.enabled) {
+    debug('OpenTelemetry tracing disabled (SENTIENGUARD_TRACING=false)');
+    return false;
+  }
+
+  if (tracingActive) {
+    return true;
+  }
+
+  try {
+    const resource = new Resource({
+      [SEMRESATTRS_SERVICE_NAME]: cfg.service,
+      [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: cfg.environment
+    });
+
+    const metricsExporter = new SentienGuardSpanExporter();
+    const traceExporter = new SentienGuardTraceSpanExporter();
+
+    const httpInstrumentation = new HttpInstrumentation({
+      ignoreOutgoingRequestHook: (requestOptions) => {
+        const host = requestOptions.hostname || (requestOptions.host ? String(requestOptions.host).split(':')[0] : '');
+        return shouldIgnoreOutgoingHost(host);
+      },
+      /**
+       * Ensure we always attach basic HTTP attributes.
+       * This protects us from cases where the underlying instrumentation
+       * doesn't populate attributes (common in some Node/Jest/undici combos).
+       */
+      requestHook: (span, request) => {
+        // Incoming request (SERVER)
+        if (request && typeof request === 'object' && 'headers' in request && 'method' in request) {
+          setAttr(span, 'http.method', request.method);
+          setAttr(span, 'http.target', request.url);
+          setAttr(span, 'http.host', safeHostFromIncoming(request));
+          return;
+        }
+
+        // Outgoing request (CLIENT) — requestOptions
+        setAttr(span, 'http.method', request?.method);
+        const url = safeUrlFromOutgoingRequest(request);
+        if (url) setAttr(span, 'http.url', url);
+        const host = request?.hostname || (request?.host ? String(request.host).split(':')[0] : '');
+        if (host) setAttr(span, 'net.peer.name', host);
+        if (request?.port) setAttrNumber(span, 'net.peer.port', request.port);
+      },
+      responseHook: (span, response) => {
+        // Incoming response (SERVER): ServerResponse
+        if (response && typeof response === 'object' && 'statusCode' in response) {
+          setAttrNumber(span, 'http.status_code', response.statusCode);
+        }
+      }
+      ,
+      /**
+       * More reliable cross-version hook that runs with both request+response context.
+       * Used as a safety net to guarantee basic attributes exist on spans.
+       */
+      applyCustomAttributesOnSpan: (span, request, response) => {
+        // Incoming request (SERVER)
+        if (request && typeof request === 'object' && 'headers' in request && 'method' in request) {
+          setAttr(span, 'http.method', request.method);
+          setAttr(span, 'http.target', request.url);
+          setAttr(span, 'http.host', safeHostFromIncoming(request));
+        } else {
+          // Outgoing request (CLIENT)
+          setAttr(span, 'http.method', request?.method);
+          const url = safeUrlFromOutgoingRequest(request);
+          if (url) setAttr(span, 'http.url', url);
+          const host = request?.hostname || (request?.host ? String(request.host).split(':')[0] : '');
+          if (host) setAttr(span, 'net.peer.name', host);
+          if (request?.port) setAttrNumber(span, 'net.peer.port', request.port);
+        }
+
+        if (response && typeof response === 'object' && 'statusCode' in response) {
+          setAttrNumber(span, 'http.status_code', response.statusCode);
+        }
+      }
+    });
+
+    const expressInstrumentation = new ExpressInstrumentation();
+    const mongoInstrumentation = new MongoDBInstrumentation();
+    const mongooseInstrumentation = new MongooseInstrumentation();
+
+    sdk = new NodeSDK({
+      resource,
+      // Important: keep span recording ON so APM metrics derived from spans are not undersampled.
+      // Raw trace export sampling is handled inside SentienGuardTraceSpanExporter instead.
+      sampler: new AlwaysOnSampler(),
+      textMapPropagator: new W3CTraceContextPropagator(),
+      // Include MongoDB/Mongoose instrumentations for "zero-code" DB spans.
+      // These are safe even when the app doesn't use MongoDB; they patch when modules are loaded.
+      instrumentations: [httpInstrumentation, expressInstrumentation, mongoInstrumentation, mongooseInstrumentation],
+      spanProcessors: [
+        new BatchSpanProcessor(metricsExporter),
+        new BatchSpanProcessor(traceExporter)
+      ],
+      autoDetectResources: false
+    });
+
+    sdk.start();
+    tracingActive = true;
+    debug('OpenTelemetry tracing started (W3C Trace Context + HTTP/Express)');
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    debug(`OpenTelemetry failed to start, falling back to legacy instrumentation: ${msg}`);
+    sdk = null;
+    tracingActive = false;
+    return false;
+  }
+}
+
+export function isTracingActive() {
+  return tracingActive;
+}
+
+/** Hex trace id for the active span (log correlation); undefined if none. */
+export function getActiveTraceId() {
+  const s = trace.getActiveSpan();
+  if (!s) return undefined;
+  const c = s.spanContext();
+  return c.traceId && c.traceFlags !== undefined ? c.traceId : undefined;
+}
+
+export async function shutdownTracing() {
+  if (!sdk) return;
+  try {
+    await sdk.shutdown();
+    debug('OpenTelemetry tracing shut down');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    debug(`OpenTelemetry shutdown error: ${msg}`);
+  } finally {
+    sdk = null;
+    tracingActive = false;
+  }
+}