@monocle.sh/adonisjs-agent 1.0.0-beta.9 → 1.0.1

package/dist/src/define_config.mjs

@@ -1,4 +1,11 @@
+import { destinations } from "@adonisjs/otel";
 //#region src/define_config.ts
+const DEFAULT_BATCH_CONFIG = {
+	maxExportBatchSize: 512,
+	scheduledDelayMillis: 5e3,
+	exportTimeoutMillis: 3e4,
+	maxQueueSize: 2048
+};
 /**
 * Extracts a header value from either ServerResponse (getHeader) or IncomingMessage (headers object).
 */
@@ -42,15 +49,17 @@ function extractUserResponseHook(httpConfig) {
 }
 /**
 * Define and validate Monocle agent configuration.
-* Sets up environment variables for OTEL exporters to point to Monocle.
 * Returns undefined if no API key is provided (telemetry will be disabled).
 */
 function defineConfig(config) {
 	if (!config.apiKey) return;
 	const endpoint = config.endpoint || "https://ingest.monocle.sh";
 	const environment = config.environment || process.env.NODE_ENV || "development";
-	process.env.OTEL_EXPORTER_OTLP_ENDPOINT = endpoint;
-	process.env.OTEL_EXPORTER_OTLP_HEADERS = `x-api-key=${config.apiKey},x-monocle-env=${environment}`;
+	const compression = config.compression === false ? "none" : "gzip";
+	const batchConfig = {
+		...DEFAULT_BATCH_CONFIG,
+		...config.batch
+	};
 	const httpConfig = config.instrumentations?.["@opentelemetry/instrumentation-http"];
 	const userResponseHook = extractUserResponseHook(httpConfig);
 	const instrumentations = {
@@ -60,13 +69,29 @@ function defineConfig(config) {
 			responseHook: createConnectionTypeHook(userResponseHook)
 		}
 	};
+	const monocleDestination = destinations.otlp({
+		endpoint,
+		signals: "all",
+		compression,
+		headers: {
+			"x-api-key": config.apiKey,
+			"x-monocle-env": environment
+		},
+		maxExportBatchSize: batchConfig.maxExportBatchSize,
+		scheduledDelayMillis: batchConfig.scheduledDelayMillis,
+		exportTimeoutMillis: batchConfig.exportTimeoutMillis,
+		maxQueueSize: batchConfig.maxQueueSize
+	});
 	return {
 		...config,
 		endpoint,
 		environment,
-		instrumentations
+		instrumentations,
+		destinations: {
+			...config.destinations,
+			monocle: monocleDestination
+		}
 	};
 }
-
 //#endregion
-export { defineConfig };
+export { defineConfig };

package/dist/src/exception_reporter.mjs

@@ -1,10 +1,6 @@
-import { buildCauseChain, stackWithCauses } from "./error_serializer.mjs";
-import { buildCauseChainWithContext } from "./context_lines.mjs";
-import { SpanStatusCode } from "@opentelemetry/api";
 import is from "@sindresorhus/is";
-
+import { ExceptionReporter } from "@monocle.sh/otel-utils";
 //#region src/exception_reporter.ts
-const DEFAULT_CONTEXT_LINES = 7;
 /**
 * Convert any unknown error to an HttpError-like object.
 */
@@ -14,39 +10,5 @@ function toHttpError(error) {
 	if (!httpError.status) httpError.status = 500;
 	return httpError;
 }
-/**
-* Reports exceptions to OpenTelemetry spans with context lines and cause chains.
-*/
-var ExceptionReporter = class {
-	/**
-	* Report an exception on the given span.
-	*/
-	async report(options) {
-		const { span, shouldReport, contextLines = DEFAULT_CONTEXT_LINES } = options;
-		const error = toHttpError(options.error);
-		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 attributes = this.#buildAttributes(error, causeChain);
-		span.addEvent("exception", attributes);
-	}
-	#buildAttributes(error, causeChain) {
-		const hasCauses = causeChain.length > 1;
-		const attributes = {
-			"exception.type": error.name || "Error",
-			"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);
-		return attributes;
-	}
-};
-
 //#endregion
-export { ExceptionReporter, toHttpError };
+export { ExceptionReporter, toHttpError };

package/dist/src/host_metrics.mjs

@@ -1,6 +1,5 @@
 import { metrics } from "@opentelemetry/api";
 import { HostMetrics } from "@opentelemetry/host-metrics";
