@monocle.sh/adonisjs-agent 1.0.0-beta.10

package/README.md

@@ -0,0 +1,133 @@
+# @monocle.sh/adonisjs-agent
+
+Monocle agent for AdonisJS - sends telemetry to Monocle cloud.
+
+## Installation
+
+```bash
+npm install @monocle.sh/adonisjs-agent
+# or
+yarn add @monocle.sh/adonisjs-agent
+# or
+pnpm add @monocle.sh/adonisjs-agent
+```
+
+## Configuration
+
+Run the configure command to set up the agent automatically:
+
+```bash
+node ace configure @monocle.sh/adonisjs-agent
+```
+
+This will:
+
+1. Create `config/monocle.ts` configuration file
+2. Create `otel.ts` initialization file at project root
+3. Add the otel.ts import as the first import in `bin/server.ts`
+4. Register the Monocle provider in `adonisrc.ts`
+5. Register the Monocle middleware as the first router middleware
+6. Add required environment variables to `.env` and `start/env.ts`
+
+After configuration, add your API key to `.env`:
+
+```env
+MONOCLE_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## User Identification
+
+To associate telemetry data with authenticated users, add `Monocle.setUser()` in your authentication middleware:
+
+```typescript
+import type { NextFn } from '@adonisjs/core/types/http'
+import type { HttpContext } from '@adonisjs/core/http'
+import { Monocle } from '@monocle.sh/adonisjs-agent'
+
+export default class SilentAuthMiddleware {
+  async handle(ctx: HttpContext, next: NextFn) {
+    await ctx.auth.check()
+
+    if (ctx.auth.user) Monocle.setUser(ctx.auth.user)
+
+    return next()
+  }
+}
+```
+
+## Exception Tracking
+
+Exceptions are automatically recorded in spans when thrown during a request. The agent hooks into AdonisJS's `ExceptionHandler.report()` method to capture exceptions with their stack traces.
+
+If you want to manually capture exceptions in custom code:
+
+```typescript
+import { Monocle } from '@monocle.sh/adonisjs-agent'
+
+try {
+  // your code
+} catch (error) {
+  Monocle.captureException(error, {
+    user: { id: '123', email: 'user@example.com' },
+    tags: { component: 'payment' },
+    extra: { orderId: 456 },
+  })
+  throw error
+}
+```
+
+## Configuration Options
+
+The `config/monocle.ts` file supports the following options:
+
+```typescript
+import { defineConfig } from '@monocle.sh/adonisjs-agent'
+import env from '#start/env'
+
+export default defineConfig({
+  // Optional: Your Monocle API key
+  apiKey: env.get('MONOCLE_API_KEY'),
+
+  // Optional: Custom ingestion endpoint (for development)
+  // endpoint: 'http://localhost:4318',
+
+  // Service identification
+  serviceName: env.get('APP_NAME'),
+  serviceVersion: env.get('APP_VERSION'),
+  environment: env.get('APP_ENV'),
+
+  // Host metrics (CPU, Memory, Network, etc.)
+  // Set to false to disable
+  hostMetrics: {
+    enabled: true,
+  },
+
+  // CLI command tracing
+  cli: {
+    enabled: false,
+    exclude: ['make:*', 'generate:*', 'queue:work', 'queue:listen'],
+  },
+
+  // Trace batching configuration
+  batch: {
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5000,
+  },
+
+  // Enable gzip compression (default: true)
+  compression: true,
+})
+```
+
+## Environment Variables
+
+| Variable          | Description                                            | Required |
+| ----------------- | ------------------------------------------------------ | -------- |
+| `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      |
+
+## License
+
+ISC

package/dist/configure.d.mts

@@ -0,0 +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

