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

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({
+  // Required: 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                                   | Yes      |
+| `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,7 @@
+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()"
+	} });
+}
+
+//#endregion
+export { configure };

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+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";
+export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, configure, defineConfig };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from "./src/define_config.mjs";
+import { Monocle } from "./src/monocle.mjs";
+import { configure } from "./configure.mjs";
+
+export { Monocle, configure, defineConfig };

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,112 @@
+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$1) {
+	const waitForAllMessagesAcknowledged = setupHooks();
+	const { OtelManager } = await import("@adonisjs/otel/manager");
+	const config = await loadConfig(join(dirname$1, "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(() => {
+			console.error("Error during OTEL shutdown");
+		});
+	};
+	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$1);
+	}
+	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 };

package/dist/monocle_provider.d.mts

@@ -0,0 +1,20 @@
+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.
+ */
+declare class OtelProvider {
+  #private;
+  protected app: ApplicationService;
+  constructor(app: ApplicationService);
+  register(): void;
+  /**
+   * Gracefully flush pending spans
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+export { OtelProvider as default };

package/dist/monocle_provider.mjs

@@ -0,0 +1,66 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+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
+* option from @adonis/otel so we can remove this file in the future.
+*/
+var OtelProvider = class {
+	constructor(app) {
+		this.app = app;
+	}
+	/**
+	* Hook into ExceptionHandler to record exceptions in spans.
+	*
+	* We always record the exception on the span (for trace visibility), but we also
+	* add an attribute `monocle.exception.should_report` to indicate whether this
+	* exception should appear in the Exceptions dashboard.
+	*
+	* This respects the AdonisJS `ignoreExceptions`, `ignoreStatuses`, and `ignoreCodes`
+	* configuration from the ExceptionHandler.
+	*/
+	#registerExceptionHandler() {
+		const originalReport = ExceptionHandler.prototype.report;
+		ExceptionHandler.macro("report", async function(error, ctx) {
+			const span = getCurrentSpan();
+			if (span && error instanceof Error) {
+				span.recordException(error);
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: error.message
+				});
+				const httpError = this.toHttpError(error);
+				const shouldReport = this.shouldReport(httpError);
+				span.setAttribute("monocle.exception.should_report", shouldReport);
+			}
+			return originalReport.call(this, error, ctx);
+		});
+	}
+	register() {
+		this.#registerExceptionHandler();
+		this.#registerMiddleware();
+	}
+	/**
+	* Register the OtelMiddleware as a singleton in the container
+	*/
+	#registerMiddleware() {
+		this.app.container.singleton(OtelMiddleware, async () => {
+			const otelConfigProvider = this.app.config.get("monocle", {});
+			return new OtelMiddleware({ userContext: (await configProvider.resolve(this.app, otelConfigProvider))?.userContext });
+		});
+	}
+	/**
+	* Gracefully flush pending spans
+	*/
+	async shutdown() {
+		await OtelManager.getInstance()?.shutdown();
+	}
+};
+
+//#endregion
+export { OtelProvider as default };

package/dist/src/cli_instrumentation.mjs

@@ -0,0 +1,90 @@
+import { createRequire } from "node:module";
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+
+//#region src/cli_instrumentation.ts
+/**
+* Default commands to exclude from tracing.
+* These are typically scaffolding commands or long-running workers.
+*/
+const DEFAULT_EXCLUDE = [
+	"make:*",
+	"generate:*",
+	"queue:work",
+	"queue:listen"
+];
+/**
+* Simple glob pattern matcher supporting only '*' wildcard
+*/
+function matchPattern(commandName, pattern) {
+	if (pattern === "*") return true;
+	if (!pattern.includes("*")) return commandName === pattern;
+	return (/* @__PURE__ */ new RegExp(`^${pattern.replace(/\*/g, ".*")}$`)).test(commandName);
+}
+/**
+* Check if a command should be traced based on include/exclude patterns
+*/
+function shouldTraceCommand(commandName, config) {
+	if ((config.exclude ?? DEFAULT_EXCLUDE).some((pattern) => matchPattern(commandName, pattern))) return false;
+	if (config.include && config.include.length > 0) return config.include.some((pattern) => matchPattern(commandName, pattern));
+	return true;
+}
+/**
+* Instrument AdonisJS Ace CLI commands with OpenTelemetry tracing.
+*
+* Uses monkey-patching of BaseCommand.prototype.exec to wrap command
+* execution with an active OTEL span context. This ensures all child
+* spans created during command execution are properly linked to the
+* CLI command span.
+*
+* @param config - CLI tracing configuration
+* @param appRoot - Application root directory path
+*/
+async function instrumentCliCommands(config, appRoot) {
+	const tracer = trace.getTracer("@monocle.sh/adonisjs-agent", "1.0.0");
+	const BaseCommand = (await import(createRequire(appRoot ? `file://${appRoot}/package.json` : import.meta.url).resolve("@adonisjs/core/ace"))).BaseCommand;
+	const originalExec = BaseCommand.prototype.exec;
+	BaseCommand.prototype.exec = async function() {
+		const commandName = this.constructor.commandName;
+		const commandDescription = this.constructor.description;
+		if (!shouldTraceCommand(commandName, config)) return originalExec.call(this);
+		const span = tracer.startSpan(`cli ${commandName}`, {
+			kind: SpanKind.INTERNAL,
+			attributes: {
+				"entry_point.type": "cli",
+				"cli.command.name": commandName,
+				"cli.command.description": commandDescription || ""
+			}
+		});
+		const ctx = trace.setSpan(context.active(), span);
+		/**
+		* CRITICAL: Execute within context.with()
+		*
+		* This is what makes child spans work! Without this wrapper:
+		* - Child spans would have no parent
+		* - All spans would be root spans with different traceIds
+		* - The trace would be fragmented
+		*
+		* context.with() sets our span as the "active" span for all async
+		* operations within the callback, enabling proper trace propagation.
+		*/
+		return context.with(ctx, async () => {
+			try {
+				return await originalExec.call(this);
+			} catch (error) {
+				if (error instanceof Error) {
+					span.recordException(error);
+					span.setStatus({
+						code: SpanStatusCode.ERROR,
+						message: error.message
+					});
+				}
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
+	};
+}
+
+//#endregion
+export { instrumentCliCommands };

package/dist/src/define_config.d.mts

@@ -0,0 +1,12 @@
+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;
+//#endregion
+export { defineConfig };

package/dist/src/define_config.mjs

@@ -0,0 +1,72 @@
+//#region src/define_config.ts
+/**
+* Extracts a header value from either ServerResponse (getHeader) or IncomingMessage (headers object).
+*/
+function getHeader(response, name) {
+	if ("getHeader" in response && typeof response.getHeader === "function") {
+		const value = response.getHeader(name);
+		if (typeof value === "string") return value;
+	}
+	if ("headers" in response && response.headers) {
+		const value = response.headers[name];
+		if (typeof value === "string") return value;
+	}
+}
+/**
+* Detects the connection type based on response headers.
+* Returns 'sse' for Server-Sent Events, 'websocket' for WebSocket upgrades,
+* or undefined for standard HTTP connections.
+*/
+function detectConnectionType(response) {
+	if (getHeader(response, "content-type")?.includes("text/event-stream")) return "sse";
+	if (getHeader(response, "upgrade")?.toLowerCase() === "websocket") return "websocket";
+}
+/**
+* Creates a response hook that detects long-running HTTP connections
+* (SSE and WebSocket) and adds the `http.connection_type` attribute.
+*/
+function createConnectionTypeHook(userHook) {
+	return (span, response) => {
+		const connectionType = detectConnectionType(response);
+		if (connectionType) span.setAttribute("http.connection_type", connectionType);
+		userHook?.(span, response);
+	};
+}
+/**
+* Extracts the user-defined response hook from HTTP instrumentation config.
+*/
+function extractUserResponseHook(httpConfig) {
+	if (typeof httpConfig !== "object" || httpConfig === null) return;
+	if (!("responseHook" in httpConfig)) return;
+	return httpConfig.responseHook;
+}
+/**
+* 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 httpConfig = config.instrumentations?.["@opentelemetry/instrumentation-http"];
+	const userResponseHook = extractUserResponseHook(httpConfig);
+	const instrumentations = {
+		...config.instrumentations,
+		"@opentelemetry/instrumentation-http": {
+			...typeof httpConfig === "object" && httpConfig !== null ? httpConfig : {},
+			responseHook: createConnectionTypeHook(userResponseHook)
+		}
+	};
+	return {
+		...config,
+		endpoint,
+		environment,
+		instrumentations
+	};
+}
+
+//#endregion
+export { defineConfig };

package/dist/src/host_metrics.mjs

@@ -0,0 +1,27 @@
+import { metrics } from "@opentelemetry/api";
+import { HostMetrics } from "@opentelemetry/host-metrics";
+
+//#region src/host_metrics.ts
+let hostMetricsInstance = null;
+/**
+* Start collecting host metrics (CPU, Memory, Network, etc.)
+*
+* Uses @opentelemetry/host-metrics to collect:
+* - system.cpu.time / system.cpu.utilization
+* - system.memory.usage / system.memory.utilization
+* - system.network.io / system.network.errors / system.network.dropped
+* - process.cpu.time / process.cpu.utilization
+* - process.memory.usage
+*/
+function startHostMetrics(config = {}) {
+	if (hostMetricsInstance) return hostMetricsInstance;
+	hostMetricsInstance = new HostMetrics({
+		meterProvider: metrics.getMeterProvider(),
+		name: config.name || "monocle-host-metrics"
+	});
+	hostMetricsInstance.start();
+	return hostMetricsInstance;
+}
+
+//#endregion
+export { startHostMetrics };

package/dist/src/monocle.d.mts

@@ -0,0 +1,28 @@
+import { UserContextResult } from "@adonisjs/otel/types";
+
+//#region src/monocle.d.ts
+interface CaptureExceptionContext {
+  user?: {
+    id: string;
+    email?: string;
+    name?: string;
+  };
+  tags?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}
+/**
+ * Monocle helper class for manual instrumentation.
+ */
+declare class Monocle {
+  /**
+   * Capture an exception and record it on the current active span.
+   * If no span is active, the exception is silently ignored.
+   */
+  static captureException(error: unknown, context?: CaptureExceptionContext): void;
+  /**
+   * Set user information on the current active span.
+   */
+  static setUser(user: UserContextResult): void;
+}
+//#endregion
+export { Monocle };

package/dist/src/monocle.mjs

@@ -0,0 +1,39 @@
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { setUser } from "@adonisjs/otel/helpers";
+
+//#region src/monocle.ts
+/**
+* Monocle helper class for manual instrumentation.
+*/
+var Monocle = class {
+	/**
+	* Capture an exception and record it on the current active span.
+	* If no span is active, the exception is silently ignored.
+	*/
+	static captureException(error, context$1) {
+		const span = trace.getActiveSpan();
+		if (!span) return;
+		const err = error instanceof Error ? error : new Error(String(error));
+		span.recordException(err);
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: err.message
+		});
+		if (context$1?.user) {
+			if (context$1.user.id) span.setAttribute("user.id", context$1.user.id);
+			if (context$1.user.email) span.setAttribute("user.email", context$1.user.email);
+			if (context$1.user.name) span.setAttribute("user.name", context$1.user.name);
+		}
+		if (context$1?.tags) for (const [key, value] of Object.entries(context$1.tags)) span.setAttribute(`monocle.tag.${key}`, value);
+		if (context$1?.extra) for (const [key, value] of Object.entries(context$1.extra)) span.setAttribute(`monocle.extra.${key}`, JSON.stringify(value));
+	}
+	/**
+	* Set user information on the current active span.
+	*/
+	static setUser(user) {
+		setUser(user);
+	}
+};
+
+//#endregion
+export { Monocle };

package/dist/src/types.d.mts

@@ -0,0 +1,114 @@
+import { OtelConfig } from "@adonisjs/otel/types";
+
+//#region src/types.d.ts
+
+/**
+ * Configuration for CLI command tracing
+ */
+interface CliTracingConfig {
+  /**
+   * Enable CLI command tracing.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Commands to include in tracing. Supports glob patterns.
+   * If not specified, all commands are traced (except excluded ones).
+   * @example ['migration:*', 'db:*', 'my-custom:*']
+   */
+  include?: string[];
+  /**
+   * Commands to exclude from tracing. Supports glob patterns.
+   * @default ['make:*', 'generate:*', 'queue:work', 'queue:listen']
+   * @example ['make:*', 'generate:*']
+   */
+  exclude?: string[];
+}
+/**
+ * Configuration for host metrics collection
+ */
+interface HostMetricsConfig {
+  /**
+   * Enable host metrics collection.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Custom name for the meter.
+   * @default 'monocle-host-metrics'
+   */
+  name?: string;
+}
+/**
+ * Configuration for trace batching. Controls how spans are batched before export.
+ */
+interface BatchConfig {
+  /**
+   * Maximum number of spans to include in a single batch.
+   * @default 512
+   */
+  maxExportBatchSize?: number;
+  /**
+   * Maximum time (ms) to wait before exporting a batch.
+   * @default 5000
+   */
+  scheduledDelayMillis?: number;
+  /**
+   * Maximum time (ms) to wait for a batch export to complete.
+   * @default 30000
+   */
+  exportTimeoutMillis?: number;
+  /**
+   * Maximum queue size. Spans will be dropped if the queue is full.
+   * @default 2048
+   */
+  maxQueueSize?: number;
+}
+interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExporter'> {
+  /**
+   * Your Monocle API key. If not provided, telemetry will be disabled.
+   * Format: mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+   */
+  apiKey?: string;
+  /**
+   * Ignore OPTIONS (CORS preflight) requests.
+   * These requests are typically not useful for tracing.
+   * @default true
+   */
+  ignoreOptionsRequests?: boolean;
+  /**
+   * Monocle ingestion endpoint.
+   * @default 'https://ingest.monocle.sh'
+   */
+  endpoint?: string;
+  /**
+   * Environment name sent with telemetry data.
+   * @default process.env.NODE_ENV || 'development'
+   */
+  environment?: string;
+  /**
+   * Host metrics configuration (CPU, Memory, Network, etc.).
+   * Set to `false` to disable, or pass config object.
+   * @default { enabled: true }
+   */
+  hostMetrics?: false | HostMetricsConfig;
+  /**
+   * Trace batching configuration. Batching reduces network overhead
+   * by grouping multiple spans into single requests.
+   */
+  batch?: BatchConfig;
+  /**
+   * Enable gzip compression for OTLP exports.
+   * Reduces bandwidth usage significantly.
+   * @default true
+   */
+  compression?: boolean;
+  /**
+   * CLI command tracing configuration.
+   * Set to `false` to disable, or pass config object.
+   * @default false
+   */
+  cli?: false | CliTracingConfig;
+}
+//#endregion
+export { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig };

package/dist/stubs/config.stub

@@ -0,0 +1,13 @@
+{{{
+  exports({ to: app.configPath('monocle.ts') })
+}}}
+import { defineConfig } from '@monocle.sh/adonisjs-agent'
+import env from '#start/env'
+
+export default defineConfig({
+  apiKey: env.get('MONOCLE_API_KEY'),
+
+  serviceName: env.get('APP_NAME'),
+  serviceVersion: env.get('APP_VERSION'),
+  environment: env.get('APP_ENV'),
+})

package/dist/stubs/main.mjs

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

package/dist/stubs/main.ts

@@ -0,0 +1,4 @@
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+export const stubsRoot = dirname(fileURLToPath(import.meta.url))

package/dist/stubs/otel.stub

@@ -0,0 +1,12 @@
+{{{
+  exports({ to: app.makePath('otel.ts') })
+}}}
+/**
+ * Monocle agent initialization file.
+ *
+ * IMPORTANT: This file must be imported FIRST in bin/server.ts
+ * for auto-instrumentation to work correctly.
+ */
+import { init } from '@monocle.sh/adonisjs-agent/init'
+
+await init(import.meta.dirname)

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@monocle.sh/adonisjs-agent",
+  "version": "1.0.0-beta.4",
+  "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
+  "keywords": [
+    "adonisjs",
+    "monocle",
+    "observability",
+    "opentelemetry",
+    "tracing"
+  ],
+  "license": "ISC",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "dev": "./index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./init": {
+      "dev": "./src/init.ts",
+      "default": "./dist/init.mjs"
+    },
+    "./monocle_middleware": {
+      "dev": "./middleware/monocle_middleware.ts",
+      "default": "./dist/monocle_middleware.mjs"
+    },
+    "./monocle_provider": {
+      "dev": "./providers/monocle_provider.ts",
+      "default": "./dist/monocle_provider.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./init": "./dist/init.mjs",
+      "./monocle_middleware": "./dist/monocle_middleware.mjs",
+      "./monocle_provider": "./dist/monocle_provider.mjs",
+      "./package.json": "./package.json"
+    },
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "release": "release-it",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@adonisjs/otel": "1.1.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.2.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/host-metrics": "^0.38.0",
+    "@opentelemetry/sdk-metrics": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
+    "import-in-the-middle": "^2.0.1"
+  },
+  "devDependencies": {
+    "@adonisjs/core": "catalog:",
+    "@adonisjs/tsconfig": "catalog:",
+    "release-it": "^19.2.2"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^6.2.0 || ^7.0.0"
+  },
+  "packageManager": "pnpm@10.26.2"
+}