-
 //#region src/host_metrics.ts
 let hostMetricsInstance = null;
 /**
@@ -22,6 +21,5 @@ function startHostMetrics(config = {}) {
 	hostMetricsInstance.start();
 	return hostMetricsInstance;
 }
-
 //#endregion
-export { startHostMetrics };
+export { startHostMetrics };

package/dist/src/instrumentations/cache/instrumentation.mjs

@@ -0,0 +1,53 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { BentoCacheInstrumentation } from "@bentocache/otel";
+//#region src/instrumentations/cache/instrumentation.ts
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const numericPattern = /^\d+$/;
+const hexPattern = /^[0-9a-f]{8,}$/i;
+/**
+* Replaces dynamic-looking segments (UUIDs, numeric IDs, hex hashes)
+* with `*` to reduce cardinality in span attributes.
+*/
+function defaultKeySanitizer(key) {
+	if (!key) return key;
+	return key.split(":").map((segment) => {
+		if (uuidPattern.test(segment)) return "*";
+		if (numericPattern.test(segment)) return "*";
+		if (hexPattern.test(segment)) return "*";
+		return segment;
+	}).join(":");
+}
+/**
+* Auto-instruments @adonisjs/cache (bentocache) with OpenTelemetry spans
+* for cache operations (get, set, getOrSet, delete, etc.).
+* Internal Redis/L2/bus spans are suppressed via `suppressInternalOperations`.
+*/
+async function instrumentCache(config, appRoot) {
+	if (config.enabled === false) return void 0;
+	const appRequire = createRequire(appRoot ? pathToFileURL(`${appRoot}/package.json`).href : import.meta.url);
+	try {
+		appRequire.resolve("@adonisjs/cache");
+	} catch {
+		return;
+	}
+	const instrumentation = new BentoCacheInstrumentation({
+		requireParentSpan: config.requireParentSpan ?? false,
+		includeKeys: config.includeKeys ?? true,
+		keySanitizer: config.keySanitizer ?? defaultKeySanitizer,
+		suppressInternalOperations: true
+	});
+	instrumentation.enable();
+	/**
+	* Eagerly import bentocache to trigger the ESM hook.
+	* If the hook didn't patch BentoCache (e.g. race condition),
+	* fall back to manual registration.
+	*/
+	try {
+		const bentocache = await import("bentocache");
+		if (bentocache.BentoCache.name !== "BentoCachePatched") instrumentation.manuallyRegister(bentocache);
+	} catch {}
+	return instrumentation;
+}
+//#endregion
+export { instrumentCache };

package/dist/src/instrumentations/mail/instrumentation.mjs

