@orbitai/orbitrace 1.1.10 → 1.1.11

package/README.md

@@ -63,6 +63,21 @@ await orbitrace.captureMessage("User registered", {
 });
 ```
 
+### 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();
+```
+
 ## Environment Variables
 
 ```env

package/dist/index.js

@@ -1,5 +1,16 @@
+// 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;
+
 class Orbitrace {
 	static #config = null;
+	static #pending = new Map();
+	static #inFlight = new Set();
+	static #pausedUntil = 0;
 
 	static getInstance(config) {
 		this.assertServerRuntime();
@@ -28,14 +39,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 +48,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: {
+				...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 +146,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.11",
 	"description": "Error tracking and monitoring for backend Node.js applications",
 	"main": "dist/index.js",
 	"files": [