@aidenappleby/monitor-js 1.1.0 → 1.2.1

package/dist/index.js

@@ -21,22 +21,91 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Monitor: () => Monitor,
-  attachAxiosMonitor: () => attachAxiosMonitor
+  attachAxiosMonitor: () => attachAxiosMonitor,
+  isValidCorrelationId: () => isValidCorrelationId,
+  newJobId: () => newJobId,
+  newRequestId: () => newRequestId,
+  newTraceId: () => newTraceId
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/ids.ts
+var CORRELATION_ID = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{8,64})$/;
+function isValidCorrelationId(id) {
+  return id === "" || CORRELATION_ID.test(id);
+}
+function randomBytes(n) {
+  const out = new Uint8Array(n);
+  const c = globalThis.crypto;
+  if (c && typeof c.getRandomValues === "function") {
+    c.getRandomValues(out);
+    return out;
+  }
+  for (let i = 0; i < n; i++) out[i] = Math.floor(Math.random() * 256);
+  return out;
+}
+function hex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function newRequestId() {
+  return hex(randomBytes(8));
+}
+function newJobId() {
+  return hex(randomBytes(8));
+}
+function newTraceId() {
+  const b = randomBytes(16);
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const h = hex(b);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
 // src/client.ts
 var DEFAULT_FLUSH_INTERVAL = 2e3;
 var DEFAULT_BATCH_SIZE = 20;
 var MAX_QUEUE_SIZE = 500;
-var Monitor = class {
+var MAX_LINE_BYTES = 1e6;
+var MAX_FIELD_CHARS = 4096;
+var KEEPALIVE_MAX_BYTES = 6e4;
+var BASE_BACKOFF_MS = 1e3;
+var MAX_BACKOFF_MS = 6e4;
+var GROUPING_KEYS = ["error", "error_message", "message", "path", "uri", "method", "reason", "status_code"];
+function classify(status) {
+  if (status >= 200 && status < 400) return "delivered";
+  if (status === 408 || status === 429) return "retryable";
+  if (status === 401 || status === 403 || status === 404 || status === 405) return "misconfigured";
+  if (status >= 400 && status < 500) return "rejected";
+  return "retryable";
+}
+function bisectBudget(n) {
+  let depth = 0;
+  for (let x = n; x > 1; x = Math.ceil(x / 2)) depth++;
+  return 4 * depth + 4;
+}
+var encoder;
+function byteLength(s) {
+  if (typeof TextEncoder === "undefined") return s.length * 3;
+  encoder ??= new TextEncoder();
+  return encoder.encode(s).length;
+}
+function normalizeLevel(level) {
+  const l = (level || "info").toLowerCase();
+  return l === "warning" ? "warn" : l;
+}
+var Monitor = class _Monitor {
   config;
   ignoreErrors = [];
+  onDrop;
   queue = [];
   timer = null;
   userId = "";
-  jobId = "";
+  jobId;
   active = false;
+  backoffUntil = 0;
+  failures = 0;
+  warnedMisconfigured = false;
+  counters = { enqueued: 0, flushed: 0, dropped: 0, quarantined: 0 };
   constructor(config) {
     this.config = {
       service: config.service,
@@ -48,6 +117,8 @@ var Monitor = class {
       debug: config.debug ?? false
     };
     this.ignoreErrors = config.ignoreErrors ?? [];
+    this.onDrop = config.onDrop;
+    this.jobId = newJobId();
     this.start();
     if (config.captureErrors !== false) {
       this.installErrorHandler();
@@ -64,29 +135,47 @@ var Monitor = class {
   clearUser() {
     this.userId = "";
   }
-  /** Set a persistent job ID (session-level identifier) */
+  /**
+   * Set a persistent job ID (session-level identifier). It must be a UUID or
+   * 8-64 hex characters — see `isValidCorrelationId`; anything else is
+   * cleared from each event and kept in data.invalid_job_id.
+   */
   setJobId(jobId) {
     this.jobId = jobId;
   }
   /** Emit an event at a specific level */
   emit(name, level, opts) {
     if (!this.active) return;
+    let data = opts?.data ?? {};
+    const repair = (field, value) => {
+      if (isValidCorrelationId(value)) return value;
+      data = { ...data, [`invalid_${field}`]: value.slice(0, 128) };
+      if (this.config.debug) {
+        console.warn(`[monitor] cleared invalid ${field} ${JSON.stringify(value)} (monitor-core accepts a UUID or 8-64 hex characters)`);
+      }
+      return "";
+    };
+    const jobId = repair("job_id", this.jobId);
+    const requestId = repair("request_id", opts?.requestId ?? "");
+    const traceId = repair("trace_id", opts?.traceId ?? "");
     const event = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       service: this.config.service,
       env: this.config.env,
-      job_id: this.jobId,
-      request_id: opts?.requestId ?? "",
-      trace_id: opts?.traceId ?? "",
+      job_id: jobId,
+      request_id: requestId,
+      trace_id: traceId,
       user_id: opts?.userId ?? this.userId,
-      name,
-      level,
-      data: opts?.data ?? {}
+      name: name || "event.unnamed",
+      level: normalizeLevel(level),
+      data
     };
     if (this.queue.length >= MAX_QUEUE_SIZE) {
       this.queue.shift();
+      this.recordDrop(1);
     }
     this.queue.push(event);
+    this.counters.enqueued++;
     if (this.config.debug) {
       console.debug(`[monitor] ${level} ${name}`, opts?.data);
     }
@@ -114,28 +203,17 @@ var Monitor = class {
   fatal(name, opts) {
     this.emit(name, "fatal", opts);
   }
+  /**
+   * Lifetime counters. Surface them wherever loss would otherwise go
+   * unnoticed: the system that would report dropped telemetry is the one
+   * dropping it.
+   */
+  stats() {
+    return { ...this.counters, queued: this.queue.length };
+  }
   /** Flush all queued events to the ingest endpoint */
   flush() {
-    if (this.queue.length === 0) return;
-    const batch = this.queue.splice(0);
-    const payload = batch.map((e) => JSON.stringify(e)).join("\n");
-    if (typeof fetch === "undefined") return;
-    fetch(this.config.ingestUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/x-ndjson",
-        "X-Api-Key": this.config.apiKey
-      },
-      body: payload,
-      keepalive: true
-    }).catch((err) => {
-      if (this.config.debug) {
-        console.warn("[monitor] flush failed:", err);
-      }
-      if (this.queue.length + batch.length <= MAX_QUEUE_SIZE) {
-        this.queue = batch.concat(this.queue);
-      }
-    });
+    this.flushQueue(false);
   }
   /** Stop the monitor and flush remaining events */
   shutdown() {
@@ -143,14 +221,144 @@ var Monitor = class {
       clearInterval(this.timer);
       this.timer = null;
     }
-    this.flush();
+    this.flushQueue(true);
     this.removeListeners();
     this.active = false;
   }
+  /**
+   * @param unloading the page (or process) is going away: ignore the backoff,
+   * since this is the last chance these events get.
+   */
+  flushQueue(unloading) {
+    if (this.queue.length === 0) return;
+    if (typeof fetch === "undefined") return;
+    if (!unloading && Date.now() < this.backoffUntil) return;
+    const batch = this.queue.splice(0);
+    this.send(batch, { remaining: bisectBudget(batch.length) });
+  }
+  send(events, budget) {
+    const lines = [];
+    const sent = [];
+    for (const e of events) {
+      const line = this.serialize(e);
+      if (line === null) {
+        this.recordDrop(1);
+        continue;
+      }
+      lines.push(line);
+      sent.push(e);
+    }
+    if (lines.length === 0) return;
+    const body = lines.join("\n");
+    let request;
+    try {
+      request = fetch(this.config.ingestUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-ndjson",
+          "X-Api-Key": this.config.apiKey
+        },
+        body,
+        keepalive: byteLength(body) <= KEEPALIVE_MAX_BYTES
+      });
+    } catch (err) {
+      request = Promise.reject(err);
+    }
+    request.then(
+      (res) => this.handleResponse(res, sent, budget),
+      (err) => {
+        if (this.config.debug) {
+          console.warn("[monitor] flush failed:", err);
+        }
+        this.retryLater(sent);
+      }
+    );
+  }
+  handleResponse(res, events, budget) {
+    const status = typeof res?.status === "number" ? res.status : 0;
+    const outcome = res?.ok ? "delivered" : classify(status);
+    switch (outcome) {
+      case "delivered":
+        this.counters.flushed += events.length;
+        this.failures = 0;
+        this.backoffUntil = 0;
+        return;
+      case "rejected":
+        if (events.length > 1 && budget.remaining > 0) {
+          budget.remaining--;
+          const mid = events.length >> 1;
+          this.send(events.slice(0, mid), budget);
+          this.send(events.slice(mid), budget);
+          return;
+        }
+        this.counters.quarantined += events.length;
+        this.recordDrop(events.length);
+        if (this.config.debug) {
+          console.warn(`[monitor] ingest rejected ${events.length} event(s) as malformed (status ${status}):`, events.map((e) => e.name));
+        }
+        return;
+      case "misconfigured":
+        this.recordDrop(events.length);
+        if (!this.warnedMisconfigured) {
+          this.warnedMisconfigured = true;
+          console.warn(`[monitor] ingest refused events with status ${status} \u2014 check ingestUrl and apiKey. Events are being dropped.`);
+        }
+        return;
+      default:
+        this.retryLater(events);
+    }
+  }
+  /** Put events back at the front of the queue and back off before retrying. */
+  retryLater(events) {
+    this.failures++;
+    const ceiling = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** Math.min(this.failures - 1, 16));
+    this.backoffUntil = Date.now() + 50 + Math.random() * ceiling;
+    const room = MAX_QUEUE_SIZE - this.queue.length;
+    const keep = room <= 0 ? [] : events.length > room ? events.slice(events.length - room) : events;
+    this.recordDrop(events.length - keep.length);
+    if (keep.length > 0) {
+      this.queue = keep.concat(this.queue);
+    }
+  }
+  /**
+   * One NDJSON line for e, or null if it cannot be serialized. Never throws:
+   * flush runs inside emit's auto-flush, and emit must never throw into the
+   * caller.
+   */
+  serialize(e) {
+    try {
+      const line = JSON.stringify(e);
+      if (line.length <= MAX_LINE_BYTES / 3) return line;
+      const size = byteLength(line);
+      if (size <= MAX_LINE_BYTES) return line;
+      const kept = { truncated: true, original_size_bytes: size };
+      for (const k of GROUPING_KEYS) {
+        const v = e.data[k];
+        if (typeof v === "string") kept[k] = v.slice(0, MAX_FIELD_CHARS);
+        else if (typeof v === "number" || typeof v === "boolean") kept[k] = v;
+      }
+      const shrunk = JSON.stringify({ ...e, data: kept });
+      return byteLength(shrunk) <= MAX_LINE_BYTES ? shrunk : null;
+    } catch {
+      return null;
+    }
+  }
+  recordDrop(n) {
+    if (n <= 0) return;
+    this.counters.dropped += n;
+    if (this.onDrop) {
+      try {
+        this.onDrop(this.counters.dropped);
+      } catch {
+      }
+    }
+  }
   start() {
     if (this.active) return;
     this.active = true;
-    this.timer = setInterval(() => this.flush(), this.config.flushInterval);
+    const t = setInterval(() => this.flush(), this.config.flushInterval);
+    if (typeof t.unref === "function") t.unref();
+    this.timer = t;
     if (typeof document !== "undefined") {
       document.addEventListener("visibilitychange", this.handleVisibilityChange);
     }
@@ -160,11 +368,11 @@ var Monitor = class {
   }
   handleVisibilityChange = () => {
     if (document.visibilityState === "hidden") {
-      this.flush();
+      this.flushQueue(true);
     }
   };
   handlePageHide = () => {
-    this.flush();
+    this.flushQueue(true);
   };
   shouldIgnoreError(message, stack) {
     if (this.ignoreErrors.length === 0) return false;
@@ -181,6 +389,20 @@ var Monitor = class {
     }
     return false;
   }
+  /**
+   * The route a browser error happened on.
+   *
+   * Deliberately `pathname` only — never the search string or hash. Query
+   * parameters routinely carry tokens, emails and other personal data, and this
+   * value is both stored on the event and folded into the server-side issue
+   * fingerprint, so anything included here is retained and grouped on.
+   *
+   * Returns undefined outside a browser so the Node handlers stay unaffected.
+   */
+  currentPath() {
+    if (typeof window === "undefined" || !window.location) return void 0;
+    return window.location.pathname;
+  }
   errorHandler = (event) => {
     const stack = event.error?.stack;
     if (this.shouldIgnoreError(event.message ?? "", stack)) return;
@@ -190,7 +412,8 @@ var Monitor = class {
         filename: event.filename,
         lineno: event.lineno,
         colno: event.colno,
-        stack
+        stack,
+        path: this.currentPath()
       }
     });
   };
@@ -202,18 +425,90 @@ var Monitor = class {
     this.emit("client.error.unhandled_rejection", "error", {
       data: {
         message,
-        stack
+        stack,
+        path: this.currentPath()
       }
     });
   };
+  // --- Node process handlers ---
+  // Adding an uncaughtException or unhandledRejection listener changes what Node
+  // does. With no listener, either one prints the error and exits with code 1;
+  // with any listener, Node assumes it was handled and keeps running — in
+  // whatever state the failure left it. So when this SDK is the only listener,
+  // it reports the error and then does what Node would have done. When the app
+  // has a listener of its own, the app has already decided; the SDK only reports.
+  /** Grace for the final batch to leave before a Node-style crash exits. */
+  static NODE_CRASH_GRACE_MS = 1500;
+  /** Rejections already reported, so the re-raise below is not reported twice. */
+  reportedRejections = /* @__PURE__ */ new WeakSet();
+  nodeExceptionHandler = (err) => {
+    const alreadyReported = typeof err === "object" && err !== null && this.reportedRejections.has(err);
+    const e = err;
+    const message = e?.message ?? String(err);
+    const stack = e?.stack;
+    if (!alreadyReported && !this.shouldIgnoreError(message, stack)) {
+      this.emit("client.error.uncaught", "error", {
+        data: {
+          message,
+          stack
+        }
+      });
+    }
+    if (this.isSoleListener("uncaughtException")) {
+      this.crashLikeNode(err);
+    }
+  };
+  nodeRejectionHandler = (reason) => {
+    const r = reason;
+    const message = r?.message ?? String(reason);
+    const stack = r?.stack;
+    if (!this.shouldIgnoreError(message, stack)) {
+      this.emit("client.error.unhandled_rejection", "error", {
+        data: {
+          message,
+          stack
+        }
+      });
+    }
+    if (this.isSoleListener("unhandledRejection")) {
+      if (typeof reason === "object" && reason !== null) {
+        this.reportedRejections.add(reason);
+      }
+      this.reraise(reason);
+    }
+  };
+  /** Hand an unhandled rejection back to Node as an uncaught exception. */
+  reraise(reason) {
+    process?.nextTick?.(() => {
+      throw reason;
+    });
+  }
+  /** True when this instance's own handler is the only listener for the event. */
+  isSoleListener(event) {
+    const count = typeof process === "undefined" ? void 0 : process.listenerCount;
+    if (typeof count !== "function") {
+      return false;
+    }
+    return count.call(process, event) <= 1;
+  }
+  /** Print the error as Node would, give the batch a moment to leave, exit 1. */
+  crashLikeNode(err) {
+    console.error(err);
+    this.flush();
+    setTimeout(() => process?.exit?.(1), _Monitor.NODE_CRASH_GRACE_MS);
+  }
   installErrorHandler() {
     if (typeof window !== "undefined") {
       window.addEventListener("error", this.errorHandler);
+    } else if (typeof process !== "undefined" && typeof process.on === "function") {
+      process.on("uncaughtException", this.nodeExceptionHandler);
     }
   }
   installRejectionHandler() {
     if (typeof window !== "undefined") {
       window.addEventListener("unhandledrejection", this.rejectionHandler);
+    } else if (typeof process !== "undefined" && typeof process.on === "function") {
+      process.on("unhandledRejection", this.nodeRejectionHandler);
     }
   }
   removeListeners() {
@@ -225,10 +520,18 @@ var Monitor = class {
     if (typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.handleVisibilityChange);
     }
+    if (typeof process !== "undefined" && typeof process.removeListener === "function") {
+      process.removeListener("uncaughtException", this.nodeExceptionHandler);
+      process.removeListener("unhandledRejection", this.nodeRejectionHandler);
+    }
   }
 };
 
 // src/axios.ts
+function stripQuery(url) {
+  const i = url.search(/[?#]/);
+  return i === -1 ? url : url.slice(0, i);
+}
 function attachAxiosMonitor(axiosInstance, monitor, opts) {
   const minStatus = opts?.minStatus ?? 400;
   const reportSuccess = opts?.reportSuccess ?? false;
@@ -239,7 +542,7 @@ function attachAxiosMonitor(axiosInstance, monitor, opts) {
   });
   axiosInstance.interceptors.response.use(
     (response) => {
-      const url = response.config?.url ?? "";
+      const url = stripQuery(response.config?.url ?? "");
       if (ignorePaths.some((p) => url.includes(p))) return response;
       const statusCode = response.status ?? 0;
       const requestId = response.headers?.["x-request-id"] ?? "";
@@ -274,7 +577,7 @@ function attachAxiosMonitor(axiosInstance, monitor, opts) {
       return response;
     },
     (error) => {
-      const url = error.config?.url ?? "";
+      const url = stripQuery(error.config?.url ?? "");
       if (ignorePaths.some((p) => url.includes(p))) {
         return Promise.reject(error);
       }
@@ -315,6 +618,10 @@ function attachAxiosMonitor(axiosInstance, monitor, opts) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Monitor,
-  attachAxiosMonitor
+  attachAxiosMonitor,
+  isValidCorrelationId,
+  newJobId,
+  newRequestId,
+  newTraceId
 });
 //# sourceMappingURL=index.js.map