flowtrace-omega 1.0.0

package/dashboard/server.js

@@ -0,0 +1,152 @@
+/**
+ * dashboard/server.js — The Dashboard Server
+ *
+ * A lightweight Express server that runs in the background.
+ * Serves the visual dashboard at localhost:9999
+ * and exposes the /traces JSON API endpoint.
+ */
+
+const express = require("express");
+const path = require("path");
+const { getAllTraces } = require("../src/exporter");
+
+const app = express();
+app.use(express.json());
+
+// ── Static files (public folder with landing pages) ────
+app.use(express.static(path.join(__dirname, "public")));
+
+// ── Landing page routes ────────────────────────────────
+app.get("/", (req, res) => {
+  res.sendFile(path.join(__dirname, "public", "index.html"));
+});
+
+app.get("/how", (req, res) => {
+  res.sendFile(path.join(__dirname, "public", "how.html"));
+});
+
+app.get("/docs", (req, res) => {
+  res.sendFile(path.join(__dirname, "public", "docs.html"));
+});
+
+// ── Dashboard UI (actual tracing visualization) ────────
+app.get("/app", (req, res) => {
+  res.sendFile(path.join(__dirname, "index.html"));
+});
+
+// ── Traces API ─────────────────────────────────────────
+// GET /traces — returns all recorded traces as JSON
+app.get("/traces", (req, res) => {
+  res.json(getAllTraces());
+});
+
+// DELETE /traces — clears the in-memory store (UI refresh)
+app.delete("/traces", (req, res) => {
+  const store = getAllTraces();
+  store.splice(0, store.length); // mutate the shared array
+  res.json({ cleared: true });
+});
+
+// POST /java-traces — receive and stitch Java agent traces
+app.post("/java-traces", (req, res) => {
+  const javaTraces = Array.isArray(req.body) ? req.body : [req.body];
+  const store = getAllTraces();
+
+  javaTraces.forEach(jt => {
+    const existing = store.find(t => t.traceId === jt.traceId);
+    if (existing) {
+      // Context Propagation: Stitch Java spans into the Node.js trace!
+      existing.spans = existing.spans.concat(jt.spans || []);
+      existing.totalDuration = Math.max(existing.totalDuration || 0, jt.totalDuration || 0);
+    } else {
+      store.push(jt);
+    }
+  });
+
+  res.json({ success: true, stitched: javaTraces.length });
+});
+
+// POST /api/proxy — The API Tester (Postman clone) Backend Proxy
+// Allows the frontend to bypass CORS and execute requests natively
+app.post("/api/proxy", async (req, res) => {
+  const { url, method = "GET", headers = {}, body } = req.body;
+  
+  if (!url) return res.status(400).json({ error: "URL is required" });
+
+  // Node 18+ has native fetch
+  try {
+    const startTime = Date.now();
+    
+    const fetchOptions = {
+      method,
+      headers,
+    };
+
+    if (body && ["POST", "PUT", "PATCH"].includes(method.toUpperCase())) {
+      fetchOptions.body = typeof body === "string" ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+    const latency = Date.now() - startTime;
+    
+    // Capture Headers
+    const resHeaders = {};
+    response.headers.forEach((val, key) => {
+      resHeaders[key] = val;
+    });
+
+    // Attempt parsing JSON
+    let data = await response.text();
+    try {
+      data = JSON.parse(data);
+    } catch(e) { }
+
+    res.json({
+      status: response.status,
+      statusText: response.statusText,
+      latency,
+      headers: resHeaders,
+      data,
+    });
+
+  } catch (err) {
+    res.status(500).json({
+      error: "Proxy Request Failed",
+      message: err.message
+    });
+  }
+});
+
+let serverInstance = null;
+
+/**
+ * Start the dashboard server.
+ * Safe to call multiple times — only starts once.
+ *
+ * @param {number} [port=9999]
+ */
+function startDashboard(port = 9999) {
+  if (serverInstance) return; // already running
+
+  serverInstance = app.listen(port, "0.0.0.0", () => {
+    console.log(`\n  ⚡ FlowTrace dashboard running at http://localhost:${port}\n`);
+  });
+
+  serverInstance.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.warn(`[FlowTrace] Port ${port} in use — dashboard not started. Try a different port.`);
+    }
+  });
+
+  return serverInstance;
+}
+
+// ── Standalone Mode (Render/Direct Execution) ────────────
+if (require.main === module) {
+  const port = process.env.PORT || 9999;
+  startDashboard(port);
+}
+
+// ── Module Exports (Vercel/Library Execution) ────────────
+module.exports = app;
+module.exports.startDashboard = startDashboard;

