@orbitai/orbitrace 1.1.9 → 1.1.11

package/README.md

@@ -1,6 +1,8 @@
 # @orbitai/orbitrace
 
-Error tracking and monitoring for Node.js and browser applications.
+Error tracking and monitoring for backend Node.js applications.
+
+Orbitrace is server-side only. Do not initialize this package in browser or frontend code, because the Orbitrace API key is a backend secret and must not be exposed in public bundles.
 
 ## Installation
 
@@ -17,8 +19,6 @@ npm install @orbitai/orbitrace
 const Orbitrace = require("@orbitai/orbitrace");
 
 function getOrbitraceInstance({ service }) {
-	console.log("Initializing Orbitrace for service:", service);
-
 	Orbitrace.getInstance({
 		apiKey: process.env.ORBITRACE_API_KEY,
 		orgId: process.env.ORBITRACE_ORG_ID,
@@ -27,7 +27,7 @@ function getOrbitraceInstance({ service }) {
 		environment: process.env.APP_ENV,
 		service,
 		version: process.env.APP_VERSION,
-		disabled: process.env.APP_ENV !== "production",
+		disabled: process.env.ORBITRACE_DISABLED === "true",
 	});
 
 	return Orbitrace;
@@ -38,165 +38,60 @@ module.exports = {
 };
 ```
 
-### 2. Usage
+### 2. Capture Exceptions
 
 ```javascript
-const { getOrbitraceInstance } = require("/path/to/orbitrace");
+const { getOrbitraceInstance } = require("./orbitrace");
 const orbitrace = getOrbitraceInstance({ service: "api" });
 
-// Capture exceptions
 try {
 	// Your code here
 } catch (error) {
 	await orbitrace.captureException(error, {
 		endpoint: "/users",
+		action: "createUser",
 	});
 }
-
-// Capture messages
-await orbitrace.captureMessage("User registered", {
-	userId: "123",
-	email: "user@example.com",
-});
-```
-
-## Frontend Setup (Vue 3 + Pinia)
-
-### 1. Initialize Orbitrace
-
-```javascript
-// orbitrace.js
-import { provide, inject } from "vue";
-import Orbitrace from "@orbitai/orbitrace";
-
-export const ORBITRACE_KEY = Symbol("orbitrace");
-
-export function getOrbitraceInstance({ service }) {
-	Orbitrace.getInstance({
-		apiKey: import.meta.env.VITE_ORBITRACE_API_KEY,
-		orgId: import.meta.env.VITE_ORBITRACE_ORG_ID,
-		projectId: import.meta.env.VITE_ORBITRACE_PROJECT_ID,
-		endpoint: import.meta.env.VITE_ORBITRACE_ENDPOINT,
-		environment: import.meta.env.VITE_APP_ENV,
-		service,
-		version: import.meta.env.VITE_APP_VERSION,
-		disabled: process.env.APP_ENV !== "production",
-	});
-
-	return orbitrace;
-}
-
-export function useOrbitrace() {
-	const orbitrace = inject(ORBITRACE_KEY);
-	if (!orbitrace) {
-		throw new Error("Orbitrace not properly initialized");
-	}
-	return orbitrace;
-}
 ```
 
-### 2. Setup in Main App
+### 3. Capture Messages
 
 ```javascript
-// main.js
-import { createApp } from "vue";
-import { createPinia } from "pinia";
-import App from "./App.vue";
-import { getOrbitraceInstance, ORBITRACE_KEY } from "/path/to/orbitrace";
-
-const app = createApp(App);
-const pinia = createPinia();
-
-// Initialize Orbitrace
-const orbitrace = getOrbitraceInstance({ service: "webapp" });
-
-// Make Orbitrace available everywhere
-app.provide(ORBITRACE_KEY, orbitrace);
-
-// Add Orbitrace to Pinia
-pinia.use(({ store }) => {
-	store.orbitrace = orbitrace;
+await orbitrace.captureMessage("User registered", {
+	userId: "123",
+	email: "user@example.com",
 });
-
-app.use(pinia);
-app.mount("#app");
 ```
 
-### 3. Usage in Vue Components
+### 4. Delivery Behavior
 
-```vue
-<script setup>
-import { useOrbitrace } from "/path/to/orbitrace";
+Orbitrace never throws and never blocks your application for long:
 
-const orbitrace = useOrbitrace();
+- 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.
 
-async function handleUserAction() {
-	try {
-		// Your code here
-	} catch (error) {
-		await orbitrace.captureException(error, {
-			component: "UserProfile",
-			action: "updateProfile",
-		});
-	}
-}
-
-// Log custom events
-async function trackEvent() {
-	await orbitrace.captureMessage("User completed onboarding", {
-		userId: "user123",
-		completedSteps: ["profile", "preferences"],
-	});
-}
-</script>
-```
-
-### 4. Usage in Pinia Stores
+In short-lived processes (scripts, CI jobs, serverless functions), call `flush()` before exiting so locally counted repeats are sent:
 
 ```javascript
-// stores/userStore.js
-import { defineStore } from "pinia";
-
-export const useUserStore = defineStore("user", {
-	state: () => ({
-		user: null,
-	}),
-	actions: {
-		async fetchUser() {
-			try {
-				// Fetch user logic
-			} catch (error) {
-				await this.orbitrace.captureException(error, {
-					store: "userStore",
-					action: "fetchUser",
-				});
-				throw error;
-			}
-		},
-	},
-});
+await orbitrace.flush();
 ```
 
-### Environment Variables
-
-For Vite:
+## Environment Variables
 
 ```env
-VITE_ORBITRACE_API_KEY=your-api-key
-VITE_ORBITRACE_ORG_ID=your-org-id
-VITE_ORBITRACE_PROJECT_ID=your-project-id
-VITE_ORBITRACE_ENDPOINT=your-endpoint
-VITE_APP_ENV=your-environment
-VITE_APP_VERSION=your-version
-```
-
-For Node.js:
-
-```env
-ORBITRACE_API_KEY=your-api-key
+ORBITRACE_API_KEY=your-backend-api-key
 ORBITRACE_ORG_ID=your-org-id
 ORBITRACE_PROJECT_ID=your-project-id
 ORBITRACE_ENDPOINT=your-endpoint
-APP_ENV=your-environment
-APP_VERSION=your-version
+APP_ENV=production
+APP_VERSION=1.0.0
+ORBITRACE_DISABLED=false
 ```
+
+## Security Model
+
+Orbitrace authenticates ingestion requests with `ORBITRACE_API_KEY`. Keep this key only in backend environments such as servers, workers, functions, and CI jobs. Do not use `VITE_`, `NEXT_PUBLIC_`, or other public frontend environment variables for Orbitrace credentials.
+
+If this package is initialized in a browser runtime, it throws an error before sending events.

package/dist/index.js

@@ -1,7 +1,19 @@
+// 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();
 		this.validateConfig(config);
 
 		this.#config = {
@@ -27,72 +39,104 @@ class Orbitrace {
 		}
 	}
 
-	static checkInitialized() {
-		if (!this.#config) {
+	static assertServerRuntime() {
+		if (typeof window !== "undefined" || typeof document !== "undefined") {
 			throw new Error(
-				"Orbitrace must be initialized with Orbitrace.getInstance() before use"
+				"Orbitrace can only be initialized in backend/server runtimes"
 			);
 		}
 	}
 
-	static isBrowser() {
-		return typeof window !== "undefined" && Boolean(window.location?.origin);
+	static async captureException(error, metadata = {}) {
+		const message = error?.message || error?.name || String(error);
+
+		return this.#capture("capture_exception", {
+			message,
+			stack: error?.stack || message,
+			metadata,
+		});
 	}
 
-	static async captureException(error, metadata = {}) {
-		this.checkInitialized();
+	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);
+
+		if (pending) {
+			pending.count++;
+			return;
+		}
 
-			return this.sendToApi("capture_exception", payload);
-		} catch (err) {
-			console.error("Orbitrace: Error capturing exception", err);
+		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 fetchOptions = {
+			const response = await fetch(this.#config.endpoint, {
 				method: "POST",
 				headers: {
 					"Content-Type": "application/json",
@@ -102,24 +146,27 @@ class Orbitrace {
 				},
 				body: JSON.stringify({
 					event,
+					...(count > 1 && { count }),
 					payload,
 				}),
-			};
-
-			if (this.isBrowser()) {
-				fetchOptions.referrerPolicy = "origin";
+				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;
 			}
 
-			const response = await fetch(this.#config.endpoint, fetchOptions);
-
 			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,7 +1,7 @@
 {
 	"name": "@orbitai/orbitrace",
-	"version": "1.1.9",
-	"description": "Error tracking and monitoring for Node.js and browser applications",
+	"version": "1.1.11",
+	"description": "Error tracking and monitoring for backend Node.js applications",
 	"main": "dist/index.js",
 	"files": [
 		"dist"