@monocle-app/agent 1.0.0-beta.0

package/README.md

@@ -0,0 +1,3 @@
+# @monocle-app/agent
+
+TODO.

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types.mjs";
+import { defineConfig } from "./src/define_config.mjs";
+import { Monocle } from "./src/monocle.mjs";
+export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, defineConfig };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { defineConfig } from "./src/define_config.mjs";
+import { Monocle } from "./src/monocle.mjs";
+
+export { Monocle, 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,111 @@
+import { register } from "node:module";
+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(path).then((mod) => mod.default || mod).catch((error) => {
+		throw new Error(`Failed to load Monocle config file at "${path}": ${error.message}`);
+	});
+}
+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: 15e3
+	});
+}
+/**
+* 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(() => {
+			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);
+	}
+	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,56 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+import OtelMiddleware from "@adonisjs/otel/otel_middleware";
+import { getCurrentSpan } from "@adonisjs/otel/helpers";
+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
+	*/
+	#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
+				});
+			}
+			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-app/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,21 @@
+//#region src/define_config.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).
+*/
+function defineConfig(config) {
+	if (!config.apiKey) return void 0;
+	const endpoint = config.endpoint || "https://ingest.monocle.adonisjs.com";
+	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}`;
+	return {
+		...config,
+		endpoint,
+		environment
+	};
+}
+
+//#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,30 @@
+//#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: {
+    id: string;
+    email?: string;
+    name?: string;
+  }): void;
+}
+//#endregion
+export { Monocle };

package/dist/src/monocle.mjs

@@ -0,0 +1,42 @@
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+//#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) {
+		const span = trace.getActiveSpan();
+		if (!span) return;
+		span.setAttribute("user.id", user.id);
+		if (user.email) span.setAttribute("user.email", user.email);
+		if (user.name) span.setAttribute("user.name", user.name);
+	}
+};
+
+//#endregion
+export { Monocle };

package/dist/src/types.d.mts

@@ -0,0 +1,108 @@
+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;
+  /**
+   * Monocle ingestion endpoint.
+   * @default 'https://ingest.monocle.adonisjs.com'
+   */
+  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/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@monocle-app/agent",
+  "version": "1.0.0-beta.0",
+  "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
+  "keywords": [
+    "adonisjs",
+    "monocle",
+    "observability",
+    "opentelemetry",
+    "tracing"
+  ],
+  "license": "ISC",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "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": {
+    "tag": "beta",
+    "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"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "release": "release-it",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@adonisjs/otel": "1.0.0",
+    "@opentelemetry/api": "^1.9.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",
+    "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.1"
+}