@@ -0,0 +1,157 @@
+import { ExceptionReporter } from "../../exception_reporter.mjs";
+import { EmailAttributes } from "./types.mjs";
+import { createRequire } from "node:module";
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { pathToFileURL } from "node:url";
+import { InstrumentationBase } from "@opentelemetry/instrumentation";
+//#region src/instrumentations/mail/instrumentation.ts
+/**
+* OpenTelemetry instrumentation for AdonisJS Mail.
+*
+* Patches Mailer.prototype methods to wrap email operations with spans.
+* Each email send creates a CLIENT span with email metadata attributes.
+*
+* Span names: `email send {mailerName}`, `email queue {mailerName}`
+* Attributes: See EmailAttributes
+*/
+var MailInstrumentation = class extends InstrumentationBase {
+	patched = false;
+	mailerClass;
+	originalSendCompiled;
+	originalSendLaterCompiled;
+	constructor(config = {}) {
+		super("@monocle.sh/instrumentation-mail", "1.0.0", config);
+	}
+	/**
+	* Required by InstrumentationBase. Returns undefined since we use
+	* monkey-patching instead of module patching.
+	*/
+	init() {}
+	/**
+	* Extract email address from a Recipient.
+	*/
+	extractAddress(recipient) {
+		return typeof recipient === "string" ? recipient : recipient.address;
+	}
+	/**
+	* Extract attributes from a mail message.
+	*/
+	extractMessageAttributes(message, mailerName, operation) {
+		const toAddresses = message.to?.map((r) => this.extractAddress(r)) ?? [];
+		const ccCount = message.cc?.length ?? 0;
+		const bccCount = message.bcc?.length ?? 0;
+		return {
+			[EmailAttributes.SYSTEM]: "adonisjs-mail",
+			[EmailAttributes.TRANSPORT]: mailerName,
+			[EmailAttributes.OPERATION]: operation,
+			[EmailAttributes.MESSAGE_SUBJECT]: message.subject ?? "",
+			[EmailAttributes.MESSAGE_FROM]: message.from ? this.extractAddress(message.from) : "",
+			[EmailAttributes.MESSAGE_TO]: toAddresses,
+			[EmailAttributes.MESSAGE_CC_COUNT]: ccCount,
+			[EmailAttributes.MESSAGE_BCC_COUNT]: bccCount,
+			[EmailAttributes.MESSAGE_HAS_ATTACHMENTS]: (message.attachments?.length ?? 0) > 0,
+			[EmailAttributes.RECIPIENT_COUNT]: toAddresses.length + ccCount + bccCount
+		};
+	}
+	/**
+	* Wraps an async function with an OpenTelemetry span.
+	*/
+	async wrapWithSpan(options) {
+		const { spanName, attributes, fn, onSuccess } = options;
+		const span = this.tracer.startSpan(spanName, {
+			kind: SpanKind.CLIENT,
+			attributes
+		});
+		const ctx = trace.setSpan(context.active(), span);
+		return context.with(ctx, async () => {
+			try {
+				const result = await fn();
+				if (onSuccess) onSuccess(span, result);
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				await new ExceptionReporter().report({
+					span,
+					error,
+					shouldReport: true
+				});
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
+	}
+	/**
+	* Wraps sendCompiled with tracing span.
+	*/
+	#createSendCompiledWrapper(original) {
+		const instrumentation = this;
+		return async function(mail, sendConfig) {
+			return instrumentation.wrapWithSpan({
+				spanName: `email send ${this.name}`,
+				attributes: instrumentation.extractMessageAttributes(mail.message, this.name, "send"),
+				fn: () => original.call(this, mail, sendConfig),
+				onSuccess: (span, response) => {
+					if (response?.messageId) span.setAttribute(EmailAttributes.MESSAGE_ID, response.messageId);
+				}
+			});
+		};
+	}
+	/**
+	* Wraps sendLaterCompiled with tracing span.
+	*/
+	#createSendLaterCompiledWrapper(original) {
+		const instrumentation = this;
+		return async function(mail, sendConfig) {
+			return instrumentation.wrapWithSpan({
+				spanName: `email queue ${this.name}`,
+				attributes: instrumentation.extractMessageAttributes(mail.message, this.name, "sendLater"),
+				fn: () => original.call(this, mail, sendConfig)
+			});
+		};
+	}
+	/**
+	* Patches Mailer.prototype methods with tracing wrappers.
+	*/
+	async enable() {
+		if (this.patched) return;
+		const appRoot = this.getConfig().appRoot;
+		const require = createRequire(appRoot ? pathToFileURL(`${appRoot}/package.json`).href : import.meta.url);
+		let mailerPath;
+		try {
+			mailerPath = require.resolve("@adonisjs/mail");
+		} catch {
+			return;
+		}
+		this.mailerClass = (await import(pathToFileURL(mailerPath).href)).Mailer;
+		this.originalSendCompiled = this.mailerClass.prototype.sendCompiled;
+		this.originalSendLaterCompiled = this.mailerClass.prototype.sendLaterCompiled;
+		this.mailerClass.prototype.sendCompiled = this.#createSendCompiledWrapper(this.originalSendCompiled);
+		this.mailerClass.prototype.sendLaterCompiled = this.#createSendLaterCompiledWrapper(this.originalSendLaterCompiled);
+		this.patched = true;
+	}
+	/**
+	* Restores original Mailer.prototype methods.
+	*/
+	disable() {
+		if (!this.patched || !this.mailerClass) return;
+		if (this.originalSendCompiled) this.mailerClass.prototype.sendCompiled = this.originalSendCompiled;
+		if (this.originalSendLaterCompiled) this.mailerClass.prototype.sendLaterCompiled = this.originalSendLaterCompiled;
+		this.patched = false;
+		this.mailerClass = void 0;
+		this.originalSendCompiled = void 0;
+		this.originalSendLaterCompiled = void 0;
+	}
+};
+/**
+* Helper function for backward compatibility.
+* Creates and enables a MailInstrumentation instance.
+*/
+async function instrumentMail(config, appRoot) {
+	if (config.enabled === false) return void 0;
+	const instrumentation = new MailInstrumentation({ appRoot: appRoot ?? config.appRoot });
+	await instrumentation.enable();
+	return instrumentation;
+}
+//#endregion
+export { instrumentMail };

package/dist/src/instrumentations/mail/types.mjs

@@ -0,0 +1,20 @@
+//#region src/instrumentations/mail/types.ts
+/**
+* Semantic convention attributes for email operations.
+* @see docs/semantic-conventions/email.md
+*/
+const EmailAttributes = {
+	SYSTEM: "email.system",
+	TRANSPORT: "email.transport",
+	OPERATION: "email.operation",
+	MESSAGE_SUBJECT: "email.message.subject",
+	MESSAGE_FROM: "email.message.from",
+	MESSAGE_TO: "email.message.to",
+	MESSAGE_CC_COUNT: "email.message.cc_count",
+	MESSAGE_BCC_COUNT: "email.message.bcc_count",
+	MESSAGE_HAS_ATTACHMENTS: "email.message.has_attachments",
+	MESSAGE_ID: "email.message.id",
+	RECIPIENT_COUNT: "email.recipient_count"
+};
+//#endregion
+export { EmailAttributes };

package/dist/src/monocle.d.mts

@@ -1,7 +1,7 @@
 import { UserContextResult } from "@adonisjs/otel/types";
 
 //#region src/monocle.d.ts
-type MessageLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+type MessageLevel = 'debug' | 'info' | 'log' | 'warning' | 'error' | 'fatal';
 interface CaptureContext {
   user?: {
     id: string;
@@ -15,6 +15,14 @@ interface CaptureMessageContext extends CaptureContext {
   level?: MessageLevel;
 }
 type CaptureExceptionContext = CaptureContext;
+/**
+ * User information for tracing. When displayed in the Monocle UI,
+ * `name` takes priority over `email` as the display label, with
+ * `email` used as fallback.
+ */
+interface MonocleUser extends UserContextResult {
+  name?: string;
+}
 /**
  * Monocle helper class for manual instrumentation.
  */
@@ -31,12 +39,20 @@ declare class Monocle {
   /**
    * Capture a message and record it on the current active span.
    * If no span is active, the message is silently ignored.
+   *
+   * Messages are stored using the same format as exceptions for unified querying.
+   * They are identified by exception.type = 'CapturedMessage'.
+   *
+   * This method is async to allow for source context extraction.
+   * You can choose to await it or fire-and-forget.
    */
-  static captureMessage(message: string, levelOrContext?: MessageLevel | CaptureMessageContext): void;
+  static captureMessage(message: string, levelOrContext?: MessageLevel | CaptureMessageContext): Promise<void>;
   /**
    * Set user information on the current active span.
+   * `name` is displayed with priority over `email` in the Monocle UI.
+   * Falls back to `email`, then `id`.
    */
-  static setUser(user: UserContextResult): void;
+  static setUser(user: MonocleUser): void;
 }
 //#endregion
-export { Monocle };
+export { Monocle, MonocleUser };

package/dist/src/monocle.mjs

@@ -1,8 +1,18 @@
 import { ExceptionReporter } from "./exception_reporter.mjs";
 import { trace } from "@opentelemetry/api";
 import { setUser } from "@adonisjs/otel/helpers";
-
+import { extractContextLines } from "@monocle.sh/otel-utils";
 //#region src/monocle.ts
+const DEFAULT_CONTEXT_LINES = 7;
+/**
+* Internal patterns to filter from stack traces.
+* These are frames from the Monocle SDK itself.
+*/
+const INTERNAL_FRAME_PATTERNS = [
+	"/monocle.ts",
+	"/monocle.js",
+	"@monocle.sh/"
+];
 /**
 * Monocle helper class for manual instrumentation.
 */
@@ -20,6 +30,22 @@ var Monocle = class {
 		return attributes;
 	}
 	/**
+	* Filter out internal Monocle SDK frames from context frames.
+	*/
+	static #filterInternalFrames(frames) {
+		return frames.filter((frame) => {
+			return !INTERNAL_FRAME_PATTERNS.some((pattern) => frame.filename.includes(pattern));
+		});
+	}
+	/**
+	* Filter out internal Monocle SDK lines from a stack trace string.
+	*/
+	static #filterInternalStack(stack) {
+		return stack.split("\n").filter((line) => {
+			return !INTERNAL_FRAME_PATTERNS.some((pattern) => line.includes(pattern));
+		}).join("\n");
+	}
+	/**
 	* Capture an exception and record it on the current active span.
 	* If no span is active, the exception is silently ignored.
 	*
@@ -41,27 +67,44 @@ var Monocle = class {
 	/**
 	* Capture a message and record it on the current active span.
 	* If no span is active, the message is silently ignored.
+	*
+	* Messages are stored using the same format as exceptions for unified querying.
+	* They are identified by exception.type = 'CapturedMessage'.
+	*
+	* This method is async to allow for source context extraction.
+	* You can choose to await it or fire-and-forget.
 	*/
-	static captureMessage(message, levelOrContext) {
+	static async captureMessage(message, levelOrContext) {
 		const span = trace.getActiveSpan();
 		if (!span) return;
 		const ctx = typeof levelOrContext === "string" ? { level: levelOrContext } : levelOrContext;
 		const level = ctx?.level ?? "info";
 		this.#applyUserToSpan(span, ctx?.user);
+		span.setAttribute("monocle.exception.should_report", true);
+		const syntheticError = new Error(message);
+		let frames = [];
+		if (syntheticError.stack) try {
+			const extracted = await extractContextLines(syntheticError.stack, DEFAULT_CONTEXT_LINES);
+			frames = this.#filterInternalFrames(extracted);
+		} catch {}
 		const attributes = {
-			"monocle.message.content": message,
+			"exception.type": "CapturedMessage",
+			"exception.message": message,
 			"monocle.message.level": level,
 			...this.#buildContextAttributes(ctx)
 		};
-		span.addEvent("monocle.message", attributes);
+		if (syntheticError.stack) attributes["exception.stacktrace"] = this.#filterInternalStack(syntheticError.stack);
+		if (frames.length > 0) attributes["monocle.exception.frames"] = JSON.stringify(frames);
+		span.addEvent("exception", attributes);
 	}
 	/**
 	* Set user information on the current active span.
+	* `name` is displayed with priority over `email` in the Monocle UI.
+	* Falls back to `email`, then `id`.
 	*/
 	static setUser(user) {
 		setUser(user);
 	}
 };
-
 //#endregion
-export { Monocle };
+export { Monocle };

package/dist/src/types.d.mts

@@ -1,7 +1,21 @@
-import { OtelConfig } from "@adonisjs/otel/types";
+import { BentoCacheInstrumentationConfig } from "@bentocache/otel/types";
+import { DestinationMap, OtelConfig } from "@adonisjs/otel/types";
 
 //#region src/types.d.ts
-
+/**
+ * Configuration for cache instrumentation
+ */
+interface CacheInstrumentationConfig extends BentoCacheInstrumentationConfig {}
+/**
+ * Configuration for mail instrumentation
+ */
+interface MailInstrumentationConfig {
+  /**
+   * Enable mail instrumentation.
+   * @default true
+   */
+  enabled?: boolean;
+}
 /**
  * Configuration for CLI command tracing
  */
@@ -86,6 +100,12 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * @default process.env.NODE_ENV || 'development'
    */
   environment?: string;
+  /**
+   * Additional OTLP destinations (Grafana, Honeycomb, etc.).
+   *
+   * Monocle destination is always injected automatically and cannot be removed.
+   */
+  destinations?: DestinationMap;
   /**
    * Host metrics configuration (CPU, Memory, Network, etc.).
    * Set to `false` to disable, or pass config object.
@@ -109,6 +129,20 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * @default false
    */
   cli?: false | CliTracingConfig;
+  /**
+   * Mail instrumentation configuration.
+   * Automatically instruments @adonisjs/mail if installed.
+   * Set to `false` to disable.
+   * @default { enabled: true }
+   */
+  mail?: false | MailInstrumentationConfig;
+  /**
+   * Cache instrumentation configuration.
+   * Automatically instruments @adonisjs/cache (bentocache) if installed.
+   * Set to `false` to disable.
+   * @default { enabled: true }
+   */
+  cache?: false | CacheInstrumentationConfig;
 }
 //#endregion
 export { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig };

package/dist/stubs/main.mjs

@@ -1,8 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
-
 //#region stubs/main.ts
 const stubsRoot = dirname(fileURLToPath(import.meta.url));
-
 //#endregion
-export { stubsRoot };
+export { stubsRoot };

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types.mjs";
+import { MonocleUser } from "./src/monocle.mjs";
+import { SpanAllOptions, SpanOptions } from "./decorators.mjs";
+import { DestinationConfig, DestinationMap, DestinationSignal, DestinationSignals, HeadersCarrier, OtelLoggingPresetOptions, OtlpDestinationConfig, OtlpDestinationOptions, UserContextResult } from "@adonisjs/otel/types";
+export { type BatchConfig, type CliTracingConfig, type DestinationConfig, type DestinationMap, type DestinationSignal, type DestinationSignals, type HeadersCarrier, type HostMetricsConfig, type MonocleConfig, type MonocleUser, type OtelLoggingPresetOptions, type OtlpDestinationConfig, type OtlpDestinationOptions, type SpanAllOptions, type SpanOptions, type UserContextResult };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};