flowtrace-omega 1.0.0

package/src/integrations/http_client.js

@@ -0,0 +1,107 @@
+const http = require("http");
+const https = require("https");
+const { getCurrentTraceId, pushSpan } = require("../context");
+
+let patched = false;
+
+function patchHttpClient() {
+  if (patched) return;
+  patched = true;
+
+  [http, https].forEach((module) => {
+    const originalRequest = module.request;
+
+    module.request = function (...args) {
+      const traceId = getCurrentTraceId();
+      
+      // If we are not inside a traced request, just pass through
+      if (!traceId) {
+        return originalRequest.apply(this, args);
+      }
+
+      // 1. Extract and mutate options
+      let url = "";
+      let options = {};
+      let callback = null;
+
+      if (typeof args[0] === "string" || args[0] instanceof URL) {
+        url = args[0].toString();
+        if (typeof args[1] === "object") {
+           options = args[1];
+           if (typeof args[2] === "function") callback = args[2];
+        } else if (typeof args[1] === "function") {
+           callback = args[1];
+        }
+      } else if (typeof args[0] === "object") {
+        options = args[0];
+        url = `${options.protocol||'http:'}//${options.hostname||options.host||'localhost'}${options.path||'/'}`;
+        if (typeof args[1] === "function") callback = args[1];
+      }
+
+      // Create proper headers if none exist
+      if (!options.headers) options.headers = {};
+
+      // W3C Trace Context injection
+      // 00 - version
+      // traceId - the 32 char hex from context (needs to be 32 char exactly, so we strip hyphens if UUID)
+      const sanitizedTraceId = traceId.replace(/-/g, "").padEnd(32, "0");
+      
+      const spanIdHex = Math.random().toString(16).slice(2, 18).padEnd(16, "0"); // 16 char hex
+      
+      options.headers["traceparent"] = `00-${sanitizedTraceId}-${spanIdHex}-01`;
+
+      const startTime = performance.now();
+      const internalSpanId = `span_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      const span = {
+        spanId: internalSpanId,
+        traceId,
+        label: url.length > 50 ? url.slice(0, 50) + "..." : url,
+        callerLabel: "Node.js",
+        method: options.method || "GET",
+        args: ["HTTP Outgoing"],
+        startTime: Date.now(),
+        duration: null,
+        error: null,
+        type: "http",
+      };
+
+      // We have to put the args back together
+      const newArgs = [];
+      if (typeof args[0] === "string" || args[0] instanceof URL) {
+        newArgs.push(args[0]);
+        newArgs.push(options);
+      } else {
+        newArgs.push(options);
+      }
+
+      // Add a wrapper to the callback if it existed
+      if (callback) {
+        newArgs.push(function (res) {
+          span.duration = +(performance.now() - startTime).toFixed(3);
+          pushSpan(span);
+          return callback(res);
+        });
+      }
+
+      const req = originalRequest.apply(this, newArgs);
+      
+      // If no callback, we listen to the response event
+      if (!callback) {
+        req.on('response', (res) => {
+          span.duration = +(performance.now() - startTime).toFixed(3);
+          pushSpan(span);
+        });
+      }
+      
+      req.on('error', (err) => {
+        span.duration = +(performance.now() - startTime).toFixed(3);
+        span.error = err.message;
+        pushSpan(span);
+      });
+
+      return req;
+    };
+  });
+}
+
+module.exports = { patchHttpClient };

package/src/integrations/index.js

@@ -0,0 +1,26 @@
+const Module = require("module");
+const { patchPg } = require("./pg");
+const { patchMysql2 } = require("./mysql2");
+const { patchGraphQL } = require("./graphql");
+
+function initIntegrations() {
+  const originalLoad = Module._load;
+  
+  Module._load = function (request, parent, isMain) {
+    const exports = originalLoad.apply(this, arguments);
+    
+    if (request === "pg") {
+      return patchPg(exports);
+    }
+    if (request === "mysql2") {
+      return patchMysql2(exports);
+    }
+    if (request === "graphql") {
+      return patchGraphQL(exports);
+    }
+    
+    return exports;
+  };
+}
+
+module.exports = { initIntegrations };

package/src/integrations/mysql2.js

@@ -0,0 +1,67 @@
+const { getCurrentTraceId, pushSpan } = require("../context");
+
+let patched = false;
+
+function patchMysql2(mysql) {
+  if (!mysql || !mysql.Connection || !mysql.Connection.prototype || !mysql.Connection.prototype.query) return mysql;
+  if (patched) return mysql;
+  patched = true;
+
+  const originalQuery = mysql.Connection.prototype.query;
+
+  mysql.Connection.prototype.query = function (...args) {
+    const traceId = getCurrentTraceId();
+    if (!traceId) return originalQuery.apply(this, args);
+
+    const startTime = performance.now();
+    let queryText = "?";
+    
+    if (typeof args[0] === "string") {
+      queryText = args[0];
+    } else if (args[0] && typeof args[0] === "object" && args[0].sql) {
+      queryText = args[0].sql;
+    }
+
+    const spanId = `span_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const span = {
+      spanId,
+      traceId,
+      label: "MySQL",
+      callerLabel: "Node.js",
+      method: "QUERY",
+      args: [queryText.length > 60 ? queryText.slice(0, 60) + "..." : queryText],
+      startTime: Date.now(),
+      duration: null,
+      error: null,
+      type: "db",
+    };
+
+    const lastArg = args[args.length - 1];
+    if (typeof lastArg === "function") {
+      args[args.length - 1] = function (...cbArgs) {
+        span.duration = +(performance.now() - startTime).toFixed(3);
+        const err = cbArgs[0];
+        if (err) span.error = err.message;
+        pushSpan(span);
+        return lastArg.apply(this, cbArgs);
+      };
+    } else {
+      // Sometimes no callback is provided in query, though rare.
+      const originalCb = args.find(a => typeof a === "function");
+      if (!originalCb) {
+         // Create dummy callback to catch the end
+         args.push(function(err, res) {
+            span.duration = +(performance.now() - startTime).toFixed(3);
+            if(err) span.error = err.message;
+            pushSpan(span);
+         });
+      }
+    }
+
+    return originalQuery.apply(this, args);
+  };
+
+  return mysql;
+}
+
+module.exports = { patchMysql2 };

package/src/integrations/pg.js

@@ -0,0 +1,79 @@
+const { getCurrentTraceId, pushSpan } = require("../context");
+
+let patched = false;
+
+function patchPg(pg) {
+  if (!pg || !pg.Client || !pg.Client.prototype || !pg.Client.prototype.query) return pg;
+  if (patched) return pg;
+  patched = true;
+
+  const originalQuery = pg.Client.prototype.query;
+
+  pg.Client.prototype.query = function (...args) {
+    const traceId = getCurrentTraceId();
+    if (!traceId) return originalQuery.apply(this, args);
+
+    const startTime = performance.now();
+    let queryText = "?";
+    
+    // pg.query can take a string, an object {text, values}, or a CustomQuery
+    if (typeof args[0] === "string") {
+      queryText = args[0];
+    } else if (args[0] && typeof args[0] === "object" && args[0].text) {
+      queryText = args[0].text;
+    }
+
+    const spanId = `span_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const span = {
+      spanId,
+      traceId,
+      label: "Database",
+      callerLabel: "Node.js",
+      method: "QUERY",
+      args: [queryText.length > 60 ? queryText.slice(0, 60) + "..." : queryText],
+      startTime: Date.now(),
+      duration: null,
+      error: null,
+      type: "db",
+    };
+
+    // Callback syntax detection
+    const lastArg = args[args.length - 1];
+    if (typeof lastArg === "function") {
+      args[args.length - 1] = function (...cbArgs) {
+        span.duration = +(performance.now() - startTime).toFixed(3);
+        const err = cbArgs[0];
+        if (err) span.error = err.message;
+        pushSpan(span);
+        return lastArg.apply(this, cbArgs);
+      };
+      return originalQuery.apply(this, args);
+    }
+
+    // Promise syntax
+    const result = originalQuery.apply(this, args);
+    if (result && typeof result.then === "function") {
+      return result
+        .then((res) => {
+          span.duration = +(performance.now() - startTime).toFixed(3);
+          pushSpan(span);
+          return res;
+        })
+        .catch((err) => {
+          span.duration = +(performance.now() - startTime).toFixed(3);
+          span.error = err.message;
+          pushSpan(span);
+          throw err;
+        });
+    }
+
+    // fallback sync (edge case)
+    span.duration = +(performance.now() - startTime).toFixed(3);
+    pushSpan(span);
+    return result;
+  };
+
+  return pg;
+}
+
+module.exports = { patchPg };

package/src/otlp.js

@@ -0,0 +1,120 @@
+const http = require("http");
+const https = require("https");
+
+const OTLP_SERVICE_NAME = process.env.OTEL_SERVICE_NAME || "flowtrace-node";
+
+/**
+ * Convert FlowTrace internal trace format to standard OpenTelemetry JSON format
+ * and POST it to an active collector.
+ *
+ * @param {Object} trace - The completed FlowTrace trace
+ * @param {string} endpoint - The OTLP endpoint (e.g. http://localhost:4318/v1/traces)
+ */
+
+function exportToOtlp(trace, endpoint) {
+  if (!endpoint) return;
+
+  // UUIDs must be hex without hyphens for OTLP
+  const traceId = trace.traceId.replace(/-/g, "").padEnd(32, "0");
+  
+  const otlpSpans = trace.spans.map((span, idx) => {
+    // Span ID must be 16 hex chars
+    let spanId = span.spanId ? span.spanId.replace(/[^0-9a-f]/g, "") : "";
+    if (spanId.length < 16) {
+      spanId = Math.random().toString(16).slice(2, 18).padEnd(16, "0");
+    } else {
+      spanId = spanId.slice(0, 16);
+    }
+    
+    return {
+      traceId,
+      spanId,
+      parentSpanId: idx === 0 ? undefined : otlpSpans[idx - 1]?.spanId, // Rough tree
+      name: span.method ? `${span.label}#${span.method}` : span.label || "Span",
+      kind: 1, // SPAN_KIND_INTERNAL
+      startTimeUnixNano: String((span.startTime || Date.now()) * 1000000),
+      endTimeUnixNano: String(((span.startTime || Date.now()) + (span.duration || 0)) * 1000000),
+      attributes: [
+        { key: "flowtrace.caller", value: { stringValue: span.callerLabel || "Unknown" } },
+        { key: "flowtrace.type", value: { stringValue: span.type || "unknown" } },
+      ],
+      status: span.error ? { code: 2, message: span.error } : { code: 1 }, // 2=ERROR, 1=OK
+    };
+  });
+
+  // Also create a "Server" entry span for the HTTP handler itself
+  const serverSpanId = Math.random().toString(16).slice(2, 18).padEnd(16, "0");
+  const serverSpan = {
+      traceId,
+      spanId: serverSpanId,
+      name: `${trace.method} ${trace.url}`,
+      kind: 2, // SPAN_KIND_SERVER
+      startTimeUnixNano: String(trace.startTime * 1000000),
+      endTimeUnixNano: String(trace.endTime * 1000000),
+      attributes: [
+        { key: "http.method", value: { stringValue: trace.method } },
+        { key: "http.url", value: { stringValue: trace.url } },
+        { key: "http.status_code", value: { intValue: trace.statusCode } }
+      ],
+      status: trace.statusCode >= 400 ? { code: 2 } : { code: 1 }
+  };
+  
+  // Link all child spans to the server span
+  otlpSpans.forEach(s => {
+      if (!s.parentSpanId) s.parentSpanId = serverSpanId;
+  });
+  
+  otlpSpans.unshift(serverSpan);
+
+  const payload = {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            {
+              key: "service.name",
+              value: { stringValue: OTLP_SERVICE_NAME },
+            },
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: "flowtrace-agent", version: "1.0.0" },
+            spans: otlpSpans,
+          },
+        ],
+      },
+    ],
+  };
+
+  const payloadString = JSON.stringify(payload);
+  const isHttps = endpoint.startsWith("https://");
+  const parsedUrl = new URL(endpoint);
+
+  const options = {
+    hostname: parsedUrl.hostname,
+    port: parsedUrl.port || (isHttps ? 443 : 80),
+    path: parsedUrl.pathname,
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(payloadString),
+    },
+  };
+
+  const engine = isHttps ? https : http;
+  const req = engine.request(options, (res) => {
+    res.on("data", () => {});
+    res.on("end", () => {
+    });
+  });
+
+  req.on("error", (e) => {
+    console.warn(`[FlowTrace] Failed to export OpenTelemetry trace: ${e.message}`);
+  });
+
+  req.write(payloadString);
+  req.end();
+}
+
+module.exports = { exportToOtlp };

