@orbitai/orbitrace 1.2.1 → 1.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @orbitai/orbitrace
 
-Error tracking and monitoring for backend Node.js applications.
+Error tracking and monitoring for Node.js services and browser apps.
 
-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.
+The package has two entries. `@orbitai/orbitrace` runs on servers with the project's API key, which is a secret. `@orbitai/orbitrace/browser` runs in browsers with the project's public key, which is accepted only from the origins allowed in the Orbitrace dashboard. Never put the API key in a browser bundle; the server entry throws if it is loaded in a browser.
 
 ## Installation
 
@@ -131,6 +131,56 @@ exports.checkout = onRequest(orbitrace.wrap(async (req, res) => {
 }));
 ```
 
+## Browser Setup
+
+Install the same package and import the browser entry. It needs a browser with `fetch`, so every current browser.
+
+```javascript
+import Orbitrace from "@orbitai/orbitrace/browser";
+
+Orbitrace.init({
+	publicKey: "the project's public key",
+	orgId: "your-org-id",
+	projectId: "your-project-id",
+	endpoint: "your-endpoint",
+	environment: import.meta.env.MODE,
+	version: "1.0.0",
+	service: "webapp",
+});
+```
+
+The public key can be read by anyone who opens your site. That is fine: it only creates events, the API accepts it only from the origins allowed for the project (dashboard, Documentation, Browser apps), and the project's rate limit and your organization's quota bound what it can do. `init` throws if it is given an `apiKey`.
+
+Automatic capture is on unless `autoCapture: false`. Uncaught errors and unhandled promise rejections are reported; breadcrumbs are recorded from `console` calls, `fetch` requests, clicks (the element, never its text) and navigation. Switch parts off with `autoCapture: { console: false, clicks: false }`; the parts are `exceptions`, `console`, `fetch`, `clicks` and `navigation`.
+
+`captureException`, `captureMessage`, `addBreadcrumb`, `flush` and `close` work as on servers. There are no scopes: one tab is one scope.
+
+```javascript
+// After sign-in, so issues show who was affected. Send a stable id, never personal data.
+Orbitrace.setUser({ id: user.uid });
+// On sign-out:
+Orbitrace.setUser(null);
+
+// Vue 3: errors Vue catches inside components are reported with the component name,
+// then passed to the app's own errorHandler, or logged as Vue would.
+app.use(Orbitrace.vue);
+```
+
+Every browser event carries `page`: the URL (without query string or fragment), referrer, viewport and language. Requests use `keepalive`, so an error reported just before the page closes still arrives. Production stacks are minified; issues still group correctly across deploys because file hashes and line numbers are ignored, so keep `version` set to your release to see which build introduced a problem.
+
+## Source Maps
+
+Production bundles are minified, so browser stacks name files like `index-39fc6623.js` and functions like `Xr`. Upload the build's source maps and Orbitrace resolves each event of that release to the original file, line and function, groups issues by them, and shows a few lines of source around each frame. Maps are stored privately, never served to browsers, and deleted after 90 days.
+
+Build with hidden source maps (Vite: `build.sourcemap = "hidden"`), then run the command the package installs, from a build or deploy job that has the server API key:
+
+```bash
+ORBITRACE_API_KEY=... ORBITRACE_ORG_ID=... ORBITRACE_PROJECT_ID=... ORBITRACE_ENDPOINT=... \
+  npx orbitrace-sourcemaps upload --release 1.22.9 --dir dist --delete
+```
+
+`--release` must equal the `version` the browser SDK sends. `--dir` is searched for `.map` files. `--delete` removes them afterwards so a hosting deploy of the same directory cannot publish them. Upload before the bundle goes live: events that arrive before their release's maps keep the minified stack.
+
 ## Data Collected
 
 Each event stores:
@@ -138,7 +188,7 @@ 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.
 - Breadcrumbs, when there are any: the last 30 recorded before the event.
-- The IP address and user agent of the server that sent the request, with an approximate location derived from that IP.
+- The IP address and user agent of the server that sent the request, with an approximate location derived from that IP. For browser events, the user agent and approximate location of the user; their IP address is not stored.
 
 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.
 
@@ -158,6 +208,6 @@ 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.
+Each project has two keys. The API key authenticates servers: keep it only in backend environments such as servers, workers, functions, and CI jobs, and never in `VITE_`, `NEXT_PUBLIC_` or other public frontend environment variables. The public key authenticates browsers: it may ship in bundles, and the API accepts it only from the project's allowed origins. Both keys can only create events.
 
-If this package is initialized in a browser runtime, it throws an error before sending events.
+The server entry throws if it is initialized in a browser, and the browser entry throws if it is given an API key.

package/bin/orbitrace-sourcemaps.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Uploads a build's source maps to Orbitrace so browser stacks of that release resolve to original files.
+//
+//   orbitrace-sourcemaps upload --release 1.22.9 --dir dist [--delete]
+//
+// Reads ORBITRACE_API_KEY, ORBITRACE_ORG_ID, ORBITRACE_PROJECT_ID and ORBITRACE_ENDPOINT from the
+// environment (--org, --project and --endpoint override the last three). The API key is the project's
+// secret server key, never the public key. --delete removes the maps from the directory afterwards, so a
+// hosting deploy of that directory cannot publish them.
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+async function findMaps(dir) {
+	const found = [];
+
+	for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+
+		if (entry.isDirectory()) {
+			found.push(...(await findMaps(full)));
+		} else if (entry.isFile() && entry.name.endsWith(".map")) {
+			found.push(full);
+		}
+	}
+
+	return found;
+}
+
+const FLAGS = new Set(["delete"]);
+
+function parseArgs(argv) {
+	const options = { _: [] };
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+
+		if (arg.startsWith("--")) {
+			const [name, inline] = arg.slice(2).split("=");
+			const next = argv[i + 1];
+
+			if (FLAGS.has(name)) {
+				options[name] = true;
+			} else if (inline !== undefined) {
+				options[name] = inline;
+			} else if (next !== undefined && !next.startsWith("--")) {
+				options[name] = next;
+				i++;
+			} else {
+				options[name] = true;
+			}
+		} else {
+			options._.push(arg);
+		}
+	}
+
+	return options;
+}
+
+async function request(url, { apiKey, orgId, projectId }, body) {
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"x-orbitrace-api-key": apiKey,
+			"x-orbitrace-org-id": orgId,
+			"x-orbitrace-project-id": projectId,
+		},
+		body: JSON.stringify(body),
+	});
+	const text = await response.text();
+	let json;
+
+	try {
+		json = JSON.parse(text);
+	} catch {
+		json = { error: text };
+	}
+
+	if (!response.ok) {
+		throw new Error(`${url} answered ${response.status}: ${json.error || json.message || text}`);
+	}
+
+	return json;
+}
+
+async function upload({ release, dir, apiKey, orgId, projectId, endpoint, remove = false, log = console.log }) {
+	for (const [name, value] of Object.entries({ release, dir, apiKey, orgId, projectId, endpoint })) {
+		if (!value) {
+			throw new Error(`Missing ${name}`);
+		}
+	}
+
+	// The configured endpoint is the events URL (".../log"); the source map routes live next to it.
+	const base = String(endpoint).replace(/\/log\/?$/, "");
+	const credentials = { apiKey, orgId, projectId };
+	const paths = await findMaps(dir);
+
+	if (paths.length === 0) {
+		throw new Error(`No .map files found under ${dir}. Build with source maps enabled (Vite: build.sourcemap = "hidden").`);
+	}
+
+	const files = await Promise.all(
+		paths.map(async (file) => ({ path: file, name: path.basename(file), size: (await fs.stat(file)).size })),
+	);
+	const names = new Set();
+
+	for (const file of files) {
+		if (names.has(file.name)) {
+			throw new Error(`Two source maps are named ${file.name}; names must be unique within a release`);
+		}
+
+		names.add(file.name);
+	}
+
+	const declared = await request(`${base}/sourcemaps/releases`, credentials, {
+		release,
+		files: files.map(({ name, size }) => ({ name, size })),
+	});
+	const uploads = new Map(declared.uploads.map((item) => [item.name, item]));
+
+	for (const file of files) {
+		const target = uploads.get(file.name);
+
+		if (!target) {
+			throw new Error(`The API returned no upload URL for ${file.name}`);
+		}
+
+		// The signed URL only accepts the headers it was signed with.
+		const response = await fetch(target.url, {
+			method: "PUT",
+			headers: target.headers,
+			body: await fs.readFile(file.path),
+		});
+
+		if (!response.ok) {
+			throw new Error(`Uploading ${file.name} failed with status ${response.status}`);
+		}
+
+		log(`Uploaded ${file.name} (${file.size} bytes)`);
+	}
+
+	const completed = await request(`${base}/sourcemaps/releases/complete`, credentials, {
+		release,
+		files: files.map(({ name }) => name),
+	});
+
+	if (remove) {
+		await Promise.all(files.map((file) => fs.unlink(file.path)));
+		log(`Removed ${files.length} source map${files.length === 1 ? "" : "s"} from ${dir}`);
+	}
+
+	log(`Release ${release}: ${completed.files} source maps, ${completed.bytes} bytes`);
+
+	if (completed.deletedReleases?.length > 0) {
+		log(`Dropped older releases: ${completed.deletedReleases.join(", ")}`);
+	}
+
+	return completed;
+}
+
+async function main(argv) {
+	const options = parseArgs(argv);
+	const command = options._[0];
+
+	if (command !== "upload") {
+		console.error("Usage: orbitrace-sourcemaps upload --release <version> --dir <directory> [--delete]");
+		process.exitCode = 1;
+		return;
+	}
+
+	try {
+		await upload({
+			release: options.release,
+			dir: options.dir,
+			apiKey: process.env.ORBITRACE_API_KEY,
+			orgId: options.org || process.env.ORBITRACE_ORG_ID,
+			projectId: options.project || process.env.ORBITRACE_PROJECT_ID,
+			endpoint: options.endpoint || process.env.ORBITRACE_ENDPOINT,
+			remove: options.delete === true,
+		});
+	} catch (error) {
+		console.error(`orbitrace-sourcemaps: ${error.message}`);
+		process.exitCode = 1;
+	}
+}
+
+if (require.main === module) {
+	main(process.argv.slice(2));
+}
+
+module.exports = { upload, parseArgs };