@monocle-app/agent 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -1,3 +1,133 @@
 # @monocle-app/agent
 
-TODO.
+Monocle agent for AdonisJS - sends telemetry to Monocle cloud.
+
+## Installation
+
+```bash
+npm install @monocle-app/agent
+# or
+yarn add @monocle-app/agent
+# or
+pnpm add @monocle-app/agent
+```
+
+## Configuration
+
+Run the configure command to set up the agent automatically:
+
+```bash
+node ace configure @monocle-app/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-app/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-app/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-app/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-app/agent/monocle_provider");
+	});
+	/**
+	* Register the middleware as FIRST router middleware
+	*/
+	await codemods.registerMiddleware("router", [{
+		path: "@monocle-app/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

@@ -1,4 +1,5 @@
 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 };
+import { configure } from "./configure.mjs";
+export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, configure, defineConfig };

package/dist/index.mjs

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

package/dist/init.mjs

@@ -1,4 +1,5 @@
 import { register } from "node:module";
+import { pathToFileURL } from "node:url";
 import { join } from "node:path";
 import { createAddHookMessageChannel } from "import-in-the-middle";
 
@@ -14,8 +15,8 @@ const DEFAULT_BATCH_CONFIG = {
 	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}`);
+	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() {
@@ -52,10 +53,10 @@ async function createSpanProcessor(config) {
 		maxQueueSize: batchConfig.maxQueueSize
 	});
 }
-async function init(dirname) {
+async function init(dirname$1) {
 	const waitForAllMessagesAcknowledged = setupHooks();
 	const { OtelManager } = await import("@adonisjs/otel/manager");
-	const config = await loadConfig(join(dirname, "config/monocle.js"));
+	const config = await loadConfig(join(dirname$1, "config/monocle.js"));
 	if (!config) return;
 	if (!OtelManager.isEnabled(config)) return;
 	const metricReader = await createMetricReader(config);
@@ -102,7 +103,7 @@ async function init(dirname) {
 	const cliConfig = config.cli;
 	if (cliConfig !== false && cliConfig?.enabled) {
 		const { instrumentCliCommands } = await import("./src/cli_instrumentation.mjs");
-		await instrumentCliCommands(cliConfig, dirname);
+		await instrumentCliCommands(cliConfig, dirname$1);
 	}
 	await waitForAllMessagesAcknowledged();
 }

package/dist/monocle_provider.mjs

@@ -1,6 +1,6 @@
 import { SpanStatusCode } from "@opentelemetry/api";
-import OtelMiddleware from "@adonisjs/otel/otel_middleware";
 import { getCurrentSpan } from "@adonisjs/otel/helpers";
+import OtelMiddleware from "@adonisjs/otel/otel_middleware";
 import { OtelManager } from "@adonisjs/otel";
 import { ExceptionHandler } from "@adonisjs/core/http";
 import { configProvider } from "@adonisjs/core";

package/dist/src/monocle.d.mts

@@ -1,3 +1,5 @@
+import { UserContextResult } from "@adonisjs/otel/types";
+
 //#region src/monocle.d.ts
 interface CaptureExceptionContext {
   user?: {
@@ -20,11 +22,7 @@ declare class Monocle {
   /**
    * Set user information on the current active span.
    */
-  static setUser(user: {
-    id: string;
-    email?: string;
-    name?: string;
-  }): void;
+  static setUser(user: UserContextResult): void;
 }
 //#endregion
 export { Monocle };

package/dist/src/monocle.mjs

@@ -1,4 +1,5 @@
 import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { setUser } from "@adonisjs/otel/helpers";
 
 //#region src/monocle.ts
 /**
@@ -30,11 +31,7 @@ var Monocle = class {
 	* 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);
+		setUser(user);
 	}
 };
 

package/dist/src/types.d.mts

@@ -70,6 +70,12 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * 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.adonisjs.com'

package/dist/stubs/config.stub

@@ -0,0 +1,13 @@
+{{{
+  exports({ to: app.configPath('monocle.ts') })
+}}}
+import { defineConfig } from '@monocle-app/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-app/agent/init'
+
+await init(import.meta.dirname)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle-app/agent",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",
@@ -11,13 +11,13 @@
   ],
   "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",
-  "files": [
-    "dist"
-  ],
   "exports": {
     ".": {
       "dev": "./index.ts",
@@ -38,7 +38,6 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "tag": "beta",
     "access": "public",
     "exports": {
       ".": "./dist/index.mjs",
@@ -46,7 +45,8 @@
       "./monocle_middleware": "./dist/monocle_middleware.mjs",
       "./monocle_provider": "./dist/monocle_provider.mjs",
       "./package.json": "./package.json"
-    }
+    },
+    "tag": "beta"
   },
   "scripts": {
     "build": "tsdown",
@@ -56,13 +56,15 @@
     "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
-    "@adonisjs/otel": "1.0.0",
+    "@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": {
@@ -73,5 +75,5 @@
   "peerDependencies": {
     "@adonisjs/core": "^6.2.0 || ^7.0.0"
   },
-  "packageManager": "pnpm@10.26.1"
+  "packageManager": "pnpm@10.26.2"
 }