package/index.js

@@ -0,0 +1,115 @@
+/**
+ * index.js — The Initialization Module
+ *
+ * The single entry point for FlowTrace.
+ * The developer adds ONE line to their project:
+ *
+ *   const FlowTrace = require('flowtrace');
+ *   FlowTrace.start();
+ *
+ * That's it. Everything else happens automatically.
+ */
+
+const http = require("http");
+const crypto = require("crypto");
+const { runWithTraceId, getStore } = require("./src/context");
+const { finalizeTrace } = require("./src/exporter");
+const { trace } = require("./src/wrapper");
+const { startDashboard } = require("./dashboard/server");
+const { initIntegrations } = require("./src/integrations/index");
+
+let initialized = false;
+
+/**
+ * Start FlowTrace.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.port=9999]         - Dashboard port
+ * @param {string} [options.outputPath]        - Custom path for trace-output.json
+ * @param {boolean} [options.silent=false]     - Suppress console output
+ */
+function start(options = {}) {
+  if (initialized) return;
+  initialized = true;
+
+  const { port = 9999, outputPath, silent = false, otlpEndpoint } = options;
+
+  // 1. Hook into require() to inject Database/GraphQL integrations dynamically
+  initIntegrations();
+  
+  // 1b. Intercept outgoing HTTP requests
+  const { patchHttpClient } = require("./src/integrations/http_client");
+  patchHttpClient();
+
+  // 2. Start the visual dashboard server
+  startDashboard(port);
+
+  // 3. Monkey-patch Node's core http module so every incoming
+  //    request automatically gets a traceId injected into its
+  //    async context — zero config for the developer.
+  patchHttpModule({ outputPath, silent, otlpEndpoint });
+
+  if (!silent) {
+    console.log("  ✓ FlowTrace initialized — http module patched\n");
+  }
+}
+
+/**
+ * Intercept http.createServer to wrap every incoming request
+ * in a new AsyncLocalStorage trace context.
+ */
+function patchHttpModule({ outputPath, silent, otlpEndpoint }) {
+  const originalCreateServer = http.createServer.bind(http);
+
+  http.createServer = function (options, requestListener) {
+    // Handle both http.createServer(listener) and http.createServer(opts, listener)
+    let listener = typeof options === "function" ? options : requestListener;
+    const serverOptions = typeof options === "object" ? options : {};
+
+    const wrappedListener = function (req, res) {
+      let traceId = crypto.randomUUID();
+      const tp = req.headers["traceparent"];
+      if (tp && typeof tp === "string") {
+        const parts = tp.split("-");
+        // W3C format: 00-{trace-id}-{span-id}-{flags}
+        if (parts.length === 4) traceId = parts[1];
+      }
+
+      // Run the entire request handler inside a new trace context
+      runWithTraceId(traceId, () => {
+        const startTime = Date.now();
+
+        // Intercept res.end so we can finalize the trace when
+        // the response is sent — capturing the status code too
+        const originalEnd = res.end.bind(res);
+        res.end = function (...args) {
+          const store = getStore();
+          if (store) {
+            finalizeTrace({
+              traceId,
+              startTime,
+              method: req.method,
+              url: req.url,
+              statusCode: res.statusCode,
+              spans: store.spans,
+              outputPath,
+              otlpEndpoint,
+            });
+          }
+          return originalEnd(...args);
+        };
+
+        if (listener) listener(req, res);
+      });
+    };
+
+    return Object.keys(serverOptions).length > 0
+      ? originalCreateServer(serverOptions, wrappedListener)
+      : originalCreateServer(wrappedListener);
+  };
+}
+
+module.exports = {
+  start,
+  trace,
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "flowtrace-omega",
+  "version": "1.0.0",
+  "description": "Zero-config dynamic tracing for Node.js. Add one line, get live sequence diagrams of every HTTP request.",
+  "main": "index.js",
+  "bin": {
+    "flowtrace": "./bin/cli.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "dashboard/",
+    "adapters/",
+    "bin/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node dashboard/server.js",
+    "test": "node test/smoke.js"
+  },
+  "keywords": [
+    "tracing",
+    "observability",
+    "sequence-diagram",
+    "debugging",
+    "apm",
+    "async-local-storage",
+    "proxy",
+    "express",
+    "nestjs",
+    "distributed-tracing",
+    "developer-tools"
+  ],
+  "author": "kavysharma",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skavy359/FlowTrace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/skavy359/FlowTrace/issues"
+  },
+  "homepage": "https://github.com/skavy359/FlowTrace#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "express": "^4.18.2"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": { "optional": true }
+  }
+}

