@monocle.sh/adonisjs-agent 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -85,7 +85,7 @@ import { defineConfig } from '@monocle.sh/adonisjs-agent'
 import env from '#start/env'
 
 export default defineConfig({
-  // Required: Your Monocle API key
+  // Optional: Your Monocle API key
   apiKey: env.get('MONOCLE_API_KEY'),
 
   // Optional: Custom ingestion endpoint (for development)
@@ -123,7 +123,7 @@ export default defineConfig({
 
 | Variable          | Description                                            | Required |
 | ----------------- | ------------------------------------------------------ | -------- |
-| `MONOCLE_API_KEY` | Your Monocle API key                                   | Yes      |
+| `MONOCLE_API_KEY` | Your Monocle API key                                   | No       |
 | `APP_NAME`        | Service name for identification                        | Yes      |
 | `APP_VERSION`     | Service version (e.g., git sha, semver)                | Yes      |
 | `APP_ENV`         | Environment: `development`, `staging`, or `production` | Yes      |

package/dist/configure.mjs

@@ -53,7 +53,7 @@ async function configure(command) {
 		APP_NAME: "Env.schema.string()",
 		APP_VERSION: "Env.schema.string()",
 		APP_ENV: `Env.schema.enum(['development', 'staging', 'production'] as const)`,
-		MONOCLE_API_KEY: "Env.schema.string()"
+		MONOCLE_API_KEY: "Env.schema.string.optional()"
 	} });
 }
 

package/dist/init.mjs

@@ -69,9 +69,7 @@ async function init(dirname$1) {
 	const manager = OtelManager.create(configWithProcessors);
 	manager?.start();
 	const shutdown = async () => {
-		await manager?.shutdown().catch(() => {
-			console.error("Error during OTEL shutdown");
-		});
+		await manager?.shutdown().catch(() => {});
 	};
 	process.on("beforeExit", shutdown);
 	process.on("SIGINT", async () => {

package/dist/monocle_provider.mjs

@@ -1,5 +1,6 @@
-import { SpanStatusCode } from "@opentelemetry/api";
+import { recordExceptionWithContext } from "./src/context_lines.mjs";
 import { getCurrentSpan } from "@adonisjs/otel/helpers";
+import is from "@sindresorhus/is";
 import OtelMiddleware from "@adonisjs/otel/otel_middleware";
 import { OtelManager } from "@adonisjs/otel";
 import { ExceptionHandler } from "@adonisjs/core/http";
@@ -15,6 +16,15 @@ var OtelProvider = class {
 		this.app = app;
 	}
 	/**
+	* Convert any error to an HttpError-like object
+	*/
+	#toHttpError(error) {
+		const httpError = is.object(error) ? error : new Error(String(error));
+		if (!httpError.message) httpError.message = "Internal server error";
+		if (!httpError.status) httpError.status = 500;
+		return httpError;
+	}
+	/**
 	* Hook into ExceptionHandler to record exceptions in spans.
 	*
 	* We always record the exception on the span (for trace visibility), but we also
@@ -26,17 +36,17 @@ var OtelProvider = class {
 	*/
 	#registerExceptionHandler() {
 		const originalReport = ExceptionHandler.prototype.report;
+		const toHttpError = this.#toHttpError;
 		ExceptionHandler.macro("report", async function(error, ctx) {
 			const span = getCurrentSpan();
-			if (span && error instanceof Error) {
-				span.recordException(error);
-				span.setStatus({
-					code: SpanStatusCode.ERROR,
-					message: error.message
-				});
-				const httpError = this.toHttpError(error);
+			if (span) {
+				const httpError = toHttpError(error);
 				const shouldReport = this.shouldReport(httpError);
-				span.setAttribute("monocle.exception.should_report", shouldReport);
+				await recordExceptionWithContext({
+					span,
+					error: is.error(error) ? error : new Error(String(error)),
+					shouldReport
+				});
 			}
 			return originalReport.call(this, error, ctx);
 		});

package/dist/src/cli_instrumentation.mjs

@@ -1,5 +1,6 @@
+import { recordExceptionWithContext } from "./context_lines.mjs";
 import { createRequire } from "node:module";
-import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { SpanKind, context, trace } from "@opentelemetry/api";
 
 //#region src/cli_instrumentation.ts
 /**
@@ -71,13 +72,10 @@ async function instrumentCliCommands(config, appRoot) {
 			try {
 				return await originalExec.call(this);
 			} catch (error) {
-				if (error instanceof Error) {
-					span.recordException(error);
-					span.setStatus({
-						code: SpanStatusCode.ERROR,
-						message: error.message
-					});
-				}
+				if (error instanceof Error) await recordExceptionWithContext({
+					span,
+					error
+				});
 				throw error;
 			} finally {
 				span.end();

package/dist/src/context_lines.mjs

@@ -0,0 +1,294 @@
+import { MAX_CAUSE_DEPTH, buildCauseChain, getErrorCause, isErrorLike, stackWithCauses } from "./error_serializer.mjs";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { createInterface } from "node:readline";
+import { createReadStream } from "node:fs";
+import { parseStack } from "error-stack-parser-es/lite";
+
+//#region src/context_lines.ts
+const DEFAULT_CONTEXT_LINES = 7;
+const MAX_LINENO = 1e4;
+const MAX_COLNO = 1e3;
+const MAX_LINE_LENGTH = 200;
+const FILE_CACHE_SIZE = 10;
+const FAILED_CACHE_SIZE = 20;
+/**
+* Simple LRU cache implementation.
+*/
+var LRUCache = class {
+	#maxSize;
+	#cache = /* @__PURE__ */ new Map();
+	constructor(maxSize) {
+		this.#maxSize = maxSize;
+	}
+	get(key) {
+		const value = this.#cache.get(key);
+		if (value === void 0) return void 0;
+		this.#cache.delete(key);
+		this.#cache.set(key, value);
+		return value;
+	}
+	set(key, value) {
+		this.#cache.delete(key);
+		if (this.#cache.size >= this.#maxSize) {
+			const oldestKey = this.#cache.keys().next().value;
+			if (oldestKey !== void 0) this.#cache.delete(oldestKey);
+		}
+		this.#cache.set(key, value);
+	}
+	has(key) {
+		return this.#cache.has(key);
+	}
+	clear() {
+		this.#cache.clear();
+	}
+};
+const fileCache = new LRUCache(FILE_CACHE_SIZE);
+const failedCache = new LRUCache(FAILED_CACHE_SIZE);
+/**
+* Normalize file path by stripping file:// protocol.
+*/
+function normalizeFilePath(path) {
+	if (path.startsWith("file://")) return path.slice(7);
+	return path;
+}
+/**
+* Check if a file should be skipped for context extraction.
+*/
+function shouldSkipFile(path) {
+	if (path.startsWith("node:")) return true;
+	if (path.startsWith("data:")) return true;
+	if (path.endsWith(".min.js")) return true;
+	if (path.endsWith(".min.cjs")) return true;
+	if (path.endsWith(".min.mjs")) return true;
+	if (path.includes("/node_modules/")) return true;
+	return false;
+}
+/**
+* Check if a frame should be skipped based on line/column numbers.
+*/
+function shouldSkipFrame(frame) {
+	if (frame.line === void 0) return true;
+	if (frame.line > MAX_LINENO) return true;
+	if (frame.col !== void 0 && frame.col > MAX_COLNO) return true;
+	return false;
+}
+/**
+* Check if a frame is from the application code (not node_modules).
+*/
+function isInApp(filename) {
+	return !filename.includes("/node_modules/");
+}
+/**
+* Truncate long lines to prevent huge payloads.
+*/
+function snipLine(line) {
+	if (line.length <= MAX_LINE_LENGTH) return line;
+	return line.slice(0, MAX_LINE_LENGTH) + "...";
+}
+/**
+* Create context range around a line number.
+*/
+function makeContextRange(lineno, contextLines) {
+	return [Math.max(1, lineno - contextLines), lineno + contextLines];
+}
+/**
+* Merge overlapping line ranges for efficient file reading.
+*/
+function mergeRanges(ranges) {
+	if (ranges.length === 0) return [];
+	const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+	const merged = [sorted[0]];
+	for (let i = 1; i < sorted.length; i++) {
+		const current = sorted[i];
+		const last = merged[merged.length - 1];
+		if (current[0] <= last[1] + 1) last[1] = Math.max(last[1], current[1]);
+		else merged.push(current);
+	}
+	return merged;
+}
+/**
+* Read specific line ranges from a file.
+* Follows Sentry's battle-tested patterns for stream handling.
+*/
+async function readFileLines(filepath, ranges) {
+	return new Promise((resolve) => {
+		const output = {};
+		let resolved = false;
+		const stream = createReadStream(filepath);
+		const lineReader = createInterface({ input: stream });
+		function destroyStreamAndResolve() {
+			if (resolved) return;
+			resolved = true;
+			stream.destroy();
+			resolve(output);
+		}
+		if (ranges.length === 0) {
+			destroyStreamAndResolve();
+			return;
+		}
+		let lineNumber = 0;
+		let currentRangeIndex = 0;
+		let rangeStart = ranges[0][0];
+		let rangeEnd = ranges[0][1];
+		function onStreamError() {
+			failedCache.set(filepath, true);
+			lineReader.close();
+			lineReader.removeAllListeners();
+			destroyStreamAndResolve();
+		}
+		stream.on("error", onStreamError);
+		lineReader.on("error", onStreamError);
+		lineReader.on("close", destroyStreamAndResolve);
+		lineReader.on("line", (line) => {
+			try {
+				lineNumber++;
+				if (lineNumber < rangeStart) return;
+				output[lineNumber] = snipLine(line);
+				if (lineNumber >= rangeEnd) {
+					if (currentRangeIndex === ranges.length - 1) {
+						lineReader.close();
+						lineReader.removeAllListeners();
+						return;
+					}
+					currentRangeIndex++;
+					const nextRange = ranges[currentRangeIndex];
+					rangeStart = nextRange[0];
+					rangeEnd = nextRange[1];
+				}
+			} catch {}
+		});
+	});
+}
+/**
+* Extract context lines for a stack trace.
+*/
+async function extractContextLines(stack, contextLines = DEFAULT_CONTEXT_LINES) {
+	const parsedFrames = parseStack(stack);
+	const framesToEnrich = [];
+	for (const frame of parsedFrames) {
+		if (!frame.file || !frame.line) continue;
+		const filepath = normalizeFilePath(frame.file);
+		if (shouldSkipFile(filepath)) continue;
+		if (shouldSkipFrame(frame)) continue;
+		const range = makeContextRange(frame.line, contextLines);
+		framesToEnrich.push({
+			frame,
+			filepath,
+			range
+		});
+	}
+	if (framesToEnrich.length === 0) return [];
+	const fileToRanges = /* @__PURE__ */ new Map();
+	for (const { filepath, range } of framesToEnrich) {
+		const existing = fileToRanges.get(filepath) || [];
+		existing.push(range);
+		fileToRanges.set(filepath, existing);
+	}
+	const readPromises = [];
+	for (const [filepath, ranges] of fileToRanges) {
+		if (failedCache.has(filepath)) continue;
+		const cachedContent = fileCache.get(filepath);
+		const mergedRanges = mergeRanges(ranges);
+		if (cachedContent && mergedRanges.every(([start, end]) => {
+			for (let i = start; i <= end; i++) if (cachedContent[i] === void 0) return false;
+			return true;
+		})) continue;
+		readPromises.push(readFileLines(filepath, mergedRanges).then((lines) => {
+			const existing = fileCache.get(filepath) || {};
+			fileCache.set(filepath, {
+				...existing,
+				...lines
+			});
+		}));
+	}
+	await Promise.all(readPromises).catch(() => {});
+	const enrichedFrames = [];
+	for (const { frame, filepath, range } of framesToEnrich) {
+		const fileContent = fileCache.get(filepath);
+		if (!fileContent) continue;
+		const [rangeStart, rangeEnd] = range;
+		const preContext = [];
+		const postContext = [];
+		for (let i = rangeStart; i < frame.line; i++) {
+			const line = fileContent[i];
+			if (line !== void 0) preContext.push(line);
+		}
+		const contextLine = fileContent[frame.line];
+		if (contextLine === void 0) continue;
+		for (let i = frame.line + 1; i <= rangeEnd; i++) {
+			const line = fileContent[i];
+			if (line !== void 0) postContext.push(line);
+		}
+		enrichedFrames.push({
+			filename: filepath,
+			lineno: frame.line,
+			colno: frame.col,
+			function: frame.function,
+			in_app: isInApp(filepath),
+			pre_context: preContext,
+			context_line: contextLine,
+			post_context: postContext
+		});
+	}
+	return enrichedFrames;
+}
+/**
+* Build a cause chain with context lines for each cause.
+* This extracts context lines from each error's stack trace.
+*/
+async function buildCauseChainWithContext(error, contextLines = DEFAULT_CONTEXT_LINES) {
+	return _buildCauseChainWithContext(error, /* @__PURE__ */ new Set(), 0, contextLines);
+}
+async function _buildCauseChainWithContext(err, seen, depth, contextLines) {
+	if (!isErrorLike(err)) return [];
+	if (depth >= MAX_CAUSE_DEPTH) return [{
+		type: "Error",
+		message: "(max cause depth reached)"
+	}];
+	if (seen.has(err)) return [{
+		type: "Error",
+		message: "(circular reference detected)"
+	}];
+	seen.add(err);
+	let frames;
+	if (err.stack) try {
+		const extracted = await extractContextLines(err.stack, contextLines);
+		if (extracted.length > 0) frames = extracted;
+	} catch {}
+	const current = {
+		type: err.name || "Error",
+		message: err.message || "",
+		stack: err.stack,
+		frames
+	};
+	const cause = getErrorCause(err);
+	if (cause) return [current, ...await _buildCauseChainWithContext(cause, seen, depth + 1, contextLines)];
+	return [current];
+}
+/**
+* Record an exception on a span with context lines.
+* This replaces `span.recordException()` with an enriched version.
+*/
+async function recordExceptionWithContext(options) {
+	const { span, error, shouldReport = true, contextLines = DEFAULT_CONTEXT_LINES } = options;
+	span.setStatus({
+		code: SpanStatusCode.ERROR,
+		message: error.message
+	});
+	span.setAttribute("monocle.exception.should_report", shouldReport);
+	const causeChain = shouldReport ? await buildCauseChainWithContext(error, contextLines) : buildCauseChain(error);
+	const hasCauses = causeChain.length > 1;
+	const attributes = {
+		"exception.type": error.name,
+		"exception.message": error.message,
+		"exception.stacktrace": hasCauses ? stackWithCauses(error) : error.stack || ""
+	};
+	const actualCauses = causeChain.slice(1);
+	if (actualCauses.length > 0) attributes["monocle.exception.cause_chain"] = JSON.stringify(actualCauses);
+	const mainFrames = causeChain[0]?.frames;
+	if (mainFrames && mainFrames.length > 0) attributes["monocle.exception.frames"] = JSON.stringify(mainFrames);
+	span.addEvent("exception", attributes);
+}
+
+//#endregion
+export { recordExceptionWithContext };

package/dist/src/error_serializer.mjs

@@ -0,0 +1,77 @@
+//#region src/error_serializer.ts
+/**
+* Maximum number of causes to capture (prevents infinite loops).
+*/
+const MAX_CAUSE_DEPTH = 5;
+/**
+* Check if a value is error-like (has a message property).
+*/
+function isErrorLike(err) {
+	return err != null && typeof err.message === "string";
+}
+/**
+* Safely extract the cause from an error.
+* Handles both standard Error.cause and VError-style cause() functions.
+*/
+function getErrorCause(err) {
+	if (!err) return void 0;
+	const cause = err.cause;
+	if (typeof cause === "function") {
+		const causeResult = cause();
+		return isErrorLike(causeResult) ? causeResult : void 0;
+	}
+	return isErrorLike(cause) ? cause : void 0;
+}
+/**
+* Build a combined stack trace from an error and all its causes.
+* Format:
+*   Error: Top-level message
+*       at file.js:10:5
+*   caused by: Error: Mid-level message
+*       at file.js:20:3
+*/
+function stackWithCauses(err) {
+	return _stackWithCauses(err, /* @__PURE__ */ new Set());
+}
+function _stackWithCauses(err, seen) {
+	if (!isErrorLike(err)) return "";
+	const stack = err.stack || "";
+	if (seen.has(err)) return stack + "\ncauses have become circular...";
+	const cause = getErrorCause(err);
+	if (cause) {
+		seen.add(err);
+		return stack + "\ncaused by: " + _stackWithCauses(cause, seen);
+	}
+	return stack;
+}
+/**
+* Build a structured cause chain from an error.
+* Returns an array of { type, message, stack } objects.
+* Limited to MAX_CAUSE_DEPTH to prevent infinite loops.
+*/
+function buildCauseChain(err) {
+	return _buildCauseChain(err, /* @__PURE__ */ new Set(), 0);
+}
+function _buildCauseChain(err, seen, depth) {
+	if (!isErrorLike(err)) return [];
+	if (depth >= MAX_CAUSE_DEPTH) return [{
+		type: "Error",
+		message: "(max cause depth reached)"
+	}];
+	if (seen.has(err)) return [{
+		type: "Error",
+		message: "(circular reference detected)"
+	}];
+	seen.add(err);
+	const current = {
+		type: err.name || "Error",
+		message: err.message || "",
+		stack: err.stack
+	};
+	const cause = getErrorCause(err);
+	if (cause) return [current, ..._buildCauseChain(cause, seen, depth + 1)];
+	return [current];
+}
+
+//#endregion
+export { MAX_CAUSE_DEPTH, buildCauseChain, getErrorCause, isErrorLike, stackWithCauses };

package/dist/src/monocle.d.mts

@@ -17,8 +17,11 @@ declare class Monocle {
   /**
    * Capture an exception and record it on the current active span.
    * If no span is active, the exception is silently ignored.
+   *
+   * This method is async to allow for source context extraction.
+   * You can choose to await it or fire-and-forget.
    */
-  static captureException(error: unknown, context?: CaptureExceptionContext): void;
+  static captureException(error: unknown, context?: CaptureExceptionContext): Promise<void>;
   /**
    * Set user information on the current active span.
    */

package/dist/src/monocle.mjs

@@ -1,4 +1,5 @@
-import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { recordExceptionWithContext } from "./context_lines.mjs";
+import { trace } from "@opentelemetry/api";
 import { setUser } from "@adonisjs/otel/helpers";
 
 //#region src/monocle.ts
@@ -9,15 +10,16 @@ var Monocle = class {
 	/**
 	* Capture an exception and record it on the current active span.
 	* If no span is active, the exception is silently ignored.
+	*
+	* This method is async to allow for source context extraction.
+	* You can choose to await it or fire-and-forget.
 	*/
-	static captureException(error, context$1) {
+	static async captureException(error, context$1) {
 		const span = trace.getActiveSpan();
 		if (!span) return;
-		const err = error instanceof Error ? error : new Error(String(error));
-		span.recordException(err);
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: err.message
+		await recordExceptionWithContext({
+			span,
+			error: error instanceof Error ? error : new Error(String(error))
 		});
 		if (context$1?.user) {
 			if (context$1.user.id) span.setAttribute("user.id", context$1.user.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/adonisjs-agent",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",
@@ -52,7 +52,9 @@
     "build": "tsdown",
     "dev": "tsdown",
     "typecheck": "tsc --noEmit",
-    "release": "release-it",
+    "test": "node --import tsx bin/test.ts",
+    "quick:test": "node --import tsx bin/test.ts",
+    "release": "release-it --preRelease=beta",
     "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
@@ -65,12 +67,19 @@
     "@opentelemetry/sdk-metrics": "^2.2.0",
     "@opentelemetry/sdk-trace-base": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
+    "@sindresorhus/is": "^7.2.0",
+    "error-stack-parser-es": "^1.0.5",
     "import-in-the-middle": "^2.0.1"
   },
   "devDependencies": {
     "@adonisjs/core": "catalog:",
     "@adonisjs/tsconfig": "catalog:",
-    "release-it": "^19.2.2"
+    "@japa/assert": "^4.2.0",
+    "@japa/file-system": "^2.3.2",
+    "@japa/runner": "^4.4.0",
+    "@japa/snapshot": "^2.0.10",
+    "release-it": "^19.2.2",
+    "tsx": "^4.19.4"
   },
   "peerDependencies": {
     "@adonisjs/core": "^6.2.0 || ^7.0.0"