@sentienguard/apm 1.0.9 → 1.0.11

package/package.json

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

package/src/config.js

@@ -14,6 +14,7 @@ const config = {
   service: '',
   environment: 'production',
   endpoint: 'https://sentienguard-dev.the-algo.com/api/v1/apm/ingest',
+  tracesEndpoint: '',
   flushInterval: 10,
   maxRoutes: 100,
   maxPayloadSize: 1024 * 1024,
@@ -43,7 +44,12 @@ const config = {
     /** When true, outgoing HTTP to localhost is traced (for multi-service dev). Default false. */
     traceLocalHttp: false,
     /** Port -> display name for local peers, from SENTIENGUARD_PEER_SERVICE_MAP */
-    peerServiceMap: {}
+    peerServiceMap: {},
+    /** Sampling rate for exporting raw spans (0..1). Parent-based. */
+    sampleRate: 0.05,
+    /** Span export queue + batch sizes (drop-on-pressure). */
+    maxQueueSize: 2048,
+    maxBatchSize: 256
   }
 };
 
@@ -60,6 +66,10 @@ export function loadConfig({ force = false } = {}) {
   config.service = process.env.SENTIENGUARD_SERVICE || '';
   config.environment = process.env.SENTIENGUARD_ENV || 'production';
   config.endpoint = process.env.SENTIENGUARD_ENDPOINT || 'https://sentienguard-dev.the-algo.com/api/v1/apm/ingest';
+  config.tracesEndpoint =
+    process.env.SENTIENGUARD_TRACES_ENDPOINT ||
+    deriveTracesEndpoint(config.endpoint) ||
+    'https://sentienguard-dev.the-algo.com/api/v1/apm/traces';
   config.flushInterval = parseInt(process.env.SENTIENGUARD_FLUSH_INTERVAL, 10) || 10;
   config.maxRoutes = parseInt(process.env.SENTIENGUARD_MAX_ROUTES, 10) || 100;
   config.maxPayloadSize = parseInt(process.env.SENTIENGUARD_MAX_PAYLOAD_SIZE, 10) || 1024 * 1024;
@@ -82,6 +92,13 @@ export function loadConfig({ force = false } = {}) {
   config.openai.slowCallMs = parseInt(process.env.SENTIENGUARD_OPENAI_SLOW_CALL_MS, 10) || 5000;
 
   config.tracing.enabled = process.env.SENTIENGUARD_TRACING !== 'false';
+  const sampleRaw = process.env.SENTIENGUARD_TRACE_SAMPLE_RATE;
+  const sample = sampleRaw != null ? Number(sampleRaw) : NaN;
+  if (!Number.isNaN(sample) && sample >= 0 && sample <= 1) {
+    config.tracing.sampleRate = sample;
+  }
+  config.tracing.maxQueueSize = parseInt(process.env.SENTIENGUARD_TRACE_MAX_QUEUE_SIZE, 10) || config.tracing.maxQueueSize;
+  config.tracing.maxBatchSize = parseInt(process.env.SENTIENGUARD_TRACE_MAX_BATCH_SIZE, 10) || config.tracing.maxBatchSize;
   // Default behavior:
   // - production: do NOT record localhost dependency edges (noise + self-calls)
   // - non-production: DO record localhost edges (local multi-service dev "just works")
@@ -114,6 +131,17 @@ function parsePeerServiceMap(raw) {
   return map;
 }
 
+function deriveTracesEndpoint(ingestEndpoint) {
+  try {
+    const u = new URL(String(ingestEndpoint));
+    // Common default: /api/v1/apm/ingest -> /api/v1/apm/traces
+    u.pathname = u.pathname.replace(/\/apm\/ingest\/?$/i, '/apm/traces');
+    return u.toString();
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Check if SDK is properly configured and should be active.
  * Triggers lazy config load if not yet loaded.

package/src/traceSpanExporter.js

@@ -0,0 +1,99 @@
+/**
+ * SpanExporter that ships sampled raw spans to SentienGuard trace ingest.
+ *
+ * This is intentionally "lossy": it enqueues serialized spans to an async transport
+ * and returns SUCCESS quickly to avoid blocking the app.
+ */
+
+import { ExportResultCode, hrTimeToMilliseconds } from '@opentelemetry/core';
+import { SpanStatusCode } from '@opentelemetry/api';
+import { enqueueSpans } from './traceTransport.js';
+
+function hrTimeToUnixNanoString(hrTime) {
+  // hrTime is [seconds, nanoseconds]
+  if (!Array.isArray(hrTime) || hrTime.length !== 2) return '';
+  const sec = BigInt(hrTime[0] || 0);
+  const ns = BigInt(hrTime[1] || 0);
+  return String(sec * 1000000000n + ns);
+}
+
+function statusForSpan(span) {
+  const code = span?.status?.code;
+  if (code === SpanStatusCode.ERROR) return { code: 'ERROR', message: span.status?.message || '' };
+  if (code === SpanStatusCode.OK) return { code: 'OK', message: span.status?.message || '' };
+  return { code: 'UNSET', message: span?.status?.message || '' };
+}
+
+function safeAttrs(attrs) {
+  if (!attrs) return {};
+  if (typeof attrs.get === 'function') {
+    const out = {};
+    for (const [k, v] of attrs.entries()) out[k] = v;
+    return out;
+  }
+  if (typeof attrs === 'object') return attrs;
+  return {};
+}
+
+function serializeSpan(span) {
+  const ctx = span?.spanContext?.();
+  if (!ctx?.traceId || !ctx?.spanId) return null;
+
+  const startNano = hrTimeToUnixNanoString(span.startTime);
+  const endNano = hrTimeToUnixNanoString(span.endTime);
+  if (!startNano || !endNano) return null;
+
+  const parentSpanId = span?.parentSpanId || span?.parentSpanContext?.spanId || null;
+  const status = statusForSpan(span);
+
+  const durationMs =
+    span.endTime && span.startTime
+      ? Math.max(0, hrTimeToMilliseconds(span.endTime) - hrTimeToMilliseconds(span.startTime))
+      : 0;
+
+  return {
+    trace_id: ctx.traceId,
+    span_id: ctx.spanId,
+    parent_span_id: parentSpanId || null,
+    name: span.name || '',
+    kind: span.kind != null ? String(span.kind) : undefined,
+    start_time_unix_nano: startNano,
+    end_time_unix_nano: endNano,
+    status,
+    attributes: safeAttrs(span.attributes),
+    events: Array.isArray(span.events) ? span.events : [],
+    links: Array.isArray(span.links) ? span.links : [],
+    duration_ms: Math.round(durationMs)
+  };
+}
+
+export class SentienGuardTraceSpanExporter {
+  export(spans, resultCallback) {
+    try {
+      const serialized = [];
+      for (const span of spans) {
+        try {
+          const s = serializeSpan(span);
+          if (s) serialized.push(s);
+        } catch {
+          // ignore
+        }
+      }
+
+      if (serialized.length) {
+        enqueueSpans(serialized);
+      }
+
+      resultCallback({ code: ExportResultCode.SUCCESS });
+    } catch (err) {
+      resultCallback({ code: ExportResultCode.FAILED, error: err });
+    }
+  }
+
+  shutdown() {
+    return Promise.resolve();
+  }
+}
+
+export default SentienGuardTraceSpanExporter;
+

package/src/traceTransport.js

@@ -0,0 +1,159 @@
+/**
+ * Trace Transport (raw spans)
+ *
+ * Rules:
+ * - Never block app requests.
+ * - Best-effort delivery; data loss is acceptable.
+ * - Drop under sustained failure or memory pressure.
+ */
+
+import https from 'https';
+import http from 'http';
+import { debug, warn, getConfig, isEnabled } from './config.js';
+
+let queue = [];
+let scheduled = false;
+let consecutiveFailures = 0;
+
+const MAX_CONSECUTIVE_FAILURES = 5;
+
+function sendToBackend(payload) {
+  return new Promise((resolve, reject) => {
+    const cfg = getConfig();
+    const data = JSON.stringify(payload);
+
+    // Reuse the same payload size protection as metrics
+    const maxBytes = cfg.maxPayloadSize || 1024 * 1024;
+    if (Buffer.byteLength(data) > maxBytes) {
+      return reject(new Error('Payload too large'));
+    }
+
+    let url;
+    try {
+      url = new URL(cfg.tracesEndpoint);
+    } catch {
+      return reject(new Error('Invalid traces endpoint URL'));
+    }
+
+    const isHttps = url.protocol === 'https:';
+    const transport = isHttps ? https : http;
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        'X-APM-Key': cfg.apiKey,
+        'X-Service': cfg.service,
+        'User-Agent': '@sentienguard/apm/1.0.0'
+      },
+      timeout: 5000
+    };
+
+    const req = transport.request(options, (res) => {
+      let responseData = '';
+      res.on('data', (chunk) => {
+        responseData += chunk;
+      });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve({ statusCode: res.statusCode, data: responseData });
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${responseData}`));
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      const reason = error instanceof Error ? error : new Error(String(error));
+      reject(reason);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+
+    req.write(data);
+    req.end();
+  });
+}
+
+async function flushOnce(batch) {
+  if (!isEnabled()) return;
+  if (!batch.length) return;
+
+  const cfg = getConfig();
+  const payload = {
+    service: cfg.service,
+    environment: cfg.environment,
+    spans: batch
+  };
+
+  try {
+    await sendToBackend(payload);
+    consecutiveFailures = 0;
+    debug(`Trace flush ok: spans=${batch.length}`);
+  } catch (err) {
+    consecutiveFailures++;
+    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');
+    }
+  }
+}
+
+function drainQueue() {
+  scheduled = false;
+  const cfg = getConfig();
+  const maxBatch = cfg.tracing?.maxBatchSize || 256;
+
+  // If backend is unhealthy, drop to protect app memory.
+  if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+    queue = [];
+    return;
+  }
+
+  // Send at most one batch per tick to keep exporter callbacks cheap.
+  const batch = queue.slice(0, maxBatch);
+  queue = queue.slice(batch.length);
+  void flushOnce(batch);
+
+  if (queue.length) {
+    scheduled = true;
+    setImmediate(drainQueue);
+  }
+}
+
+export function enqueueSpans(serializedSpans) {
+  const cfg = getConfig();
+  const maxQueue = cfg.tracing?.maxQueueSize || 2048;
+
+  if (!Array.isArray(serializedSpans) || serializedSpans.length === 0) return;
+  if (!isEnabled()) return;
+
+  // Drop-on-pressure.
+  const room = maxQueue - queue.length;
+  if (room <= 0) return;
+  if (serializedSpans.length > room) {
+    queue.push(...serializedSpans.slice(0, room));
+  } else {
+    queue.push(...serializedSpans);
+  }
+
+  if (!scheduled) {
+    scheduled = true;
+    setImmediate(drainQueue);
+  }
+}
+
+export function resetTraceQueueForTests() {
+  queue = [];
+  scheduled = false;
+  consecutiveFailures = 0;
+}
+

package/src/tracing.js

@@ -10,8 +10,10 @@ 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 { getConfig, debug } from './config.js';
 import { SentienGuardSpanExporter } from './spanExporter.js';
+import { SentienGuardTraceSpanExporter } from './traceSpanExporter.js';
 
 let sdk = null;
 let tracingActive = false;
@@ -55,7 +57,8 @@ export function startTracing() {
       [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: cfg.environment
     });
 
-    const traceExporter = new SentienGuardSpanExporter();
+    const metricsExporter = new SentienGuardSpanExporter();
+    const traceExporter = new SentienGuardTraceSpanExporter();
 
     const httpInstrumentation = new HttpInstrumentation({
       ignoreOutgoingRequestHook: (requestOptions) => {
@@ -68,9 +71,15 @@ export function startTracing() {
 
     sdk = new NodeSDK({
       resource,
-      traceExporter,
+      sampler: new ParentBasedSampler({
+        root: new TraceIdRatioBasedSampler(cfg.tracing?.sampleRate ?? 0.05)
+      }),
       textMapPropagator: new W3CTraceContextPropagator(),
       instrumentations: [httpInstrumentation, expressInstrumentation],
+      spanProcessors: [
+        new BatchSpanProcessor(metricsExporter),
+        new BatchSpanProcessor(traceExporter)
+      ],
       autoDetectResources: false
     });