package/src/context.js

@@ -0,0 +1,74 @@
+/**
+ * context.js — The Context Manager
+ *
+ * Solves the async event loop problem using AsyncLocalStorage.
+ * Every async operation that flows from a single HTTP request
+ * will share the same traceId — automatically, with zero user config.
+ */
+
+const { AsyncLocalStorage } = require("async_hooks");
+
+// Singleton instance shared across the entire library
+const asyncLocalStorage = new AsyncLocalStorage();
+
+/**
+ * Run a function within a new trace context.
+ * Everything called inside `fn` (sync or async) will share this traceId.
+ *
+ * @param {string} traceId - Unique ID for this request trace
+ * @param {Function} fn - The function to run inside the context
+ */
+
+function runWithTraceId(traceId, fn) {
+  const store = {
+    traceId,
+    spans: [],       // All spans collected for this trace
+    startTime: Date.now(),
+  };
+  asyncLocalStorage.run(store, fn);
+}
+
+/**
+ * Get the full store object for the current async context.
+ * Returns null if called outside a trace context.
+ */
+function getStore() {
+  return asyncLocalStorage.getStore() || null;
+}
+
+/**
+ * Get just the traceId for the current async context.
+ */
+function getCurrentTraceId() {
+  const store = getStore();
+  return store ? store.traceId : null;
+}
+
+/**
+ * Push a span into the current trace's span collection.
+ * Safe to call from anywhere — silently no-ops if no active context.
+ *
+ * @param {Object} span - The span object to record
+ */
+function pushSpan(span) {
+  const store = getStore();
+  if (store) {
+    store.spans.push(span);
+  }
+}
+
+/**
+ * Get all spans for the current trace context.
+ */
+function getCurrentSpans() {
+  const store = getStore();
+  return store ? store.spans : [];
+}
+
+module.exports = {
+  runWithTraceId,
+  getStore,
+  getCurrentTraceId,
+  pushSpan,
+  getCurrentSpans,
+};

package/src/exporter.js

@@ -0,0 +1,112 @@
+/**
+ * exporter.js — The Data Exporter
+ *
+ * Handles persisting completed traces to disk as structured JSON.
+ * Also maintains an in-memory store of recent traces for the dashboard.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// In-memory ring buffer — keeps the last N traces for the live dashboard
+const MAX_TRACES = 50;
+const traceStore = [];
+
+/**
+ * A completed "Trace" is the top-level object that groups all spans
+ * from a single HTTP request lifecycle.
+ *
+ * @typedef {Object} Trace
+ * @property {string} traceId
+ * @property {number} startTime       - Unix ms timestamp
+ * @property {number} totalDuration   - ms from first to last span
+ * @property {string} method          - HTTP method (GET, POST, …)
+ * @property {string} url             - Request URL
+ * @property {number} statusCode      - HTTP response status
+ * @property {Object[]} spans         - All recorded spans
+ */
+
+const { exportToOtlp } = require("./otlp");
+
+/**
+ * Finalize a trace and push it to the store + disk.
+ *
+ * @param {Object} params
+ * @param {string} params.traceId
+ * @param {number} params.startTime
+ * @param {string} params.method
+ * @param {string} params.url
+ * @param {number} params.statusCode
+ * @param {Object[]} params.spans
+ * @param {string} [params.outputPath]  - Where to write trace-output.json
+ * @param {string} [params.otlpEndpoint] - Optional OpenTelemetry endpoint (e.g. Jaeger)
+ */
+
+function finalizeTrace({ traceId, startTime, method, url, statusCode, spans, outputPath, otlpEndpoint }) {
+  const endTime = Date.now();
+
+  const trace = {
+    traceId,
+    startTime,
+    endTime,
+    totalDuration: endTime - startTime,
+    method,
+    url,
+    statusCode,
+    spanCount: spans.length,
+    spans,
+  };
+
+  // Push to in-memory ring buffer
+  traceStore.unshift(trace);
+  if (traceStore.length > MAX_TRACES) {
+    traceStore.pop();
+  }
+
+  // Write to disk (append mode — one JSON object per line = newline-delimited JSON)
+  const filePath = outputPath || path.join(process.cwd(), "trace-output.json");
+  persistTrace(trace, filePath);
+
+  // If the user configured an OpenTelemetry Collector, forward it!
+  if (otlpEndpoint) {
+    exportToOtlp(trace, otlpEndpoint);
+  }
+
+  return trace;
+}
+
+/**
+ * Write the entire current traceStore to the JSON file.
+ * We overwrite each time to keep the file clean and parseable.
+ */
+function persistTrace(trace, filePath) {
+  try {
+    let existing = [];
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, "utf-8").trim();
+      if (raw) existing = JSON.parse(raw);
+    }
+    existing.unshift(trace);
+    if (existing.length > MAX_TRACES) existing = existing.slice(0, MAX_TRACES);
+    fs.writeFileSync(filePath, JSON.stringify(existing, null, 2), "utf-8");
+  } catch (err) {
+    // Non-fatal — dashboard still works via in-memory store
+    console.warn(`[FlowTrace] Could not write trace-output.json: ${err.message}`);
+  }
+}
+
+/**
+ * Get all in-memory traces (for the dashboard API endpoint).
+ */
+function getAllTraces() {
+  return traceStore;
+}
+
+/**
+ * Get a single trace by ID.
+ */
+function getTrace(traceId) {
+  return traceStore.find((t) => t.traceId === traceId) || null;
+}
+
+module.exports = { finalizeTrace, getAllTraces, getTrace };

