@sentienguard/apm 1.0.11 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentienguard/apm",
-  "version": "1.0.11",
+  "version": "1.0.14",
   "description": "SentienGuard APM SDK - Minimal, production-safe application performance monitoring",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -8,6 +8,7 @@ export interface ApmConfig {
   service?: string;
   environment?: string;
   endpoint?: string;
+  tracesEndpoint?: string;
   flushInterval?: number;
   maxRoutes?: number;
   maxPayloadSize?: number;
@@ -17,6 +18,12 @@ export interface ApmConfig {
     enabled?: boolean;
     traceLocalHttp?: boolean;
     peerServiceMap?: Record<string, string>;
+    /** Export sampling for raw traces only (0..1). Metrics are not sampled. */
+    sampleRate?: number;
+    /** Drop-on-pressure queue size for raw span export */
+    maxQueueSize?: number;
+    /** Batch size for raw span export */
+    maxBatchSize?: number;
   };
 }
 

package/src/index.js

@@ -14,8 +14,12 @@
  *   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)
  *
@@ -33,6 +37,7 @@ import { instrumentMongoDB, autoInstrumentMongoDB, stopMongoDBInstrumentation }
 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;
 
@@ -100,6 +105,8 @@ function setupGracefulShutdown() {
 
     // Final flush
     await finalFlush();
+    // Best-effort flush of queued raw spans
+    await flushTraceQueue();
 
     debug('Shutdown complete');
   };
@@ -122,6 +129,8 @@ async function shutdown() {
   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();

package/src/traceSpanExporter.js

@@ -8,6 +8,7 @@
 import { ExportResultCode, hrTimeToMilliseconds } from '@opentelemetry/core';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { enqueueSpans } from './traceTransport.js';
+import { getConfig } from './config.js';
 
 function hrTimeToUnixNanoString(hrTime) {
   // hrTime is [seconds, nanoseconds]
@@ -35,6 +36,26 @@ function safeAttrs(attrs) {
   return {};
 }
 
+function shouldSampleTraceId(traceId, sampleRate) {
+  if (sampleRate == null) return true;
+  const r = Number(sampleRate);
+  if (!Number.isFinite(r)) return true;
+  if (r <= 0) return false;
+  if (r >= 1) return true;
+
+  // Deterministic sampling based on trace_id (stable across services).
+  // Use the first 8 hex chars (32 bits) -> [0,1).
+  try {
+    const prefix = String(traceId).slice(0, 8);
+    if (!/^[0-9a-f]{8}$/i.test(prefix)) return Math.random() < r;
+    const n = parseInt(prefix, 16) >>> 0;
+    const p = n / 0x100000000; // 2^32
+    return p < r;
+  } catch {
+    return Math.random() < r;
+  }
+}
+
 function serializeSpan(span) {
   const ctx = span?.spanContext?.();
   if (!ctx?.traceId || !ctx?.spanId) return null;
@@ -70,11 +91,14 @@ function serializeSpan(span) {
 export class SentienGuardTraceSpanExporter {
   export(spans, resultCallback) {
     try {
+      const cfg = getConfig();
+      const rate = cfg?.tracing?.sampleRate;
+
       const serialized = [];
       for (const span of spans) {
         try {
           const s = serializeSpan(span);
-          if (s) serialized.push(s);
+          if (s && shouldSampleTraceId(s.trace_id, rate)) serialized.push(s);
         } catch {
           // ignore
         }

package/src/traceTransport.js

@@ -14,8 +14,11 @@ import { debug, warn, getConfig, isEnabled } from './config.js';
 let queue = [];
 let scheduled = false;
 let consecutiveFailures = 0;
+let lastFailureAtMs = 0;
+let recoveryTimer = null;
 
 const MAX_CONSECUTIVE_FAILURES = 5;
+const RECOVERY_BACKOFF_MS = 30_000;
 
 function sendToBackend(payload) {
   return new Promise((resolve, reject) => {
@@ -96,13 +99,29 @@ async function flushOnce(batch) {
   try {
     await sendToBackend(payload);
     consecutiveFailures = 0;
+    lastFailureAtMs = 0;
     debug(`Trace flush ok: spans=${batch.length}`);
   } catch (err) {
     consecutiveFailures++;
+    lastFailureAtMs = Date.now();
     warn(`Trace flush failed (attempt ${consecutiveFailures}): ${err.message}`);
     if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
       // Stop retrying aggressively; drop future spans until backend recovers.
       warn('Trace flush: max failures reached; dropping spans under backpressure');
+      if (!recoveryTimer) {
+        recoveryTimer = setTimeout(() => {
+          recoveryTimer = null;
+          consecutiveFailures = 0;
+          lastFailureAtMs = 0;
+          debug('Trace flush: recovery window elapsed; retrying delivery');
+          if (queue.length && !scheduled) {
+            scheduled = true;
+            setImmediate(drainQueue);
+          }
+        }, RECOVERY_BACKOFF_MS);
+        // Allow process to exit naturally.
+        if (typeof recoveryTimer.unref === 'function') recoveryTimer.unref();
+      }
     }
   }
 }
@@ -114,6 +133,8 @@ function drainQueue() {
 
   // If backend is unhealthy, drop to protect app memory.
   if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+    // During the recovery backoff window, keep dropping to protect memory.
+    // After backoff, recoveryTimer resets failures and normal flushing resumes.
     queue = [];
     return;
   }
@@ -155,5 +176,35 @@ export function resetTraceQueueForTests() {
   queue = [];
   scheduled = false;
   consecutiveFailures = 0;
+  lastFailureAtMs = 0;
+  if (recoveryTimer) {
+    clearTimeout(recoveryTimer);
+    recoveryTimer = null;
+  }
+}
+
+/**
+ * Best-effort flush of queued spans (e.g. during shutdown).
+ * Never throws; safe to call even if tracing is disabled.
+ */
+export async function flushTraceQueue({ timeoutMs = 1500 } = {}) {
+  try {
+    if (!isEnabled()) return;
+    const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+    const cfg = getConfig();
+    const maxBatch = cfg.tracing?.maxBatchSize || 256;
+
+    while (queue.length && Date.now() < deadline) {
+      const batch = queue.slice(0, maxBatch);
+      queue = queue.slice(batch.length);
+      // Attempt flush even if failures happened earlier; this is a single best-effort drain.
+      consecutiveFailures = 0;
+      lastFailureAtMs = 0;
+      // eslint-disable-next-line no-await-in-loop
+      await flushOnce(batch);
+    }
+  } catch {
+    // ignore
+  }
 }
 

package/src/tracing.js

@@ -10,7 +10,7 @@ import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT } from '@o
 import { W3CTraceContextPropagator } from '@opentelemetry/core';
 import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
 import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
-import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';
+import { AlwaysOnSampler, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { getConfig, debug } from './config.js';
 import { SentienGuardSpanExporter } from './spanExporter.js';
 import { SentienGuardTraceSpanExporter } from './traceSpanExporter.js';
@@ -71,9 +71,9 @@ export function startTracing() {
 
     sdk = new NodeSDK({
       resource,
-      sampler: new ParentBasedSampler({
-        root: new TraceIdRatioBasedSampler(cfg.tracing?.sampleRate ?? 0.05)
-      }),
+      // 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(),
       instrumentations: [httpInstrumentation, expressInstrumentation],
       spanProcessors: [