@monocle.sh/adonisjs-agent 1.0.3 → 1.2.0

package/dist/ai.d.mts

@@ -0,0 +1,2 @@
+import { getConversationId, withConversationId } from "@monocle.sh/instrumentation-vercel-ai";
+export { getConversationId, withConversationId };

package/dist/ai.mjs

@@ -0,0 +1,2 @@
+import { getConversationId, withConversationId } from "@monocle.sh/instrumentation-vercel-ai";
+export { getConversationId, withConversationId };

package/dist/configure.mjs

@@ -10,7 +10,12 @@ async function configure(command) {
 	* Publish otel.ts at project root
 	*/
 	await codemods.makeUsingStub(stubsRoot, "otel.stub", {});
-	const serverFile = (await codemods.getTsMorphProject())?.getSourceFile(command.app.makePath("bin/server.ts"));
+	/**
+	* Add otel.ts import as the FIRST import in bin/server.ts
+	* This is critical for auto-instrumentation to work
+	*/
+	const project = await codemods.getTsMorphProject();
+	const serverFile = project?.getSourceFile(command.app.makePath("bin/server.ts"));
 	if (serverFile) {
 		const insertIndex = serverFile.getImportDeclarations()[0]?.getChildIndex() ?? 0;
 		serverFile.insertStatements(insertIndex, [
@@ -24,6 +29,23 @@ async function configure(command) {
 		await serverFile.save();
 	}
 	/**
+	* Add otel.ts import as the FIRST import in bin/console.ts
+	* Required for CLI command tracing to work
+	*/
+	const consoleFile = project?.getSourceFile(command.app.makePath("bin/console.ts"));
+	if (consoleFile) {
+		const insertIndex = consoleFile.getImportDeclarations()[0]?.getChildIndex() ?? 0;
+		consoleFile.insertStatements(insertIndex, [
+			"/**",
+			" * OpenTelemetry initialization - MUST be the first import",
+			" * @see https://opentelemetry.io/docs/languages/js/getting-started/nodejs/",
+			" */",
+			`import '../otel.js'`,
+			""
+		]);
+		await consoleFile.save();
+	}
+	/**
 	* Register the provider in adonisrc.ts
 	*/
 	await codemods.updateRcFile((rcFile) => {

package/dist/decorators.d.mts

@@ -1,14 +1,6 @@
-import { Attributes } from "@opentelemetry/api";
+import { SpanAllOptions, SpanOptions } from "./src/types/decorators.mjs";
 
 //#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.
  *
@@ -80,4 +72,4 @@ declare function span(options?: SpanOptions): (target: any, propertyKey: string,
  */
 declare function spanAll(options?: SpanAllOptions): <T extends new (...args: any[]) => any>(constructor: T) => T;
 //#endregion
-export { SpanAllOptions, SpanOptions, span, spanAll };
+export { span, spanAll };

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types.mjs";
+import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types/config.mjs";
 import { defineConfig } from "./src/define_config.mjs";
+import { SpanAllOptions, SpanOptions } from "./src/types/decorators.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";
+import { span, spanAll } from "./decorators.mjs";
 import { destinations } from "@adonisjs/otel";
 export { type BatchConfig, type CliTracingConfig, type HostMetricsConfig, Monocle, type MonocleConfig, type SpanAllOptions, type SpanOptions, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };

package/dist/init.mjs

@@ -23,6 +23,22 @@ async function init(dirname) {
 	const config = await loadConfig(join(dirname, "config/monocle.js"));
 	if (!config) return;
 	if (!OtelManager.isEnabled(config)) return;
+	/**
+	* AI SDK Instrumentation (Vercel AI SDK)
+	*
+	* Uses import-in-the-middle to hook the `ai` module BEFORE it's loaded.
+	* Must be registered before OtelManager.create() so the hook is in place.
+	* The SpanProcessor is added via config.spanProcessors.
+	*/
+	if (config.ai !== false) try {
+		const { VercelAiInstrumentation, VercelAiSpanProcessor } = await import("@monocle.sh/instrumentation-vercel-ai");
+		const aiOpts = typeof config.ai === "object" ? config.ai : {};
+		new VercelAiInstrumentation({
+			recordInputs: aiOpts.recordInputs,
+			recordOutputs: aiOpts.recordOutputs
+		}).enable();
+		config.spanProcessors = [...config.spanProcessors ?? [], new VercelAiSpanProcessor()];
+	} catch {}
 	const manager = OtelManager.create(config);
 	manager?.start();
 	const shutdown = async () => {
@@ -51,14 +67,14 @@ async function init(dirname) {
 	*
 	* 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`
+	* 2. Config must not have `cli: false` or `cli.enabled: false`
 	*
 	* @see ./cli_instrumentation.ts for implementation details
 	*/
 	const cliConfig = config.cli;
-	if (cliConfig !== false && cliConfig?.enabled) {
+	if (cliConfig !== false && cliConfig?.enabled !== false) {
 		const { instrumentCliCommands } = await import("./src/cli_instrumentation.mjs");
-		await instrumentCliCommands(cliConfig, dirname);
+		await instrumentCliCommands(cliConfig ?? {}, dirname);
 	}
 	/**
 	* Mail Instrumentation
@@ -87,6 +103,18 @@ async function init(dirname) {
 		await instrumentQueue(queueConfig ?? { enabled: true }, dirname);
 	}
 	/**
+	* BullMQ Instrumentation
+	*
+	* Automatically instruments bullmq if installed.
+	* Creates PRODUCER spans for dispatch and CONSUMER spans for execution,
+	* with configurable span link mode and queue time calculation.
+	*/
+	const bullmqConfig = config.bullmq;
+	if (bullmqConfig !== false) {
+		const { instrumentBullMQ } = await import("./src/instrumentations/bullmq/instrumentation.mjs");
+		await instrumentBullMQ(bullmqConfig);
+	}
+	/**
 	* Cache Instrumentation
 	*
 	* Automatically instruments @adonisjs/cache (bentocache) if installed.

package/dist/src/define_config.d.mts

@@ -1,4 +1,4 @@
-import { MonocleConfig } from "./types.mjs";
+import { MonocleConfig } from "./types/config.mjs";
 
 //#region src/define_config.d.ts
 /**

package/dist/src/define_config.mjs

@@ -20,30 +20,13 @@ function getHeader(response, name) {
 	}
 }
 /**
-* Returns the raw HTTP header string from a ServerResponse.
-* After `writeHead()` is called with inline headers, `getHeader()` returns
-* undefined. Node.js stores the serialized headers in `_header` which is
-* the only reliable way to read them after they've been flushed.
-*/
-function getRawHeader(response) {
-	const raw = response._header;
-	if (typeof raw === "string") return raw;
-}
-/**
 * Detects the connection type based on response headers.
 * Returns 'sse' for Server-Sent Events, 'websocket' for WebSocket upgrades,
 * or undefined for standard HTTP connections.
-*
-* Checks both `getHeader()` and the raw `_header` string to handle cases
-* where headers are passed inline to `writeHead()` (e.g. @hono/node-server).
 */
 function detectConnectionType(response) {
 	if (getHeader(response, "content-type")?.includes("text/event-stream")) return "sse";
 	if (getHeader(response, "upgrade")?.toLowerCase() === "websocket") return "websocket";
-	const raw = getRawHeader(response);
-	if (!raw) return;
-	if (raw.includes("text/event-stream")) return "sse";
-	if (raw.toLowerCase().includes("upgrade: websocket")) return "websocket";
 }
 /**
 * Creates a response hook that detects long-running HTTP connections
@@ -69,12 +52,18 @@ function extractUserResponseHook(httpConfig) {
 * 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 isDev = config.dev ?? process.env.NODE_ENV === "development";
+	if (!isDev && !config.apiKey) return;
+	if (isDev) process.env.OTEL_EXPORTER_OTLP_PROTOCOL = "http/json";
+	const endpoint = isDev ? config.endpoint || "http://localhost:4200" : config.endpoint || "https://ingest.monocle.sh";
 	const environment = config.environment || process.env.NODE_ENV || "development";
-	const compression = config.compression === false ? "none" : "gzip";
-	const batchConfig = {
+	const compression = isDev ? "none" : config.compression === false ? "none" : "gzip";
+	const devBatchConfig = {
 		...DEFAULT_BATCH_CONFIG,
+		scheduledDelayMillis: 100
+	};
+	const batchConfig = {
+		...isDev ? devBatchConfig : DEFAULT_BATCH_CONFIG,
 		...config.batch
 	};
 	const httpConfig = config.instrumentations?.["@opentelemetry/instrumentation-http"];
@@ -86,14 +75,13 @@ function defineConfig(config) {
 			responseHook: createConnectionTypeHook(userResponseHook)
 		}
 	};
+	const headers = { "x-monocle-env": environment };
+	if (config.apiKey) headers["x-api-key"] = config.apiKey;
 	const monocleDestination = destinations.otlp({
 		endpoint,
 		signals: "all",
 		compression,
-		headers: {
-			"x-api-key": config.apiKey,
-			"x-monocle-env": environment
-		},
+		headers,
 		maxExportBatchSize: batchConfig.maxExportBatchSize,
 		scheduledDelayMillis: batchConfig.scheduledDelayMillis,
 		exportTimeoutMillis: batchConfig.exportTimeoutMillis,

package/dist/src/instrumentations/bullmq/instrumentation.mjs

@@ -0,0 +1,15 @@
+//#region src/instrumentations/bullmq/instrumentation.ts
+/**
+* Auto-instruments BullMQ with OpenTelemetry spans for job
+* dispatch (PRODUCER) and execution (CONSUMER).
+*
+* Does nothing if `@monocle.sh/instrumentation-bullmq` is not installed.
+*/
+async function instrumentBullMQ(config) {
+	try {
+		const { BullMQInstrumentation } = await import("@monocle.sh/instrumentation-bullmq");
+		new BullMQInstrumentation(config).enable();
+	} catch {}
+}
+//#endregion
+export { instrumentBullMQ };

package/dist/src/monocle.d.mts

@@ -1,28 +1,6 @@
-import { UserContextResult } from "@adonisjs/otel/types";
+import { CaptureExceptionContext, CaptureMessageContext, MessageLevel, MonocleUser } from "./types/monocle.mjs";
 
 //#region src/monocle.d.ts
-type MessageLevel = 'debug' | 'info' | 'log' | 'warning' | 'error' | 'fatal';
-interface CaptureContext {
-  user?: {
-    id: string;
-    email?: string;
-    name?: string;
-  };
-  tags?: Record<string, string>;
-  extra?: Record<string, unknown>;
-}
-interface CaptureMessageContext extends CaptureContext {
-  level?: MessageLevel;
-}
-type CaptureExceptionContext = CaptureContext;
-/**
- * User information for tracing. When displayed in the Monocle UI,
- * `name` takes priority over `email` as the display label, with
- * `email` used as fallback.
- */
-interface MonocleUser extends UserContextResult {
-  name?: string;
-}
 /**
  * Monocle helper class for manual instrumentation.
  */
@@ -55,4 +33,4 @@ declare class Monocle {
   static setUser(user: MonocleUser): void;
 }
 //#endregion
-export { Monocle, MonocleUser };
+export { Monocle };

package/dist/src/{types.d.mts → types/config.d.mts}

@@ -1,7 +1,8 @@
+import { BullMQInstrumentationConfig } from "@monocle.sh/instrumentation-bullmq";
 import { BentoCacheInstrumentationConfig } from "@bentocache/otel/types";
 import { DestinationMap, OtelConfig } from "@adonisjs/otel/types";
 
-//#region src/types.d.ts
+//#region src/types/config.d.ts
 /**
  * Configuration for cache instrumentation
  */
@@ -30,7 +31,7 @@ interface MailInstrumentationConfig {
 interface CliTracingConfig {
   /**
    * Enable CLI command tracing.
-   * @default false
+   * @default true
    */
   enabled?: boolean;
   /**
@@ -86,7 +87,29 @@ interface BatchConfig {
    */
   maxQueueSize?: number;
 }
+/**
+ * Configuration for AI SDK instrumentation
+ */
+interface AiInstrumentationConfig {
+  /**
+   * Record prompt/input data in span attributes.
+   * @default true
+   */
+  recordInputs?: boolean;
+  /**
+   * Record response/output data in span attributes.
+   * @default true
+   */
+  recordOutputs?: boolean;
+}
+type BullMQAgentConfig = BullMQInstrumentationConfig;
 interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExporter'> {
+  /**
+   * Enable local DevTools mode.
+   * Sends telemetry to Monocle DevTools (localhost:4200) with no compression.
+   * No API key required.
+   */
+  dev?: boolean;
   /**
    * Your Monocle API key. If not provided, telemetry will be disabled.
    * Format: mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -134,7 +157,7 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
   /**
    * CLI command tracing configuration.
    * Set to `false` to disable, or pass config object.
-   * @default false
+   * @default { enabled: true, exclude: ['make:*', 'generate:*', 'queue:work', 'queue:listen'] }
    */
   cli?: false | CliTracingConfig;
   /**
@@ -158,6 +181,20 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * @default { enabled: true }
    */
   queue?: false | QueueInstrumentationConfig;
+  /**
+   * BullMQ instrumentation configuration.
+   * Automatically instruments BullMQ if installed.
+   * Set to `false` to disable.
+   * @default { enabled: true }
+   */
+  bullmq?: false | BullMQAgentConfig;
+  /**
+   * AI SDK instrumentation configuration.
+   * Automatically instruments the Vercel AI SDK (`ai` package) if installed.
+   * Set to `false` to disable.
+   * @default { enabled: true }
+   */
+  ai?: false | AiInstrumentationConfig;
 }
 //#endregion
 export { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig };

package/dist/src/types/decorators.d.mts

@@ -0,0 +1,13 @@
+import { Attributes } from "@opentelemetry/api";
+
+//#region src/types/decorators.d.ts
+interface SpanOptions {
+  name?: string;
+  attributes?: Attributes;
+}
+interface SpanAllOptions {
+  prefix?: string;
+  attributes?: Attributes;
+}
+//#endregion
+export { SpanAllOptions, SpanOptions };

package/dist/src/types/main.d.mts

@@ -0,0 +1,3 @@
+import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./config.mjs";
+import { SpanAllOptions, SpanOptions } from "./decorators.mjs";
+import { CaptureContext, CaptureExceptionContext, CaptureMessageContext, MessageLevel, MonocleUser } from "./monocle.mjs";

package/dist/src/types/monocle.d.mts

@@ -0,0 +1,27 @@
+import { UserContextResult } from "@adonisjs/otel/types";
+
+//#region src/types/monocle.d.ts
+type MessageLevel = 'debug' | 'info' | 'log' | 'warning' | 'error' | 'fatal';
+interface CaptureContext {
+  user?: {
+    id: string;
+    email?: string;
+    name?: string;
+  };
+  tags?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}
+interface CaptureMessageContext extends CaptureContext {
+  level?: MessageLevel;
+}
+type CaptureExceptionContext = CaptureContext;
+/**
+ * User information for tracing. When displayed in the Monocle UI,
+ * `name` takes priority over `email` as the display label, with
+ * `email` used as fallback.
+ */
+interface MonocleUser extends UserContextResult {
+  name?: string;
+}
+//#endregion
+export { CaptureContext, CaptureExceptionContext, CaptureMessageContext, MessageLevel, MonocleUser };

package/dist/types.d.mts

@@ -1,5 +1,5 @@
-import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types.mjs";
-import { MonocleUser } from "./src/monocle.mjs";
-import { SpanAllOptions, SpanOptions } from "./decorators.mjs";
+import { BatchConfig, CliTracingConfig, HostMetricsConfig, MonocleConfig } from "./src/types/config.mjs";
+import { SpanAllOptions, SpanOptions } from "./src/types/decorators.mjs";
+import { MonocleUser } from "./src/types/monocle.mjs";
 import { DestinationConfig, DestinationMap, DestinationSignal, DestinationSignals, HeadersCarrier, OtelLoggingPresetOptions, OtlpDestinationConfig, OtlpDestinationOptions, UserContextResult } from "@adonisjs/otel/types";
 export { type BatchConfig, type CliTracingConfig, type DestinationConfig, type DestinationMap, type DestinationSignal, type DestinationSignals, type HeadersCarrier, type HostMetricsConfig, type MonocleConfig, type MonocleUser, type OtelLoggingPresetOptions, type OtlpDestinationConfig, type OtlpDestinationOptions, type SpanAllOptions, type SpanOptions, type UserContextResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/adonisjs-agent",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",
@@ -24,6 +24,7 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
+    "./ai": "./dist/ai.mjs",
     "./decorators": "./dist/decorators.mjs",
     "./helpers": "./dist/helpers.mjs",
     "./init": "./dist/init.mjs",
@@ -52,8 +53,10 @@
     "@sindresorhus/is": "^7.2.0",
     "error-stack-parser-es": "^1.0.5",
     "import-in-the-middle": "^3.0.0",
+    "@monocle.sh/instrumentation-bullmq": "^0.2.0",
     "@monocle.sh/instrumentation-mcp": "^1.0.0",
-    "@monocle.sh/otel-utils": "^1.0.0"
+    "@monocle.sh/instrumentation-vercel-ai": "^1.1.0",
+    "@monocle.sh/otel-utils": "^1.0.1"
   },
   "devDependencies": {
     "@adonisjs/core": "^7.1.1",