@monocle.sh/adonisjs-agent 1.3.1 → 1.4.0

package/dist/index.d.mts

@@ -4,4 +4,5 @@ import { configure } from "./configure.mjs";
 import { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes } from "./helpers.mjs";
 import { span, spanAll } from "./decorators.mjs";
 import { destinations } from "@adonisjs/otel";
-export { Monocle, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };
+import { Sample } from "@monocle.sh/otel-utils";
+export { Monocle, Sample, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };

package/dist/index.mjs

@@ -4,4 +4,5 @@ import { configure } from "./configure.mjs";
 import { extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes } from "./helpers.mjs";
 import { span, spanAll } from "./decorators.mjs";
 import { destinations } from "@adonisjs/otel";
-export { Monocle, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };
+import { Sample } from "@monocle.sh/otel-utils";
+export { Monocle, Sample, configure, defineConfig, destinations, extractTraceContext, getCurrentSpan, handleError, injectTraceContext, otelLoggingPreset, record, recordEvent, setAttributes, span, spanAll };

package/dist/init.mjs

@@ -17,6 +17,17 @@ function setupHooks() {
 	register("import-in-the-middle/hook.mjs", import.meta.url, registerOptions);
 	return waitForAllMessagesAcknowledged;
 }
+function moveSamplingProcessorLast(config) {
+	const processors = config.spanProcessors;
+	if (!processors) return;
+	const samplingProcessors = processors.filter((processor) => {
+		return processor.constructor.name === "SamplingSpanProcessor";
+	});
+	if (samplingProcessors.length === 0) return;
+	config.spanProcessors = [...processors.filter((processor) => {
+		return processor.constructor.name !== "SamplingSpanProcessor";
+	}), ...samplingProcessors];
+}
 async function init(dirname) {
 	const waitForAllMessagesAcknowledged = setupHooks();
 	const { OtelManager } = await import("@adonisjs/otel/manager");
@@ -39,6 +50,25 @@ async function init(dirname) {
 		}).enable();
 		config.spanProcessors = [...config.spanProcessors ?? [], new VercelAiSpanProcessor()];
 	} catch {}
