@monocle.sh/adonisjs-agent 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/helpers.d.mts

@@ -9,7 +9,6 @@ import { extractTraceContext, getCurrentSpan, injectTraceContext, otelLoggingPre
  * to extract source context lines from the stack trace.
  */
 declare function handleError(span: Span, error: Error): Promise<never>;
-type RecordCallback<T> = (span: Span) => T | Promise<T>;
 /**
  * Record a code section as a span in your traces.
  *
@@ -17,8 +16,9 @@ type RecordCallback<T> = (span: Span) => T | Promise<T>;
  * to capture exceptions with source context lines (pre/post context around
  * the error location).
  *
- * Always returns a Promise to ensure context lines are properly captured
- * even for synchronous errors.
+ * Preserves sync/async semantics: if the callback is synchronous, the return
+ * type is `T`. If the callback returns a Promise-like value, the return type
+ * is async-compatible.
  *
  * Automatically handles:
  * - Creating and closing the span
@@ -29,10 +29,10 @@ type RecordCallback<T> = (span: Span) => T | Promise<T>;
  * ```ts
  * import { record } from '@monocle.sh/adonisjs-agent'
  *
- * const result = await record('database.query', () => {
- *   return db.query('SELECT * FROM users')
- * })
+ * // Sync callback returns T directly
+ * const value = record('compute.hash', () => computeHash(data))
  *
+ * // Async callback returns Promise<T>
  * const user = await record('user.fetch', async () => {
  *   return await userService.findById(id)
  * })
@@ -44,6 +44,6 @@ type RecordCallback<T> = (span: Span) => T | Promise<T>;
  * })
  * ```
  */
-declare function record<T>(name: string, callback: RecordCallback<T>): Promise<T>;
+declare function record<T>(name: string, callback: (span: Span) => T): T;
 //#endregion
 export { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes };

package/dist/helpers.mjs

@@ -1,8 +1,31 @@
 import { ExceptionReporter } from "./src/exception_reporter.mjs";
-import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { trace } from "@opentelemetry/api";
 import { extractTraceContext, getCurrentSpan, injectTraceContext, otelLoggingPreset, recordEvent, setAttributes } from "@adonisjs/otel/helpers";
 
 //#region src/helpers.ts
+function isPromiseLike(value) {
+	if (!value) return false;
+	if (typeof value !== "object" && typeof value !== "function") return false;
+	return typeof value.then === "function";
+}
+async function reportErrorAndEndSpan(span, error, endTime) {
+	const reporter = new ExceptionReporter();
+	try {
+		await reporter.report({
+			span,
+			error,
+			shouldReport: true
+		});
+	} catch {
+		reporter.reportSync({
+			span,
+			error,
+			shouldReport: true
+		});
+	} finally {
+		span.end(endTime);
+	}
+}
 /**
 * Handle an error by reporting it with context frames extraction.
 *
@@ -10,16 +33,7 @@ import { extractTraceContext, getCurrentSpan, injectTraceContext, otelLoggingPre
 * to extract source context lines from the stack trace.
 */
 async function handleError(span, error) {
-	await new ExceptionReporter().report({
-		span,
-		error,
-		shouldReport: true
-	});
-	span.setStatus({
-		code: SpanStatusCode.ERROR,
-		message: error?.message
-	});
-	span.end();
+	await reportErrorAndEndSpan(span, error, /* @__PURE__ */ new Date());
 	throw error;
 }
 /**
@@ -29,8 +43,9 @@ async function handleError(span, error) {
 * to capture exceptions with source context lines (pre/post context around
 * the error location).
 *
-* Always returns a Promise to ensure context lines are properly captured
-* even for synchronous errors.
+* Preserves sync/async semantics: if the callback is synchronous, the return
+* type is `T`. If the callback returns a Promise-like value, the return type
+* is async-compatible.
 *
 * Automatically handles:
 * - Creating and closing the span
@@ -41,10 +56,10 @@ async function handleError(span, error) {
 * ```ts
 * import { record } from '@monocle.sh/adonisjs-agent'
 *
-* const result = await record('database.query', () => {
-*   return db.query('SELECT * FROM users')
-* })
+* // Sync callback returns T directly
+* const value = record('compute.hash', () => computeHash(data))
 *
+* // Async callback returns Promise<T>
 * const user = await record('user.fetch', async () => {
 *   return await userService.findById(id)
 * })
@@ -56,14 +71,19 @@ async function handleError(span, error) {
 * })
 * ```
 */
-async function record(name, callback) {
-	return trace.getTracer("@monocle.sh/agent").startActiveSpan(name, async (span) => {
+function record(name, callback) {
+	return trace.getTracer("@monocle.sh/agent").startActiveSpan(name, (span) => {
 		try {
-			const result = await callback(span);
+			const result = callback(span);
+			if (isPromiseLike(result)) return Promise.resolve(result).then((value) => {
+				span.end();
+				return value;
+			}).catch((error) => handleError(span, error));
 			span.end();
 			return result;
 		} catch (error) {
-			return handleError(span, error);
+			reportErrorAndEndSpan(span, error, /* @__PURE__ */ new Date());
+			throw error;
 		}
 	});
 }

package/dist/init.mjs

@@ -74,6 +74,20 @@ async function init(dirname) {
 		const { instrumentMail } = await import("./src/instrumentations/mail/instrumentation.mjs");
 		await instrumentMail(mailConfig ?? { enabled: true }, dirname);
 	}
+	/**
+	* Cache Instrumentation
+	*
+	* Automatically instruments @adonisjs/cache (bentocache) if installed.
+	* Creates spans for cache operations (get, set, getOrSet, delete, etc.)
+	* and suppresses internal Redis/L2/bus spans.
+	*
+	* @see ./instrumentations/cache/instrumentation.ts for implementation details
+	*/
+	const cacheConfig = config.cache;
+	if (cacheConfig !== false) {
+		const { instrumentCache } = await import("./src/instrumentations/cache/instrumentation.mjs");
+		await instrumentCache(cacheConfig ?? { enabled: true }, dirname);
+	}
 	await waitForAllMessagesAcknowledged();
 }
 

package/dist/src/exception_reporter.mjs

@@ -33,6 +33,23 @@ var ExceptionReporter = class {
 		const attributes = this.#buildAttributes(error, causeChain);
 		span.addEvent("exception", attributes);
 	}
+	/**
+	* Synchronous version of report. Uses buildCauseChain (no file I/O)
+	* so source context frames won't be available, but the full stack trace,
+	* cause chain, error status, and exception event are still recorded.
+	*/
+	reportSync(options) {
+		const { span, shouldReport } = options;
+		const error = toHttpError(options.error);
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: error.message
+		});
+		span.setAttribute("monocle.exception.should_report", shouldReport);
+		const causeChain = buildCauseChain(error);
+		const attributes = this.#buildAttributes(error, causeChain);
+		span.addEvent("exception", attributes);
+	}
 	#buildAttributes(error, causeChain) {
 		const hasCauses = causeChain.length > 1;
 		const attributes = {

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

@@ -0,0 +1,55 @@
+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/monocle.d.mts

@@ -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.
  */
@@ -41,8 +49,10 @@ declare class Monocle {
   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

@@ -100,6 +100,8 @@ var Monocle = class {
 	}
 	/**
 	* 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);

package/dist/src/types.d.mts

@@ -1,6 +1,11 @@
 import { DestinationMap, OtelConfig } from "@adonisjs/otel/types";
+import { BentoCacheInstrumentationConfig } from "@bentocache/otel/types";
 
 //#region src/types.d.ts
+/**
+ * Configuration for cache instrumentation
+ */
+interface CacheInstrumentationConfig extends BentoCacheInstrumentationConfig {}
 /**
  * Configuration for mail instrumentation
  */
@@ -131,6 +136,13 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * @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/config.stub

@@ -1,7 +1,7 @@
 {{{
   exports({ to: app.configPath('monocle.ts') })
 }}}
-import { defineConfig, destinations } from '@monocle.sh/adonisjs-agent'
+import { defineConfig } from '@monocle.sh/adonisjs-agent'
 import env from '#start/env'
 
 export default defineConfig({
@@ -10,12 +10,4 @@ export default defineConfig({
   serviceName: env.get('APP_NAME'),
   serviceVersion: env.get('APP_VERSION'),
   environment: env.get('APP_ENV'),
-
-  // Optional: Additional OTLP destinations (Monocle is injected automatically)
-  // destinations: {
-  //   grafana: destinations.otlp({
-  //     endpoint: env.get('GRAFANA_OTLP_ENDPOINT'),
-  //     signals: 'all',
-  //   }),
-  // },
 })

package/dist/types.d.mts

@@ -1,4 +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 OtelLoggingPresetOptions, type OtlpDestinationConfig, type OtlpDestinationOptions, type SpanAllOptions, type SpanOptions, type UserContextResult };
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/adonisjs-agent",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@adonisjs/otel": "^1.2.0",
+    "@bentocache/otel": "^0.1.2",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.5.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.211.0",