package/src/wrapper.js

@@ -0,0 +1,123 @@
+/**
+ * wrapper.js — The Interceptor
+ *
+ * The magic that spies on the user's code.
+ * Wraps any class instance or plain object in a JavaScript Proxy.
+ * On every method call, it records a Span: who called what, when, and how long it took.
+ */
+
+const { getCurrentTraceId, pushSpan } = require("./context");
+
+/**
+ * Generate a simple unique span ID.
+ */
+function generateSpanId() {
+  return `span_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Wrap a class instance or plain object so every method call is traced.
+ *
+ * Usage:
+ *   const tracedService = trace(new UserService(), "UserService");
+ *
+ * @param {Object} target - The object/instance to wrap
+ * @param {string} label  - Human-readable name shown in diagrams (e.g. "UserService")
+ * @param {string} [callerLabel] - Optional: the label of the caller for diagram edges
+ * @returns {Proxy} - A transparent proxy that records spans on every method call
+ */
+
+function trace(target, label, callerLabel = "Client") {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      const original = Reflect.get(obj, prop, receiver);
+
+      // Only intercept actual functions; pass through everything else
+      if (typeof original !== "function") {
+        return original;
+      }
+
+      // Return a wrapped version of the function
+      return function (...args) {
+        const traceId = getCurrentTraceId();
+
+        // If we're not inside a trace context, just call the original
+        if (!traceId) {
+          return original.apply(obj, args);
+        }
+
+        const spanId = generateSpanId();
+        const startTime = performance.now();
+        const methodName = String(prop);
+
+        // Build the span skeleton before we know the result
+        const span = {
+          spanId,
+          traceId,
+          label,         // The component being called (e.g. "UserService")
+          callerLabel,   // The component doing the calling (e.g. "UserController")
+          method: methodName,
+          args: serializeArgs(args),
+          startTime: Date.now(),
+          duration: null,
+          error: null,
+          type: "function",
+        };
+
+        let result;
+        try {
+          result = original.apply(obj, args);
+
+          // Handle async functions — wait for the promise to settle
+          if (result instanceof Promise) {
+            return result
+              .then((resolved) => {
+                span.duration = +(performance.now() - startTime).toFixed(3);
+                pushSpan(span);
+                return resolved;
+              })
+              .catch((err) => {
+                span.duration = +(performance.now() - startTime).toFixed(3);
+                span.error = err.message;
+                pushSpan(span);
+                throw err;
+              });
+          }
+
+          // Synchronous function — record immediately
+          span.duration = +(performance.now() - startTime).toFixed(3);
+          pushSpan(span);
+          return result;
+
+        } catch (err) {
+          span.duration = +(performance.now() - startTime).toFixed(3);
+          span.error = err.message;
+          pushSpan(span);
+          throw err;
+        }
+      };
+    },
+  });
+}
+
+/**
+ * Safely serialize function arguments for the span log.
+ * Avoids circular references and keeps things readable.
+ */
+function serializeArgs(args) {
+  return args.map((arg) => {
+    if (arg === null || arg === undefined) return String(arg);
+    if (typeof arg === "function") return "[Function]";
+    if (typeof arg === "object") {
+      try {
+        const str = JSON.stringify(arg);
+        return str.length > 200 ? str.slice(0, 200) + "…" : str;
+      } catch {
+        return "[Object]";
+      }
+    }
+    return String(arg);
+  });
+}
+
+module.exports = { trace };