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

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

@@ -52,10 +52,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 +102,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/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.1",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",