@orbitai/orbitrace 1.1.10 → 1.1.12

package/README.md

@@ -59,10 +59,36 @@ try {
 ```javascript
 await orbitrace.captureMessage("User registered", {
 	userId: "123",
-	email: "user@example.com",
 });
 ```
 
+### 4. Delivery Behavior
+
+Orbitrace never throws and never blocks your application for long:
+
+- Each request times out after 5 seconds. Failures are logged to the console and swallowed.
+- Repeats of the same event (same message and stack) within 10 seconds are counted locally and sent as one request with an occurrence count, so an error raised in a loop costs at most two requests per 10 seconds.
+- At most 10 requests are in flight at once; events beyond that are dropped.
+- When the API answers `429`, events are dropped until its `Retry-After` period ends.
+
+In short-lived processes (scripts, CI jobs, serverless functions), call `flush()` before exiting so locally counted repeats are sent:
+
+```javascript
+await orbitrace.flush();
+```
+
+## Data Collected
+
+Each event stores:
+
+- The error message (truncated to 200 characters) and stack trace, or the message text.
+- The `metadata` object you pass, plus `env`, `version` and `service` from your configuration.
+- The IP address and user agent of the server that sent the request, with an approximate location derived from that IP.
+
+Before sending, metadata values whose key contains `password`, `passwd`, `secret`, `token`, `authorization`, `cookie`, `apikey`, `privatekey`, `credential` or `session` (ignoring case, `-` and `_`) are replaced with `[Filtered]`, at any depth. Error messages and stack traces are sent as they are.
+
+Filtering is a safety net, not a guarantee. Do not put personal data (emails, names, addresses) or secrets in metadata or error messages; send stable identifiers such as a user id instead.
+
 ## Environment Variables
 
 ```env

package/dist/index.js

@@ -1,5 +1,67 @@
+// Reporting must never slow down or break the host application, so every failure is logged and swallowed.
+const REQUEST_TIMEOUT_MS = 5000;
+// Repeats of the same event inside this window are counted locally and sent once as a single request.
+const DEDUPE_WINDOW_MS = 10000;
+// Caps concurrent requests so a loop of distinct errors cannot exhaust the host's sockets or memory.
+const MAX_IN_FLIGHT = 10;
+const DEFAULT_RETRY_AFTER_SECONDS = 60;
+// Metadata keys containing any of these (ignoring case, "-" and "_") have their values replaced before sending.
+const SENSITIVE_KEY_PARTS = [
+	"password",
+	"passwd",
+	"secret",
+	"token",
+	"authorization",
+	"cookie",
+	"apikey",
+	"privatekey",
+	"credential",
+	"session",
+];
+const FILTERED_VALUE = "[Filtered]";
+
+function isSensitiveKey(key) {
+	const normalized = key.toLowerCase().replace(/[-_]/g, "");
+	return SENSITIVE_KEY_PARTS.some((part) => normalized.includes(part));
+}
+
+// Recurses only into plain objects and arrays so values like Date keep their JSON form.
+// `ancestors` breaks reference cycles, which would otherwise make the request body unserializable.
+function filterSensitive(value, ancestors = new WeakSet()) {
+	if (value === null || typeof value !== "object") {
+		return value;
+	}
+
+	if (ancestors.has(value)) {
+		return "[Circular]";
+	}
+
+	const isArray = Array.isArray(value);
+	const prototype = Object.getPrototypeOf(value);
+
+	if (!isArray && prototype !== Object.prototype && prototype !== null) {
+		return value;
+	}
+
+	ancestors.add(value);
+	const filtered = isArray
+		? value.map((item) => filterSensitive(item, ancestors))
+		: Object.fromEntries(
+				Object.entries(value).map(([key, item]) => [
+					key,
+					isSensitiveKey(key) ? FILTERED_VALUE : filterSensitive(item, ancestors),
+				])
+			);
+	ancestors.delete(value);
+
+	return filtered;
+}
+
 class Orbitrace {
 	static #config = null;
+	static #pending = new Map();
+	static #inFlight = new Set();
+	static #pausedUntil = 0;
 
 	static getInstance(config) {
 		this.assertServerRuntime();
@@ -28,14 +90,6 @@ class Orbitrace {
 		}
 	}
 
-	static checkInitialized() {
-		if (!this.#config) {
-			throw new Error(
-				"Orbitrace must be initialized with Orbitrace.getInstance() before use"
-			);
-		}
-	}
-
 	static assertServerRuntime() {
 		if (typeof window !== "undefined" || typeof document !== "undefined") {
 			throw new Error(
@@ -45,57 +99,93 @@ class Orbitrace {
 	}
 
 	static async captureException(error, metadata = {}) {
-		this.checkInitialized();
+		const message = error?.message || error?.name || String(error);
+
+		return this.#capture("capture_exception", {
+			message,
+			stack: error?.stack || message,
+			metadata,
+		});
+	}
+
+	static async captureMessage(message, metadata = {}) {
+		return this.#capture("capture_message", { message, metadata });
+	}
+
+	// Sends counts still held by the dedupe window and waits for in-flight requests.
+	// Call it before a short-lived process or serverless invocation ends.
+	static async flush() {
+		await Promise.all([...this.#pending.keys()].map((key) => this.#flushPending(key)));
+		await Promise.all(this.#inFlight);
+	}
+
+	static async #capture(event, { metadata, ...fields }) {
+		if (!this.#config) {
+			console.error("Orbitrace: call Orbitrace.getInstance() before capturing events");
+			return;
+		}
 
 		if (this.#config.disabled) {
 			console.log("Orbitrace: Logging is disabled");
 			return;
 		}
 
-		try {
-			const payload = {
-				message: error.message,
-				stack: error.stack,
-				metadata: {
-					...metadata,
-					env: this.#config.environment,
-					version: this.#config.version,
-					service: this.#config.service,
-				},
-			};
+		const payload = {
+			...fields,
+			metadata: {
+				...filterSensitive(metadata),
+				env: this.#config.environment,
+				version: this.#config.version,
+				service: this.#config.service,
+			},
+		};
+		const key = JSON.stringify([event, payload.message, payload.stack ?? null]);
+		const pending = this.#pending.get(key);
 
-			return this.sendToApi("capture_exception", payload);
-		} catch (err) {
-			console.error("Orbitrace: Error capturing exception", err);
+		if (pending) {
+			pending.count++;
+			return;
+		}
+
+		if (!this.#canSend()) {
+			return;
 		}
+
+		const entry = { event, payload, count: 0 };
+		entry.timer = setTimeout(() => this.#flushPending(key), DEDUPE_WINDOW_MS);
+		entry.timer.unref?.();
+		this.#pending.set(key, entry);
+
+		return this.#send(event, payload, 1);
 	}
 
-	static async captureMessage(message, metadata = {}) {
-		this.checkInitialized();
+	static async #flushPending(key) {
+		const entry = this.#pending.get(key);
 
-		if (this.#config.disabled) {
-			console.log("Orbitrace: Logging is disabled");
+		if (!entry) {
 			return;
 		}
 
-		try {
-			const payload = {
-				message,
-				metadata: {
-					...metadata,
-					env: this.#config.environment,
-					version: this.#config.version,
-					service: this.#config.service,
-				},
-			};
+		this.#pending.delete(key);
+		clearTimeout(entry.timer);
 
-			return this.sendToApi("capture_message", payload);
-		} catch (err) {
-			console.error("Orbitrace: Error capturing message", err);
+		if (entry.count > 0 && this.#canSend()) {
+			await this.#send(entry.event, entry.payload, entry.count);
 		}
 	}
 
-	static async sendToApi(event, payload) {
+	static #canSend() {
+		return Date.now() >= this.#pausedUntil && this.#inFlight.size < MAX_IN_FLIGHT;
+	}
+
+	static #send(event, payload, count) {
+		const request = this.#post(event, payload, count).finally(() => this.#inFlight.delete(request));
+		this.#inFlight.add(request);
+
+		return request;
+	}
+
+	static async #post(event, payload, count) {
 		try {
 			const response = await fetch(this.#config.endpoint, {
 				method: "POST",
@@ -107,18 +197,27 @@ class Orbitrace {
 				},
 				body: JSON.stringify({
 					event,
+					...(count > 1 && { count }),
 					payload,
 				}),
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
 			});
 
+			if (response.status === 429) {
+				const retryAfterSeconds = Number(response.headers.get("retry-after")) || DEFAULT_RETRY_AFTER_SECONDS;
+				this.#pausedUntil = Date.now() + retryAfterSeconds * 1000;
+				console.warn(`Orbitrace: rate limited, dropping events for ${retryAfterSeconds}s`);
+				return;
+			}
+
 			if (!response.ok) {
-				throw new Error(`HTTP error! status: ${response.status}`);
+				console.error(`Orbitrace: API responded with status ${response.status}`);
+				return;
 			}
 
 			return await response.json();
 		} catch (error) {
-			console.error("Orbitrace: Error sending data to API", error);
-			throw error;
+			console.error("Orbitrace: Error sending data to API", error.message);
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orbitai/orbitrace",
-	"version": "1.1.10",
+	"version": "1.1.12",
 	"description": "Error tracking and monitoring for backend Node.js applications",
 	"main": "dist/index.js",
 	"files": [