+	/**
+	* Mastra Instrumentation
+	*
+	* Mastra already emits OpenTelemetry spans through @mastra/otel-bridge.
+	* This processor normalizes Mastra GenAI attributes to the fields consumed by
+	* Monocle AI monitoring.
+	*/
+	if (config.mastra !== false) try {
+		const { MastraSpanProcessor } = await import("@monocle.sh/instrumentation-mastra");
+		const aiOpts = typeof config.ai === "object" ? config.ai : {};
+		const mastraOpts = typeof config.mastra === "object" ? config.mastra : {};
+		const mastraProcessorConfig = {
+			recordInputs: aiOpts.recordInputs,
+			recordOutputs: aiOpts.recordOutputs,
+			...mastraOpts
+		};
+		config.spanProcessors = [...config.spanProcessors ?? [], new MastraSpanProcessor(mastraProcessorConfig)];
+	} catch {}
+	moveSamplingProcessorLast(config);
 	const manager = OtelManager.create(config);
 	manager?.start();
 	const shutdown = async () => {
@@ -112,7 +142,10 @@ async function init(dirname) {
 	const bullmqConfig = config.bullmq;
 	if (bullmqConfig !== false) {
 		const { instrumentBullMQ } = await import("./src/instrumentations/bullmq/instrumentation.mjs");
-		await instrumentBullMQ(bullmqConfig);
+		await instrumentBullMQ({
+			...bullmqConfig,
+			sampling: config.sampling
+		});
 	}
 	/**
 	* Cache Instrumentation

package/dist/sampling.d.mts

@@ -0,0 +1,2 @@
+export * from "@monocle.sh/otel-utils/sampling";
+export * from "@monocle.sh/otel-utils/types/sampling";

package/dist/sampling.mjs

@@ -0,0 +1,2 @@
+export * from "@monocle.sh/otel-utils/sampling";
+export {};

package/dist/src/define_config.mjs

@@ -1,5 +1,7 @@
 import { buildHttpInstrumentationConfig } from "./http_instrumentation_config.mjs";
+import { AdonisSamplingDestinations } from "./sampling_destinations.mjs";
 import { destinations } from "@adonisjs/otel";
+import { SamplingActivationSpanProcessor, defaultJobSamplingContextExtractor } from "@monocle.sh/otel-utils/sampling";
 //#region src/define_config.ts
 const DEFAULT_BATCH_CONFIG = {
 	maxExportBatchSize: 512,
@@ -8,7 +10,7 @@ const DEFAULT_BATCH_CONFIG = {
 	maxQueueSize: 2048
 };
 function resolveSdkVersion() {
-	return "1.3.1";
+	return "1.4.0";
 }
 function buildNodejsResourceAttributes() {
 	const attributes = {
@@ -19,6 +21,17 @@ function buildNodejsResourceAttributes() {
 	if (sdkVersion) attributes["telemetry.sdk.version"] = sdkVersion;
 	return attributes;
 }
+function createSamplingActivationProcessor(config) {
+	return new SamplingActivationSpanProcessor({
+		sampling: config.sampling,
+		extractor(span) {
+			const context = defaultJobSamplingContextExtractor(span);
+			if (!context) return;
+			if (context.system === "bullmq" && config.bullmq !== false) return;
+			return context;
+		}
+	});
+}
 /**
 * Define and validate Monocle agent configuration.
 * Returns undefined if no API key is provided (telemetry will be disabled).
@@ -59,16 +72,27 @@ function defineConfig(config) {
 		exportTimeoutMillis: batchConfig.exportTimeoutMillis,
 		maxQueueSize: batchConfig.maxQueueSize
 	});
+	const destinationMap = {
+		...config.destinations,
+		monocle: monocleDestination
+	};
+	const samplingDestinations = new AdonisSamplingDestinations(destinationMap);
+	const spanProcessors = config.sampling ? [
+		...config.spanProcessors ?? [],
+		createSamplingActivationProcessor(config),
+		samplingDestinations.createSpanProcessor()
+	] : config.spanProcessors;
+	const resolvedDestinations = config.sampling ? samplingDestinations.stripTraceSignals() : destinationMap;
+	const samplingRatio = config.sampling && !config.sampler ? 1 : config.samplingRatio;
 	return {
 		...config,
 		endpoint,
 		environment,
+		samplingRatio,
 		resourceAttributes,
 		instrumentations,
-		destinations: {
-			...config.destinations,
-			monocle: monocleDestination
-		}
+		spanProcessors,
+		destinations: resolvedDestinations
 	};
 }
 //#endregion

package/dist/src/sampling_destinations.mjs

@@ -0,0 +1,80 @@
+import { SamplingSpanProcessor } from "@monocle.sh/otel-utils/sampling";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/sampling_destinations.ts
+/**
+* Normalizes Adonis OTEL destination signal declarations.
+*/
+function signalSet(signals) {
+	if (signals === "all") return new Set([
+		"traces",
+		"metrics",
+		"logs"
+	]);
+	return new Set(signals);
+}
+/**
+* Builds sampling-aware processors from Adonis OTEL destinations.
+*
+* This stays in the Adonis agent because the destination schema comes from
+* `@adonisjs/otel`. Other framework agents can provide their own adapter and
+* still reuse `SamplingSpanProcessor` from `@monocle.sh/otel-utils/sampling`.
+*/
+var AdonisSamplingDestinations = class {
+	#destinations;
+	constructor(destinations) {
+		this.#destinations = destinations;
+	}
+	/**
+	* Returns destinations with trace export removed.
+	*/
+	stripTraceSignals() {
+		const result = {};
+		for (const [key, destination] of Object.entries(this.#destinations)) {
+			const stripped = this.#removeTraceSignal(destination);
+			if (stripped) result[key] = stripped;
+		}
+		return result;
+	}
+	/**
+	* Creates a sampling processor that forwards accepted traces to the original
+	* trace destinations.
+	*/
+	createSpanProcessor() {
+		return new SamplingSpanProcessor(Object.values(this.#destinations).filter((destination) => destination.enabled && this.#hasTraceSignal(destination)).map((destination) => this.#createTraceProcessor(destination)));
+	}
+	#hasTraceSignal(destination) {
+		return signalSet(destination.signals).has("traces");
+	}
+	#resolveTraceEndpoint(destination) {
+		const traceEndpoint = destination.endpoints?.traces;
+		if (traceEndpoint) return traceEndpoint;
+		if (destination.endpoint) return `${destination.endpoint.replace(/\/$/, "")}/v1/traces`;
+	}
+	#createTraceProcessor(destination) {
+		const url = this.#resolveTraceEndpoint(destination);
+		return new BatchSpanProcessor(new OTLPTraceExporter({
+			...url && { url },
+			...destination.headers && { headers: destination.headers },
+			...destination.timeoutMillis !== void 0 && { timeoutMillis: destination.timeoutMillis },
+			...destination.concurrencyLimit !== void 0 && { concurrencyLimit: destination.concurrencyLimit },
+			...destination.compression !== void 0 && { compression: destination.compression }
+		}), {
+			...destination.maxExportBatchSize !== void 0 && { maxExportBatchSize: destination.maxExportBatchSize },
+			...destination.scheduledDelayMillis !== void 0 && { scheduledDelayMillis: destination.scheduledDelayMillis },
+			...destination.exportTimeoutMillis !== void 0 && { exportTimeoutMillis: destination.exportTimeoutMillis },
+			...destination.maxQueueSize !== void 0 && { maxQueueSize: destination.maxQueueSize }
+		});
+	}
+	#removeTraceSignal(destination) {
+		if (!this.#hasTraceSignal(destination)) return destination;
+		const signals = [...signalSet(destination.signals)].filter((signal) => signal !== "traces");
+		if (signals.length === 0) return;
+		return {
+			...destination,
+			signals
+		};
+	}
+};
+//#endregion
+export { AdonisSamplingDestinations };

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

@@ -1,7 +1,8 @@
-import { HttpBodyCaptureConfig, HttpUrlSanitizationConfig } from "@monocle.sh/otel-utils";
+import { HttpBodyCaptureConfig, HttpUrlSanitizationConfig, SamplingConfig } from "@monocle.sh/otel-utils";
 import { BentoCacheInstrumentationConfig } from "@bentocache/otel/types";
 import { DestinationMap, HttpInstrumentationConfig, InstrumentationsConfig, OtelConfig } from "@adonisjs/otel/types";
 import { BullMQInstrumentationConfig } from "@monocle.sh/instrumentation-bullmq";
+import { MastraSpanProcessorConfig } from "@monocle.sh/instrumentation-mastra";
 
 //#region src/types/config.d.ts
 /**
@@ -104,6 +105,7 @@ interface AiInstrumentationConfig {
   recordOutputs?: boolean;
 }
 type BullMQAgentConfig = BullMQInstrumentationConfig;
+type MastraAgentConfig = MastraSpanProcessorConfig;
 /**
  * Extended HTTP instrumentation config consumed by the Monocle agent.
  */
@@ -184,6 +186,15 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * by grouping multiple spans into single requests.
    */
   batch?: BatchConfig;
+  /**
+   * Trace sampling callback. Use this to sample specific jobs, commands,
+   * or HTTP requests with Monocle's `Sample` helper.
+   *
+   * When enabled, the agent records traces locally before deciding whether to
+   * export them. Do not combine this option with head sampling unless you know
+   * errors dropped by the head sampler cannot be recovered.
+   */
+  sampling?: SamplingConfig;
   /**
    * Enable gzip compression for OTLP exports.
    * Reduces bandwidth usage significantly.
@@ -231,6 +242,13 @@ interface MonocleConfig extends Omit<OtelConfig, 'traceExporter' | 'metricExport
    * @default { enabled: true }
    */
   ai?: false | AiInstrumentationConfig;
+  /**
+   * Mastra instrumentation configuration.
+   * Normalizes spans emitted by Mastra's OtelBridge for Monocle AI monitoring.
+   * Set to `false` to disable.
+   * @default { enabled: true }
+   */
+  mastra?: false | MastraAgentConfig;
 }
 //#endregion
-export { AiInstrumentationConfig, BatchConfig, BullMQAgentConfig, CacheInstrumentationConfig, CliTracingConfig, HostMetricsConfig, MailInstrumentationConfig, MonocleConfig, MonocleHttpInstrumentationConfig, MonocleInstrumentationsConfig, QueueInstrumentationConfig };
+export { AiInstrumentationConfig, BatchConfig, BullMQAgentConfig, CacheInstrumentationConfig, CliTracingConfig, HostMetricsConfig, MailInstrumentationConfig, MastraAgentConfig, MonocleConfig, MonocleHttpInstrumentationConfig, MonocleInstrumentationsConfig, QueueInstrumentationConfig };

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

@@ -1,11 +1,11 @@
-import { AiInstrumentationConfig, BatchConfig, BullMQAgentConfig, CacheInstrumentationConfig, CliTracingConfig, HostMetricsConfig, MailInstrumentationConfig, MonocleConfig, MonocleHttpInstrumentationConfig, MonocleInstrumentationsConfig, QueueInstrumentationConfig } from "./config.mjs";
+import { AiInstrumentationConfig, BatchConfig, BullMQAgentConfig, CacheInstrumentationConfig, CliTracingConfig, HostMetricsConfig, MailInstrumentationConfig, MastraAgentConfig, MonocleConfig, MonocleHttpInstrumentationConfig, MonocleInstrumentationsConfig, QueueInstrumentationConfig } from "./config.mjs";
 import { CaptureContext, CaptureExceptionContext, CaptureMessageContext, MessageLevel, MonocleUser } from "./monocle.mjs";
 import { SpanAllOptions, SpanOptions } from "./decorators.mjs";
 export * from "@monocle.sh/otel-utils";
 
 //#region src/types/main.d.ts
 declare namespace main_d_exports {
-  export { AiInstrumentationConfig, BatchConfig, BullMQAgentConfig, CacheInstrumentationConfig, CaptureContext, CaptureExceptionContext, CaptureMessageContext, CliTracingConfig, HostMetricsConfig, MailInstrumentationConfig, MessageLevel, MonocleConfig, MonocleHttpInstrumentationConfig, MonocleInstrumentationsConfig, MonocleUser, QueueInstrumentationConfig, SpanAllOptions, SpanOptions };
+  export { AiInstrumentationConfig, BatchConfig, BullMQAgentConfig, CacheInstrumentationConfig, CaptureContext, CaptureExceptionContext, CaptureMessageContext, CliTracingConfig, HostMetricsConfig, MailInstrumentationConfig, MastraAgentConfig, MessageLevel, MonocleConfig, MonocleHttpInstrumentationConfig, MonocleInstrumentationsConfig, MonocleUser, QueueInstrumentationConfig, SpanAllOptions, SpanOptions };
 }
 import * as import__monocle_sh_otel_utils from "@monocle.sh/otel-utils";
 //#endregion

package/dist/types/sampling.d.mts

@@ -0,0 +1,2 @@
+import { CommandSamplingContext, HttpSamplingContext, JobSamplingContext, JobSamplingContextExtractor, KeepErrorsOptions, SamplingConfig, SamplingContext, SamplingDecision, SamplingKind, SamplingRule, SamplingRuleKind } from "@monocle.sh/otel-utils/types/sampling";
+export { type CommandSamplingContext, type HttpSamplingContext, type JobSamplingContext, type JobSamplingContextExtractor, type KeepErrorsOptions, type SamplingConfig, type SamplingContext, type SamplingDecision, type SamplingKind, type SamplingRule, type SamplingRuleKind };

package/dist/types/sampling.mjs

@@ -0,0 +1 @@
+export {};

package/dist/types.d.mts

@@ -11,4 +11,8 @@ type HttpBodyRedactionConfig = main_d_exports.HttpBodyRedactionConfig;
 type HttpBodyRedactor = main_d_exports.HttpBodyRedactor;
 type HttpUrlSanitizationConfig = main_d_exports.HttpUrlSanitizationConfig;
 type HttpUrlSanitizerHook = main_d_exports.HttpUrlSanitizerHook;
-export { type BatchConfig, type CliTracingConfig, type DestinationConfig, type DestinationMap, type DestinationSignal, type DestinationSignals, type HeadersCarrier, type HostMetricsConfig, type HttpBodyCaptureConfig, type HttpBodyCaptureSideConfig, type HttpBodyInfo, type HttpBodyKind, type HttpBodyRedactionConfig, type HttpBodyRedactor, type HttpUrlSanitizationConfig, type HttpUrlSanitizerHook, type MonocleConfig, type MonocleHttpInstrumentationConfig, type MonocleInstrumentationsConfig, type MonocleUser, type OtelLoggingPresetOptions, type OtlpDestinationConfig, type OtlpDestinationOptions, type SpanAllOptions, type SpanOptions, type UserContextResult };
+type SamplingConfig = main_d_exports.SamplingConfig;
+type SamplingContext = main_d_exports.SamplingContext;
+type SamplingDecision = main_d_exports.SamplingDecision;
+type SamplingRule = main_d_exports.SamplingRule;
+export { type BatchConfig, type CliTracingConfig, type DestinationConfig, type DestinationMap, type DestinationSignal, type DestinationSignals, type HeadersCarrier, type HostMetricsConfig, type HttpBodyCaptureConfig, type HttpBodyCaptureSideConfig, type HttpBodyInfo, type HttpBodyKind, type HttpBodyRedactionConfig, type HttpBodyRedactor, type HttpUrlSanitizationConfig, type HttpUrlSanitizerHook, type MonocleConfig, type MonocleHttpInstrumentationConfig, type MonocleInstrumentationsConfig, type MonocleUser, type OtelLoggingPresetOptions, type OtlpDestinationConfig, type OtlpDestinationOptions, type SamplingConfig, type SamplingContext, type SamplingDecision, type SamplingRule, type SpanAllOptions, type SpanOptions, type UserContextResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/adonisjs-agent",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Monocle agent for AdonisJS - sends telemetry to Monocle cloud",
   "keywords": [
     "adonisjs",
@@ -31,7 +31,9 @@
     "./mcp": "./dist/mcp.mjs",
     "./monocle_middleware": "./dist/monocle_middleware.mjs",
     "./monocle_provider": "./dist/monocle_provider.mjs",
+    "./sampling": "./dist/sampling.mjs",
     "./types": "./dist/types.mjs",
+    "./types/sampling": "./dist/types/sampling.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -42,32 +44,33 @@
     "@adonisjs/otel": "^1.2.3",
     "@bentocache/otel": "^0.1.2",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.214.0",
-    "@opentelemetry/core": "^2.6.1",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/api-logs": "^0.216.0",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.216.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.216.0",
     "@opentelemetry/host-metrics": "^0.38.3",
-    "@opentelemetry/instrumentation": "^0.214.0",
-    "@opentelemetry/sdk-metrics": "^2.6.1",
-    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/instrumentation": "^0.216.0",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@sindresorhus/is": "^7.2.0",
     "error-stack-parser-es": "^1.0.5",
-    "import-in-the-middle": "^3.0.0",
-    "@monocle.sh/instrumentation-bullmq": "^0.3.1",
+    "import-in-the-middle": "^3.0.1",
+    "@monocle.sh/instrumentation-bullmq": "^0.4.0",
+    "@monocle.sh/instrumentation-mastra": "^0.2.0",
     "@monocle.sh/instrumentation-mcp": "^1.0.1",
-    "@monocle.sh/instrumentation-vercel-ai": "^1.1.2",
-    "@monocle.sh/otel-utils": "^1.1.1"
+    "@monocle.sh/instrumentation-vercel-ai": "^1.1.3",
+    "@monocle.sh/otel-utils": "^1.2.0"
   },
   "devDependencies": {
-    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/core": "^7.3.2",
     "@adonisjs/tsconfig": "^2.0.0",
     "@japa/assert": "^4.2.0",
     "@japa/file-system": "^3.0.0",
     "@japa/runner": "^5.3.0",
     "@japa/snapshot": "^2.0.10",
     "@poppinss/ts-exec": "^1.4.4",
-    "tsdown": "^0.21.7"
+    "tsdown": "^0.21.10"
   },
   "peerDependencies": {
     "@adonisjs/core": "^6.2.0 || ^7.0.0",
@@ -82,6 +85,6 @@
     "build": "tsdown",
     "dev": "tsdown",
     "typecheck": "tsgo --noEmit",
-    "test": "node --import @poppinss/ts-exec bin/test.ts"
+    "test": "NODE_OPTIONS=--conditions=dev node --import @poppinss/ts-exec bin/test.ts"
   }
 }