package/src/integrations/graphql.js

@@ -0,0 +1,101 @@
+const { getCurrentTraceId, pushSpan } = require("../context");
+
+let patched = false;
+
+function patchGraphQL(graphql) {
+  if (!graphql || !graphql.execute) return graphql;
+  if (patched) return graphql;
+  patched = true;
+
+  const originalExecute = graphql.execute;
+
+  graphql.execute = function (...args) {
+    const traceId = getCurrentTraceId();
+    if (!traceId) return originalExecute.apply(this, args);
+
+    const startTime = performance.now();
+    let opName = "GraphQL Query";
+    let queryBody = "";
+
+    // GraphQL execute can receive an object or multiple arguments
+    let doc = null;
+    if (args.length === 1 && typeof args[0] === "object") {
+      doc = args[0].document;
+      if (args[0].operationName) opName = args[0].operationName;
+    } else if (args.length >= 2) {
+      doc = args[1];
+      if (args.length >= 6 && args[5]) opName = args[5];
+    }
+
+    if (doc && doc.definitions) {
+      const def = doc.definitions.find(d => d.kind === 'OperationDefinition');
+      if (def && def.name && def.name.value) {
+        opName = def.name.value;
+      }
+      
+      // Attempt to extract the first level of fields to show what is being resolved
+      if (def && def.selectionSet && def.selectionSet.selections) {
+         const fields = def.selectionSet.selections
+            .filter(sel => sel.kind === 'Field')
+            .map(sel => sel.name.value);
+         if (fields.length > 0) {
+             queryBody = fields.join(", ");
+         }
+      }
+    }
+
+    const spanId = `span_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const span = {
+      spanId,
+      traceId,
+      label: "GraphQL",
+      callerLabel: "Node.js",
+      method: "RESOLVE",
+      args: [opName + (queryBody ? ` { ${queryBody} }` : "")],
+      startTime: Date.now(),
+      duration: null,
+      error: null,
+      type: "graphql",
+    };
+
+    try {
+      const result = originalExecute.apply(this, args);
+      
+      if (result && typeof result.then === "function") {
+        return result
+          .then((res) => {
+            span.duration = +(performance.now() - startTime).toFixed(3);
+            if (res.errors && res.errors.length > 0) {
+                span.error = res.errors[0].message;
+            }
+            pushSpan(span);
+            return res;
+          })
+          .catch((err) => {
+            span.duration = +(performance.now() - startTime).toFixed(3);
+            span.error = err.message;
+            pushSpan(span);
+            throw err;
+          });
+      }
+
+      // Sync Execution
+      span.duration = +(performance.now() - startTime).toFixed(3);
+      if (result.errors && result.errors.length > 0) {
+          span.error = result.errors[0].message;
+      }
+      pushSpan(span);
+      return result;
+
+    } catch (err) {
+      span.duration = +(performance.now() - startTime).toFixed(3);
+      span.error = err.message;
+      pushSpan(span);
+      throw err;
+    }
+  };
+
+  return graphql;
+}
+
+module.exports = { patchGraphQL };