@monocle.sh/adonisjs-agent 1.0.0-beta.11 → 1.0.0-beta.13

package/README.md

@@ -81,7 +81,7 @@ try {
 The `config/monocle.ts` file supports the following options:
 
 ```typescript
-import { defineConfig } from '@monocle.sh/adonisjs-agent'
+import { defineConfig, destinations } from '@monocle.sh/adonisjs-agent'
 import env from '#start/env'
 
 export default defineConfig({
@@ -96,6 +96,14 @@ export default defineConfig({
   serviceVersion: env.get('APP_VERSION'),
   environment: env.get('APP_ENV'),
 
+  // Additional OTLP destinations (Monocle is always injected automatically)
+  destinations: {
+    grafana: destinations.otlp({
+      endpoint: env.get('GRAFANA_OTLP_ENDPOINT'),
+      signals: 'all',
+    }),
+  },
+
   // Host metrics (CPU, Memory, Network, etc.)
   // Set to false to disable
   hostMetrics: {
@@ -108,13 +116,13 @@ export default defineConfig({
     exclude: ['make:*', 'generate:*', 'queue:work', 'queue:listen'],
   },
 
-  // Trace batching configuration
+  // Trace/log batching configuration for Monocle destination
   batch: {
     maxExportBatchSize: 512,
     scheduledDelayMillis: 5000,
   },
 
-  // Enable gzip compression (default: true)
+  // Enable gzip compression for Monocle destination (default: true)
   compression: true,
 })
 ```

package/dist/index.d.mts

@@ -4,4 +4,5 @@ import { Monocle } from "./src/monocle.mjs";
 import { configure } from "./configure.mjs";
 import { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes } from "./helpers.mjs";
 import { SpanAllOptions, SpanOptions, span, spanAll } from "./decorators.mjs";
-export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, type SpanAllOptions, type SpanOptions, configure, defineConfig, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };
+import { destinations } from "@adonisjs/otel";
+export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, type SpanAllOptions, type SpanOptions, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };

package/dist/index.mjs

@@ -3,5 +3,6 @@ import { Monocle } from "./src/monocle.mjs";
 import { configure } from "./configure.mjs";
 import { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes } from "./helpers.mjs";
 import { span, spanAll } from "./decorators.mjs";
+import { destinations } from "@adonisjs/otel";
 
-export { Monocle, configure, defineConfig, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };
+export { Monocle, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };

package/dist/init.mjs

@@ -8,12 +8,6 @@ import { createAddHookMessageChannel } from "import-in-the-middle";
 * Also stolen and tweaked from @adonisjs/otel in order to use our own config file.
 * Need to be able to remove this file in the future.
 */
-const DEFAULT_BATCH_CONFIG = {
-	maxExportBatchSize: 512,
-	scheduledDelayMillis: 5e3,
-	exportTimeoutMillis: 3e4,
-	maxQueueSize: 2048
-};
 async function loadConfig(path) {
 	return await import(pathToFileURL(path).href).then((mod) => mod.default || mod).catch((error) => {
 		throw new Error(`Failed to load Monocle config file at "${path}"`, { cause: error });
@@ -24,49 +18,13 @@ function setupHooks() {
 	register("import-in-the-middle/hook.mjs", import.meta.url, registerOptions);
 	return waitForAllMessagesAcknowledged;
 }
-/**
-* Create a metric reader for exporting metrics via OTLP
-*/
-async function createMetricReader(config) {
-	const { PeriodicExportingMetricReader } = await import("@opentelemetry/sdk-metrics");
-	const { OTLPMetricExporter } = await import("@opentelemetry/exporter-metrics-otlp-http");
-	return new PeriodicExportingMetricReader({
-		exporter: new OTLPMetricExporter({ compression: config.compression !== false ? "gzip" : void 0 }),
-		exportIntervalMillis: 6e4
-	});
-}
-/**
-* Create a BatchSpanProcessor for efficient trace export with compression
-*/
-async function createSpanProcessor(config) {
-	const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
-	const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
-	const compression = config.compression !== false ? "gzip" : void 0;
-	const batchConfig = {
-		...DEFAULT_BATCH_CONFIG,
-		...config.batch
-	};
-	return new BatchSpanProcessor(new OTLPTraceExporter({ compression }), {
-		maxExportBatchSize: batchConfig.maxExportBatchSize,
-		scheduledDelayMillis: batchConfig.scheduledDelayMillis,
-		exportTimeoutMillis: batchConfig.exportTimeoutMillis,
-		maxQueueSize: batchConfig.maxQueueSize
-	});
-}
 async function init(dirname) {
 	const waitForAllMessagesAcknowledged = setupHooks();
 	const { OtelManager } = await import("@adonisjs/otel/manager");
 	const config = await loadConfig(join(dirname, "config/monocle.js"));
 	if (!config) return;
 	if (!OtelManager.isEnabled(config)) return;
-	const metricReader = await createMetricReader(config);
-	const spanProcessor = await createSpanProcessor(config);
-	const configWithProcessors = {
-		...config,
-		metricReader,
-		spanProcessors: [spanProcessor, ...config.spanProcessors || []]
-	};
-	const manager = OtelManager.create(configWithProcessors);
+	const manager = OtelManager.create(config);
 	manager?.start();
 	const shutdown = async () => {
 		await manager?.shutdown().catch(() => {});
@@ -116,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/monocle_provider.mjs

@@ -1,7 +1,7 @@
 import { ExceptionReporter, toHttpError } from "./src/exception_reporter.mjs";
+import { OtelManager } from "@adonisjs/otel";
 import { getCurrentSpan } from "@adonisjs/otel/helpers";
 import OtelMiddleware from "@adonisjs/otel/otel_middleware";
-import { OtelManager } from "@adonisjs/otel";
 import { ExceptionHandler } from "@adonisjs/core/http";
 import { configProvider } from "@adonisjs/core";
 

package/dist/src/define_config.d.mts

@@ -3,7 +3,6 @@ import { MonocleConfig } from "./types.mjs";
 //#region src/define_config.d.ts
 /**
  * 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).
  */
 declare function defineConfig(config: MonocleConfig): MonocleConfig | undefined;

package/dist/src/define_config.mjs

@@ -1,4 +1,12 @@
+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 +50,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,11 +70,28 @@ 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
+		}
 	};
 }
 

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

@@ -0,0 +1,46 @@
+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();
+	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 { OtelConfig } from "@adonisjs/otel/types";
+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
  */
@@ -95,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.
@@ -125,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/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 { HeadersCarrier, OtelLoggingPresetOptions, UserContextResult } from "@adonisjs/otel/types";
-export { type BatchConfig, type CliTracingConfig, type HeadersCarrier, type HostMetricsConfig, type MonocleConfig, type OtelLoggingPresetOptions, type SpanAllOptions, type SpanOptions, type UserContextResult };
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/adonisjs-agent",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.13",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",
@@ -31,7 +31,8 @@
     "tag": "beta"
   },
   "dependencies": {
-    "@adonisjs/otel": "^1.1.2",
+    "@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",