@@ -0,0 +1,61 @@
+import { stubsRoot } from "./stubs/main.mjs";
+
+//#region configure.ts
+async function configure(command) {
+	const codemods = await command.createCodemods();
+	/**
+	* Publish config/monocle.ts
+	*/
+	await codemods.makeUsingStub(stubsRoot, "config.stub", {});
+	/**
+	* Publish otel.ts at project root
+	*/
+	await codemods.makeUsingStub(stubsRoot, "otel.stub", {});
+	const serverFile = (await codemods.getTsMorphProject())?.getSourceFile(command.app.makePath("bin/server.ts"));
+	if (serverFile) {
+		const insertIndex = serverFile.getImportDeclarations()[0]?.getChildIndex() ?? 0;
+		serverFile.insertStatements(insertIndex, [
+			"/**",
+			" * OpenTelemetry initialization - MUST be the first import",
+			" * @see https://opentelemetry.io/docs/languages/js/getting-started/nodejs/",
+			" */",
+			`import '../otel.js'`,
+			""
+		]);
+		await serverFile.save();
+	}
+	/**
+	* Register the provider in adonisrc.ts
+	*/
+	await codemods.updateRcFile((rcFile) => {
+		rcFile.addProvider("@monocle.sh/adonisjs-agent/monocle_provider");
+	});
+	/**
+	* Register the middleware as FIRST router middleware
+	*/
+	await codemods.registerMiddleware("router", [{
+		path: "@monocle.sh/adonisjs-agent/monocle_middleware",
+		position: "before"
+	}]);
+	/**
+	* Define environment variables in .env
+	*/
+	await codemods.defineEnvVariables({
+		APP_NAME: command.app.appName,
+		APP_VERSION: "0.0.1",
+		APP_ENV: "development",
+		MONOCLE_API_KEY: ""
+	});
+	/**
+	* Define environment validations in start/env.ts
+	*/
+	await codemods.defineEnvValidations({ variables: {
+		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.optional()"
+	} });
+}
+
+//#endregion
+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,110 @@
+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>;
+type RecordCallback<T> = (span: Span) => T | Promise<T>;
+/**
+ * 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).
+ *
+ * Always returns a Promise to ensure context lines are properly captured
+ * even for synchronous errors.
+ *
+ * Automatically handles:
+ * - Creating and closing the span
+ * - Capturing exceptions with context frames
+ * - Setting error status
+ *
+ * @example
+ * ```ts
+ * import { record } from '@monocle.sh/adonisjs-agent'
+ *
+ * const result = await record('database.query', () => {
+ *   return db.query('SELECT * FROM users')
+ * })
+ *
+ * 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: RecordCallback<T>): Promise<T>;
+//#endregion
+export { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes };

package/dist/helpers.mjs

@@ -0,0 +1,72 @@
+import { ExceptionReporter } from "./src/exception_reporter.mjs";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { extractTraceContext, getCurrentSpan, injectTraceContext, otelLoggingPreset, recordEvent, setAttributes } from "@adonisjs/otel/helpers";
+
+//#region src/helpers.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.
+*/
+async function handleError(span, error) {
+	await new ExceptionReporter().report({
+		span,
+		error,
+		shouldReport: true
+	});
+	span.setStatus({
+		code: SpanStatusCode.ERROR,
+		message: error?.message
+	});
+	span.end();
+	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).
+*
+* Always returns a Promise to ensure context lines are properly captured
+* even for synchronous errors.
+*
+* Automatically handles:
+* - Creating and closing the span
+* - Capturing exceptions with context frames
+* - Setting error status
+*
+* @example
+* ```ts
+* import { record } from '@monocle.sh/adonisjs-agent'
+*
+* const result = await record('database.query', () => {
+*   return db.query('SELECT * FROM users')
+* })
+*
+* 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)
+* })
+* ```
+*/
+async function record(name, callback) {
+	return trace.getTracer("@monocle.sh/agent").startActiveSpan(name, async (span) => {
+		try {
+			const result = await callback(span);
+			span.end();
+			return result;
+		} catch (error) {
+			return handleError(span, error);
+		}
+	});
+}
+
+//#endregion
+export { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes };

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types.mjs";
+import { defineConfig } from "./src/define_config.mjs";
+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 };

package/dist/index.mjs

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

package/dist/init.d.mts

@@ -0,0 +1,8 @@
+//#region src/init.d.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.
+ */
+declare function init(dirname: string): Promise<void>;
+//#endregion
+export { init };

package/dist/init.mjs

@@ -0,0 +1,123 @@
+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 });
+	});
+}
+function setupHooks() {
+	const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel();
+	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);
+	manager?.start();
+	const shutdown = async () => {
+		await manager?.shutdown().catch(() => {});
+	};
+	process.on("beforeExit", shutdown);
+	process.on("SIGINT", async () => {
+		await shutdown();
+		process.exit(0);
+	});
+	process.on("SIGTERM", async () => {
+		await shutdown();
+		process.exit(0);
+	});
+	const hostMetricsConfig = config.hostMetrics;
+	if (hostMetricsConfig !== false) {
+		const { startHostMetrics } = await import("./src/host_metrics.mjs");
+		startHostMetrics(hostMetricsConfig === void 0 ? {} : hostMetricsConfig);
+	}
+	/**
+	* CLI Command Instrumentation
+	*
+	* When enabled, this patches AdonisJS Ace commands to create OTEL spans.
+	* The `dirname` parameter is passed so the instrumentation can resolve
+	* @adonisjs/core/ace from the app's node_modules (pnpm isolation).
+	*
+	* Prerequisites for this to work:
+	* 1. App's `bin/console.ts` must import `otel.ts` FIRST (before reflect-metadata)
+	* 2. Config must have `cli.enabled: true`
+	*
+	* @see ./cli_instrumentation.ts for implementation details
+	*/
+	const cliConfig = config.cli;
+	if (cliConfig !== false && cliConfig?.enabled) {
+		const { instrumentCliCommands } = await import("./src/cli_instrumentation.mjs");
+		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);
+	}
+	await waitForAllMessagesAcknowledged();
+}
+
+//#endregion
+export { init };

package/dist/monocle_middleware.d.mts

@@ -0,0 +1,2 @@
+import OtelMiddleware from "@adonisjs/otel/otel_middleware";
+export { OtelMiddleware as default };

package/dist/monocle_middleware.mjs

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