@deepeloper/deeptracker 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @deepeloper/deeptracker
+
+> Auto-instrumenting **deep request tracer** for Node.js. See exactly what your API is doing — every request, every step, every error.
+
+It records the full journey of each HTTP request — middleware, database queries, outbound
+calls, errors — as a nested trace, and ships it to your [deeptracker dashboard](https://github.com/deepeloper)
+where you can view it as a waterfall.
+
+## Install
+
+```bash
+npm i @deepeloper/deeptracker
+```
+
+## Quick start
+
+Call `init()` once, at the very top of your entry file — **before** you require your
+framework — so the auto-instrumentation is in place:
+
+```ts
+import tracker from '@deepeloper/deeptracker';
+
+tracker.init({
+  apiKey: 'trk_live_xxx', // from your dashboard
+  appName: 'my-api',
+});
+
+// ...then start your app as usual. Express, http/https and pg are traced automatically.
+```
+
+That's it. Every request now produces a trace with timing for each step, and any error is
+captured with the span where it happened.
+
+## What's captured automatically
+
+| Source                                        | What you get                                              |
+| --------------------------------------------- | --------------------------------------------------------- |
+| Inbound HTTP (any framework on `http.Server`) | a root trace per request (method, path, status, duration) |
+| Express                                       | parameterized route templates (`/users/:id`)              |
+| `http` / `https` outbound                     | child spans for axios / request-based clients             |
+| `pg`                                          | database query spans (timing, row count)                  |
+
+## Manual spans & tags
+
+```ts
+// Wrap your own logic so it shows up in the trace
+const user = await tracker.span('db.getUser', () => db.users.find(id));
+
+// Tag the current trace (searchable in the dashboard)
+tracker.setTag('userId', id);
+
+// Add a log event to the current span
+tracker.log('cache miss, fetching from DB');
+```
+
+## Configuration
+
+```ts
+tracker.init({
+  apiKey: 'trk_live_xxx',
+  appName: 'my-api',
+  environment: 'production', // defaults to NODE_ENV
+  endpoint: 'https://...', // custom ingest endpoint (defaults to the hosted platform)
+  sampleRate: 1.0, // 0.0–1.0, fraction of requests to trace
+  ignore: ['/health', '/favicon.ico'], // paths (or predicates) to skip
+  flushIntervalMs: 5000, // how often buffered traces are shipped
+});
+```
+
+Without an `endpoint`, traces print to the console as a waterfall — handy in development.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,546 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  flush: () => flush,
+  getConfig: () => getConfig,
+  init: () => init,
+  log: () => log,
+  setTag: () => setTag,
+  span: () => span
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/context.ts
+var import_node_async_hooks = require("async_hooks");
+var als = new import_node_async_hooks.AsyncLocalStorage();
+function getStore() {
+  return als.getStore();
+}
+function runWith(store, fn) {
+  return als.run(store, fn);
+}
+
+// src/core/tracer.ts
+var import_node_perf_hooks = require("perf_hooks");
+
+// src/core/ids.ts
+var import_node_crypto = require("crypto");
+function newTraceId() {
+  return (0, import_node_crypto.randomBytes)(16).toString("hex");
+}
+function newSpanId() {
+  return (0, import_node_crypto.randomBytes)(8).toString("hex");
+}
+
+// src/core/tracer.ts
+var state = {
+  appName: "unknown",
+  environment: "development",
+  sampleRate: 1,
+  ignore: [],
+  sink: null
+};
+function configure(patch) {
+  state = { ...state, ...patch };
+}
+function shouldTrace(req) {
+  if (state.sampleRate < 1 && Math.random() > state.sampleRate) return false;
+  const path = stripQuery(req.url ?? "");
+  for (const rule of state.ignore) {
+    if (typeof rule === "string" ? rule === path : safeRule(rule, req)) return false;
+  }
+  return true;
+}
+function createTrace() {
+  return {
+    traceId: newTraceId(),
+    appName: state.appName,
+    environment: state.environment,
+    rootSpanId: newSpanId(),
+    startWall: Date.now(),
+    startMono: import_node_perf_hooks.performance.now(),
+    tags: {},
+    spans: [],
+    http: {},
+    ended: false
+  };
+}
+function startSpan(name, type, metadata = {}) {
+  const store = getStore();
+  if (!store) return null;
+  const parentId = store.parent ? store.parent.spanId : store.trace.rootSpanId;
+  const span2 = {
+    spanId: newSpanId(),
+    parentSpanId: parentId,
+    traceId: store.trace.traceId,
+    name,
+    type,
+    startTime: Date.now(),
+    endTime: 0,
+    duration: 0,
+    status: "ok",
+    metadata,
+    events: [],
+    _startMono: import_node_perf_hooks.performance.now()
+  };
+  store.trace.spans.push(span2);
+  return span2;
+}
+function endSpan(span2, error) {
+  if (!span2 || span2.endTime !== 0) return;
+  span2.duration = import_node_perf_hooks.performance.now() - span2._startMono;
+  span2.endTime = span2.startTime + span2.duration;
+  if (error !== void 0) {
+    span2.status = "error";
+    span2.error = toSpanError(error);
+  }
+}
+async function runInSpan(name, type, fn) {
+  const store = getStore();
+  if (!store) return await fn();
+  const span2 = startSpan(name, type);
+  if (!span2) return await fn();
+  return await runWith({ trace: store.trace, parent: span2 }, async () => {
+    try {
+      const result = await fn();
+      endSpan(span2);
+      return result;
+    } catch (err) {
+      endSpan(span2, err);
+      throw err;
+    }
+  });
+}
+function endTrace(trace, statusCode, path) {
+  if (trace.ended) return;
+  trace.ended = true;
+  const duration = import_node_perf_hooks.performance.now() - trace.startMono;
+  const hasError = statusCode >= 500 || trace.spans.some((s) => s.status === "error");
+  const out = {
+    traceId: trace.traceId,
+    appName: trace.appName,
+    environment: trace.environment,
+    startTime: trace.startWall,
+    endTime: trace.startWall + duration,
+    duration,
+    status: hasError ? "error" : "ok",
+    http: {
+      method: trace.http.method ?? "GET",
+      path,
+      rawPath: trace.http.rawPath ?? path,
+      statusCode,
+      ...trace.http.userAgent !== void 0 ? { userAgent: trace.http.userAgent } : {}
+    },
+    tags: trace.tags,
+    rootSpanId: trace.rootSpanId,
+    spans: trace.spans.map(serializeSpan)
+  };
+  state.sink?.(out);
+}
+function serializeSpan(span2) {
+  const { _startMono: _ignored, ...rest } = span2;
+  void _ignored;
+  return rest;
+}
+function toSpanError(error) {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      stack: error.stack ?? "",
+      type: error.name || "Error"
+    };
+  }
+  return { message: String(error), stack: "", type: "Error" };
+}
+function safeRule(rule, req) {
+  try {
+    return rule(req);
+  } catch {
+    return false;
+  }
+}
+function stripQuery(url) {
+  const q = url.indexOf("?");
+  return q === -1 ? url : url.slice(0, q);
+}
+
+// src/core/buffer.ts
+var DEFAULTS = { maxSize: 100, flushIntervalMs: 5e3 };
+var TraceBuffer = class {
+  constructor(exporter, opts = {}) {
+    this.exporter = exporter;
+    this.opts = { ...DEFAULTS, ...opts };
+  }
+  exporter;
+  items = [];
+  timer = null;
+  opts;
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.flush(), this.opts.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  add(trace) {
+    this.items.push(trace);
+    if (this.items.length >= this.opts.maxSize) void this.flush();
+  }
+  async flush() {
+    if (this.items.length === 0) return;
+    const batch = this.items;
+    this.items = [];
+    try {
+      await this.exporter.export(batch);
+    } catch {
+    }
+  }
+  async shutdown() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+};
+
+// src/transport/console.ts
+var ConsoleExporter = class {
+  export(traces) {
+    for (const trace of traces) {
+      this.print(trace);
+    }
+  }
+  print(trace) {
+    const flag = trace.status === "error" ? "\u2717" : "\u2713";
+    const head = `${flag} ${trace.http.method} ${trace.http.path} ${trace.http.statusCode} ${fmt(trace.duration)}`;
+    console.log(`
+[tracker] ${head}  (${trace.traceId})`);
+    const byParent = /* @__PURE__ */ new Map();
+    for (const span2 of trace.spans) {
+      const key = span2.parentSpanId ?? trace.rootSpanId;
+      const list = byParent.get(key) ?? [];
+      list.push(span2);
+      byParent.set(key, list);
+    }
+    const walk = (parentId, depth) => {
+      const children = (byParent.get(parentId) ?? []).sort((a, b) => a.startTime - b.startTime);
+      for (const span2 of children) {
+        const indent = "  ".repeat(depth + 1);
+        const mark = span2.status === "error" ? " \u2717" : "";
+        console.log(`${indent}${span2.type}: ${span2.name}  ${fmt(span2.duration)}${mark}`);
+        if (span2.error) {
+          console.log(`${indent}  \u21B3 ${span2.error.type}: ${span2.error.message}`);
+        }
+        walk(span2.spanId, depth + 1);
+      }
+    };
+    walk(trace.rootSpanId, 0);
+  }
+};
+function fmt(ms) {
+  return ms < 1e3 ? `${Math.round(ms)}ms` : `${(ms / 1e3).toFixed(2)}s`;
+}
+
+// src/transport/http.ts
+var HttpExporter = class {
+  constructor(endpoint, apiKey, timeoutMs = 3e3) {
+    this.endpoint = endpoint;
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+  }
+  endpoint;
+  apiKey;
+  timeoutMs;
+  async export(traces) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ traces }),
+        signal: controller.signal
+      });
+    } catch {
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/instruments/http.ts
+var import_node_http = __toESM(require("http"), 1);
+var import_node_https = __toESM(require("https"), 1);
+
+// src/instruments/wrap.ts
+var WRAPPED = /* @__PURE__ */ Symbol.for("deeptracker.wrapped");
+function wrap(target, name, factory) {
+  const original = target[name];
+  if (typeof original !== "function") return;
+  if (original[WRAPPED]) return;
+  const wrapped = factory(original);
+  Object.defineProperty(wrapped, "name", {
+    value: original.name,
+    configurable: true
+  });
+  wrapped[WRAPPED] = true;
+  wrapped.__original = original;
+  target[name] = wrapped;
+}
+
+// src/instruments/http.ts
+var HANDLED = /* @__PURE__ */ Symbol.for("deeptracker.http.handled");
+function installHttpServer() {
+  const patchServer = (proto) => {
+    wrap(
+      proto,
+      "emit",
+      (emit) => function(event, ...args) {
+        if (event !== "request") return emit.call(this, event, ...args);
+        const req = args[0];
+        const res = args[1];
+        if (!req || !res || req[HANDLED]) return emit.call(this, event, ...args);
+        req[HANDLED] = true;
+        if (!shouldTrace(req)) return emit.call(this, event, ...args);
+        const trace = createTrace();
+        trace.http.method = req.method ?? "GET";
+        trace.http.rawPath = stripQuery(String(req.url ?? "/"));
+        const ua = req.headers?.["user-agent"];
+        if (typeof ua === "string") trace.http.userAgent = ua;
+        return runWith({ trace, parent: null }, () => {
+          res.on("finish", () => {
+            endTrace(trace, res.statusCode ?? 0, resolvePath(req, trace.http.rawPath ?? "/"));
+          });
+          return emit.call(this, event, ...args);
+        });
+      }
+    );
+  };
+  patchServer(import_node_http.default.Server.prototype);
+  if (import_node_https.default.Server && import_node_https.default.Server.prototype !== import_node_http.default.Server.prototype) {
+    patchServer(import_node_https.default.Server.prototype);
+  }
+}
+function resolvePath(req, fallback) {
+  const routePath = req.route?.path;
+  if (typeof routePath === "string") {
+    return (req.baseUrl ?? "") + routePath;
+  }
+  return fallback;
+}
+function installHttpClient() {
+  for (const [mod, scheme] of [
+    [import_node_http.default, "http"],
+    [import_node_https.default, "https"]
+  ]) {
+    for (const method of ["request", "get"]) {
+      wrap(
+        mod,
+        method,
+        (original) => function(...args) {
+          const desc = describeOutbound(args, scheme);
+          const span2 = startSpan(`${desc.method} ${desc.url}`, "http", {
+            method: desc.method,
+            url: desc.url
+          });
+          if (!span2) return original.apply(this, args);
+          const req = original.apply(this, args);
+          let settled = false;
+          const finish = (err) => {
+            if (settled) return;
+            settled = true;
+            endSpan(span2, err);
+          };
+          try {
+            req.on("response", (res) => {
+              span2.metadata.statusCode = res.statusCode;
+            });
+            req.on("error", (err) => finish(err));
+            req.on("close", () => finish());
+          } catch {
+            finish();
+          }
+          return req;
+        }
+      );
+    }
+  }
+}
+function describeOutbound(args, scheme) {
+  const first = args[0];
+  let method = "GET";
+  let url = "";
+  if (typeof first === "string") {
+    url = first;
+  } else if (first instanceof URL) {
+    url = first.toString();
+  } else if (first && typeof first === "object") {
+    const host = first.hostname ?? first.host ?? "localhost";
+    const path = first.path ?? "/";
+    method = first.method ?? "GET";
+    url = `${scheme}://${host}${path}`;
+  }
+  const second = args[1];
+  if (second && typeof second === "object" && typeof second.method === "string") {
+    method = second.method;
+  }
+  return { method, url };
+}
+
+// src/instruments/pg.ts
+var import_node_module = require("module");
+var import_meta = {};
+function patchPgClient(ClientClass) {
+  if (!ClientClass?.prototype) return;
+  wrap(
+    ClientClass.prototype,
+    "query",
+    (original) => function(...args) {
+      const span2 = startSpan(describeQuery(args[0]), "db", { query: extractSql(args[0]) });
+      if (!span2) return original.apply(this, args);
+      const last = args[args.length - 1];
+      if (typeof last === "function") {
+        args[args.length - 1] = function(...cbArgs) {
+          const [err, result] = cbArgs;
+          if (result?.rowCount != null) span2.metadata.rowCount = result.rowCount;
+          endSpan(span2, err ?? void 0);
+          return last.apply(this, cbArgs);
+        };
+        return original.apply(this, args);
+      }
+      const promise = original.apply(this, args);
+      if (promise && typeof promise.then === "function") {
+        return promise.then(
+          (result) => {
+            if (result?.rowCount != null) span2.metadata.rowCount = result.rowCount;
+            endSpan(span2);
+            return result;
+          },
+          (err) => {
+            endSpan(span2, err);
+            throw err;
+          }
+        );
+      }
+      endSpan(span2);
+      return promise;
+    }
+  );
+}
+function installPg() {
+  try {
+    const require2 = (0, import_node_module.createRequire)(import_meta.url);
+    const pg = require2("pg");
+    patchPgClient(pg.Client);
+  } catch {
+  }
+}
+function extractSql(arg) {
+  const text = typeof arg === "string" ? arg : arg?.text ?? "";
+  return String(text).slice(0, 2e3);
+}
+function describeQuery(arg) {
+  const sql = extractSql(arg).trim().replace(/\s+/g, " ");
+  const verb = sql.split(" ")[0]?.toUpperCase() ?? "QUERY";
+  return `db.${verb.toLowerCase()}`;
+}
+
+// src/index.ts
+var activeConfig = null;
+var buffer = null;
+function init(config) {
+  if (!config.apiKey) throw new Error("[tracker] `apiKey` is required");
+  if (!config.appName) throw new Error("[tracker] `appName` is required");
+  activeConfig = config;
+  const environment = config.environment ?? process.env["NODE_ENV"] ?? "development";
+  const exporter = config.endpoint !== void 0 ? new HttpExporter(config.endpoint, config.apiKey) : new ConsoleExporter();
+  buffer = new TraceBuffer(exporter, {
+    ...config.maxBatchSize !== void 0 ? { maxSize: config.maxBatchSize } : {},
+    ...config.flushIntervalMs !== void 0 ? { flushIntervalMs: config.flushIntervalMs } : {}
+  });
+  buffer.start();
+  configure({
+    appName: config.appName,
+    environment,
+    sampleRate: config.sampleRate ?? 1,
+    ignore: config.ignore ?? [],
+    sink: (trace) => buffer?.add(trace)
+  });
+  installHttpServer();
+  installHttpClient();
+  installPg();
+  registerShutdown();
+}
+var shutdownRegistered = false;
+function registerShutdown() {
+  if (shutdownRegistered) return;
+  shutdownRegistered = true;
+  const stop = () => {
+    void buffer?.shutdown();
+  };
+  process.once("beforeExit", stop);
+  process.once("SIGTERM", stop);
+  process.once("SIGINT", stop);
+}
+async function span(name, fn) {
+  return await runInSpan(name, "custom", fn);
+}
+function setTag(key, value) {
+  const store = getStore();
+  if (store) store.trace.tags[key] = String(value);
+}
+function log(message) {
+  const store = getStore();
+  if (store?.parent) {
+    store.parent.events.push({ timestamp: Date.now(), message });
+  }
+}
+async function flush() {
+  await buffer?.flush();
+}
+function getConfig() {
+  return activeConfig;
+}
+var index_default = { init, span, setTag, log, flush, getConfig };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  flush,
+  getConfig,
+  init,
+  log,
+  setTag,
+  span
+});
+//# sourceMappingURL=index.cjs.map