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

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-present, Julien Ripouteau
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

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/configure.d.mts

@@ -1,7 +1,6 @@
 import ConfigureCommand from "@adonisjs/core/commands/configure";
 
 //#region configure.d.ts
-
 declare function configure(command: ConfigureCommand): Promise<void>;
 //#endregion
 export { configure };

package/dist/configure.mjs

@@ -1,5 +1,4 @@
 import { stubsRoot } from "./stubs/main.mjs";
-
 //#region configure.ts
 async function configure(command) {
 	const codemods = await command.createCodemods();
@@ -56,6 +55,5 @@ async function configure(command) {
 		MONOCLE_API_KEY: "Env.schema.string.optional()"
 	} });
 }
-
 //#endregion
-export { configure };
+export { configure };

package/dist/decorators.d.mts

@@ -0,0 +1,83 @@
+import { Attributes } from "@opentelemetry/api";
+
+//#region src/decorators.d.ts
+interface SpanOptions {
+  name?: string;
+  attributes?: Attributes;
+}
+interface SpanAllOptions {
+  prefix?: string;
+  attributes?: Attributes;
+}
+/**
+ * Decorator to create a span around a method.
+ *
+ * Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+ * to capture exceptions with source context lines.
+ *
+ * Automatically handles:
+ * - Creating and closing the span
+ * - Capturing exceptions with context frames
+ * - Setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { span } from '@monocle.sh/adonisjs-agent'
+ *
+ * class UserService {
+ *   @span()
+ *   async findById(id: string) {
+ *     // Span name: "UserService.findById"
+ *     return db.users.find(id)
+ *   }
+ *
+ *   @span({ name: 'user.create', attributes: { operation: 'create' } })
+ *   async create(data: UserData) {
+ *     return db.users.create(data)
+ *   }
+ * }
+ * ```
+ */
+declare function span(options?: SpanOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator to create spans around all methods of a class.
+ *
+ * Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+ * to capture exceptions with source context lines.
+ *
+ * Automatically handles:
+ * - Creating and closing spans for each method
+ * - Capturing exceptions with context frames
+ * - Setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { spanAll } from '@monocle.sh/adonisjs-agent'
+ *
+ * @spanAll()
+ * class OrderService {
+ *   async create(data: OrderData) {
+ *     // Span name: "OrderService.create"
+ *     return db.orders.create(data)
+ *   }
+ *
+ *   async findById(id: string) {
+ *     // Span name: "OrderService.findById"
+ *     return db.orders.find(id)
+ *   }
+ * }
+ *
+ * @spanAll({ prefix: 'order' })
+ * class OrderService {
+ *   async create(data: OrderData) {
+ *     // Span name: "order.create"
+ *     return db.orders.create(data)
+ *   }
+ * }
+ * ```
+ */
+declare function spanAll(options?: SpanAllOptions): <T extends new (...args: any[]) => any>(constructor: T) => T;
+//#endregion
+export { SpanAllOptions, SpanOptions, span, spanAll };

package/dist/decorators.mjs

@@ -0,0 +1,108 @@
+import { record } from "./helpers.mjs";
+//#region src/decorators.ts
+/**
+* Wrap a method to create a span around its execution.
+*/
+function wrapMethod(target, propertyKey, descriptor, options) {
+	const originalMethod = descriptor.value;
+	const className = target.constructor.name;
+	descriptor.value = function(...args) {
+		return record(options?.name ?? `${className}.${propertyKey}`, (activeSpan) => {
+			if (options?.attributes) activeSpan.setAttributes(options.attributes);
+			return originalMethod.apply(this, args);
+		});
+	};
+	return descriptor;
+}
+/**
+* Decorator to create a span around a method.
+*
+* Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+* to capture exceptions with source context lines.
+*
+* Automatically handles:
+* - Creating and closing the span
+* - Capturing exceptions with context frames
+* - Setting error status
+* - Async/await support
+*
+* @example
+* ```ts
+* import { span } from '@monocle.sh/adonisjs-agent'
+*
+* class UserService {
+*   @span()
+*   async findById(id: string) {
+*     // Span name: "UserService.findById"
+*     return db.users.find(id)
+*   }
+*
+*   @span({ name: 'user.create', attributes: { operation: 'create' } })
+*   async create(data: UserData) {
+*     return db.users.create(data)
+*   }
+* }
+* ```
+*/
+function span(options) {
+	return function(target, propertyKey, descriptor) {
+		return wrapMethod(target, propertyKey, descriptor, options);
+	};
+}
+/**
+* Decorator to create spans around all methods of a class.
+*
+* Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+* to capture exceptions with source context lines.
+*
+* Automatically handles:
+* - Creating and closing spans for each method
+* - Capturing exceptions with context frames
+* - Setting error status
+* - Async/await support
+*
+* @example
+* ```ts
+* import { spanAll } from '@monocle.sh/adonisjs-agent'
+*
+* @spanAll()
+* class OrderService {
+*   async create(data: OrderData) {
+*     // Span name: "OrderService.create"
+*     return db.orders.create(data)
+*   }
+*
+*   async findById(id: string) {
+*     // Span name: "OrderService.findById"
+*     return db.orders.find(id)
+*   }
+* }
+*
+* @spanAll({ prefix: 'order' })
+* class OrderService {
+*   async create(data: OrderData) {
+*     // Span name: "order.create"
+*     return db.orders.create(data)
+*   }
+* }
+* ```
+*/
+function spanAll(options) {
+	return function(constructor) {
+		const prototype = constructor.prototype;
+		const propertyNames = Object.getOwnPropertyNames(prototype);
+		for (const propertyName of propertyNames) {
+			if (propertyName === "constructor") continue;
+			const descriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);
+			if (!descriptor || typeof descriptor.value !== "function") continue;
+			const wrappedDescriptor = wrapMethod(prototype, propertyName, descriptor, {
+				name: options?.prefix ? `${options.prefix}.${propertyName}` : void 0,
+				attributes: options?.attributes
+			});
+			Object.defineProperty(prototype, propertyName, wrappedDescriptor);
+		}
+		return constructor;
+	};
+}
+//#endregion
+export { span, spanAll };

package/dist/helpers.d.mts

@@ -0,0 +1,49 @@
+import { Span } from "@opentelemetry/api";
+import { extractTraceContext, getCurrentSpan, injectTraceContext, otelLoggingPreset, recordEvent, setAttributes } from "@adonisjs/otel/helpers";
+
+//#region src/helpers.d.ts
+/**
+ * Handle an error by reporting it with context frames extraction.
+ *
+ * Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+ * to extract source context lines from the stack trace.
+ */
+declare function handleError(span: Span, error: Error): Promise<never>;
+/**
+ * Record a code section as a span in your traces.
+ *
+ * Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+ * to capture exceptions with source context lines (pre/post context around
+ * the error location).
+ *
+ * Preserves sync/async semantics: if the callback is synchronous, the return
+ * type is `T`. If the callback returns a Promise, the return type
+ * is async-compatible.
+ *
+ * Automatically handles:
+ * - Creating and closing the span
+ * - Capturing exceptions with context frames
+ * - Setting error status
+ *
+ * @example
+ * ```ts
+ * import { record } from '@monocle.sh/adonisjs-agent'
+ *
+ * // 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)
+ * })
+ *
+ * // With attributes
+ * const order = await record('order.process', async (span) => {
+ *   span.setAttributes({ 'order.id': orderId })
+ *   return await processOrder(orderId)
+ * })
+ * ```
+ */
+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

@@ -0,0 +1,84 @@
+import { ExceptionReporter } from "./src/exception_reporter.mjs";
+import { trace } from "@opentelemetry/api";
+import { extractTraceContext, getCurrentSpan, injectTraceContext, otelLoggingPreset, recordEvent, setAttributes } from "@adonisjs/otel/helpers";
+//#region src/helpers.ts
+function isNativePromise(value) {
+	if (!value) return false;
+	if (typeof value !== "object" && typeof value !== "function") return false;
+	return value instanceof Promise || Object.prototype.toString.call(value) === "[object Promise]";
+}
+async function reportErrorAndEndSpan(span, error, endTime) {
+	const reporter = new ExceptionReporter();
+	try {
+		await reporter.report({
+			span,
+			error,
+			shouldReport: true
+		});
+	} catch {} finally {
+		span.end(endTime);
+	}
+}
+/**
+* Handle an error by reporting it with context frames extraction.
+*
+* Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+* to extract source context lines from the stack trace.
+*/
+async function handleError(span, error) {
+	await reportErrorAndEndSpan(span, error, /* @__PURE__ */ new Date());
+	throw error;
+}
+/**
+* Record a code section as a span in your traces.
+*
+* Unlike the @adonisjs/otel version, this uses Monocle's ExceptionReporter
+* to capture exceptions with source context lines (pre/post context around
+* the error location).
+*
+* Preserves sync/async semantics: if the callback is synchronous, the return
+* type is `T`. If the callback returns a Promise, the return type
+* is async-compatible.
+*
+* Automatically handles:
+* - Creating and closing the span
+* - Capturing exceptions with context frames
+* - Setting error status
+*
+* @example
+* ```ts
+* import { record } from '@monocle.sh/adonisjs-agent'
+*
+* // 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)
+* })
+*
+* // With attributes
+* const order = await record('order.process', async (span) => {
+*   span.setAttributes({ 'order.id': orderId })
+*   return await processOrder(orderId)
+* })
+* ```
+*/
+function record(name, callback) {
+	return trace.getTracer("@monocle.sh/agent").startActiveSpan(name, (span) => {
+		try {
+			const result = callback(span);
+			if (isNativePromise(result)) return Promise.resolve(result).then((value) => {
+				span.end();
+				return value;
+			}).catch((error) => handleError(span, error));
+			span.end();
+			return result;
+		} catch (error) {
+			reportErrorAndEndSpan(span, error, /* @__PURE__ */ new Date());
+			throw error;
+		}
+	});
+}
+//#endregion
+export { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes };

package/dist/index.d.mts

@@ -2,4 +2,7 @@ import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from
 import { defineConfig } from "./src/define_config.mjs";
 import { Monocle } from "./src/monocle.mjs";
 import { configure } from "./configure.mjs";
-export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, configure, defineConfig };
+import { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes } from "./helpers.mjs";
+import { SpanAllOptions, SpanOptions, span, spanAll } from "./decorators.mjs";
+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

@@ -1,5 +1,7 @@
 import { defineConfig } from "./src/define_config.mjs";
 import { Monocle } from "./src/monocle.mjs";
 import { configure } from "./configure.mjs";
-
-export { Monocle, configure, defineConfig };
+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, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };

package/dist/init.mjs

@@ -2,18 +2,11 @@ import { register } from "node:module";
 import { pathToFileURL } from "node:url";
 import { join } from "node:path";
 import { createAddHookMessageChannel } from "import-in-the-middle";
-
 //#region src/init.ts
 /**
 * 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 +17,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$1) {
+async function init(dirname) {
 	const waitForAllMessagesAcknowledged = setupHooks();
 	const { OtelManager } = await import("@adonisjs/otel/manager");
-	const config = await loadConfig(join(dirname$1, "config/monocle.js"));
+	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(() => {});
@@ -101,10 +58,36 @@ async function init(dirname$1) {
 	const cliConfig = config.cli;
 	if (cliConfig !== false && cliConfig?.enabled) {
 		const { instrumentCliCommands } = await import("./src/cli_instrumentation.mjs");
-		await instrumentCliCommands(cliConfig, dirname$1);
+		await instrumentCliCommands(cliConfig, dirname);
+	}
+	/**
+	* Mail Instrumentation
+	*
+	* Automatically instruments @adonisjs/mail if installed.
+	* Creates spans for email send operations with metadata attributes.
+	*
+	* @see ./instrumentations/mail/instrumentation.ts for implementation details
+	*/
+	const mailConfig = config.mail;
+	if (mailConfig !== false) {
+		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();
 }
-
 //#endregion
-export { init };
+export { init };

package/dist/mcp.d.mts

@@ -0,0 +1,2 @@
+import { InstrumentMcpServerOptions, instrumentMcpServer } from "@monocle.sh/instrumentation-mcp";
+export { type InstrumentMcpServerOptions, instrumentMcpServer };

package/dist/mcp.mjs

@@ -0,0 +1,2 @@
+import { instrumentMcpServer } from "@monocle.sh/instrumentation-mcp";
+export { instrumentMcpServer };

package/dist/monocle_middleware.mjs

@@ -1,7 +1,5 @@
 import OtelMiddleware from "@adonisjs/otel/otel_middleware";
-
 //#region middleware/monocle_middleware.ts
 var monocle_middleware_default = OtelMiddleware;
-
 //#endregion
-export { monocle_middleware_default as default };
+export { monocle_middleware_default as default };

package/dist/monocle_provider.d.mts

@@ -1,7 +1,6 @@
 import { ApplicationService } from "@adonisjs/core/types";
 
 //#region providers/monocle_provider.d.ts
-
 /**
  * Stolen from @Adonisjs/otel to use another config filename. we need to expose this
  * option from @adonis/otel so we can remove this file in the future.

package/dist/monocle_provider.mjs

@@ -1,10 +1,9 @@
 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";
-
 //#region providers/monocle_provider.ts
 /**
 * Stolen from @Adonisjs/otel to use another config filename. we need to expose this
@@ -61,6 +60,5 @@ var OtelProvider = class {
 		await OtelManager.getInstance()?.shutdown();
 	}
 };
-
 //#endregion
-export { OtelProvider as default };
+export { OtelProvider as default };