@monocle.sh/effect-agent 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-present, Julien Ripouteau
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { MonocleEffectConfig } from "./src/types.mjs";
+import { MonocleLayer } from "./src/layer.mjs";
+import { MonocleSpanProcessor } from "./src/index.mjs";
+export { MonocleEffectConfig, MonocleLayer, MonocleSpanProcessor };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { MonocleLayer } from "./src/layer.mjs";
+import { MonocleSpanProcessor } from "./src/index.mjs";
+export { MonocleLayer, MonocleSpanProcessor };

package/dist/src/index.d.mts

@@ -0,0 +1,4 @@
+import { MonocleEffectConfig } from "./types.mjs";
+import { MonocleLayer } from "./layer.mjs";
+import { MonocleSpanProcessor as MonocleSpanProcessor$1 } from "@monocle.sh/otel-utils";
+export { MonocleSpanProcessor$1 as MonocleSpanProcessor };

package/dist/src/index.mjs

@@ -0,0 +1,3 @@
+import "./layer.mjs";
+import { MonocleSpanProcessor as MonocleSpanProcessor$1 } from "@monocle.sh/otel-utils";
+export { MonocleSpanProcessor$1 as MonocleSpanProcessor };

package/dist/src/layer.d.mts

@@ -0,0 +1,18 @@
+import { MonocleEffectConfig } from "./types.mjs";
+import { Resource } from "@effect/opentelemetry";
+import { Layer } from "effect";
+
+//#region src/layer.d.ts
+/**
+ * Creates an Effect Layer that configures OpenTelemetry with Monocle.
+ *
+ * Sets up OTLP exporters for traces, metrics, and logs with the proper
+ * Monocle authentication headers. Includes the MonocleSpanProcessor
+ * for automatic exception enrichment.
+ *
+ * Returns an empty layer when no API key is available and dev mode
+ * is disabled, making it safe for local development.
+ */
+declare function MonocleLayer(config: MonocleEffectConfig): Layer.Layer<Resource.Resource>;
+//#endregion
+export { MonocleLayer };

package/dist/src/layer.mjs

@@ -0,0 +1,93 @@
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { NodeSdk } from "@effect/opentelemetry";
+import { Layer, Option, Redacted } from "effect";
+import { MonocleSpanProcessor } from "@monocle.sh/otel-utils";
+//#region src/layer.ts
+const DEFAULT_ENDPOINT = "https://ingest.monocle.sh";
+const DEV_ENDPOINT = "http://localhost:4200";
+const DEFAULT_BATCH_CONFIG = {
+	maxExportBatchSize: 512,
+	scheduledDelayMillis: 5e3,
+	exportTimeoutMillis: 3e4,
+	maxQueueSize: 2048
+};
+const DEV_BATCH_CONFIG = {
+	...DEFAULT_BATCH_CONFIG,
+	scheduledDelayMillis: 100
+};
+/**
+* Resolve the Monocle API key from config or MONOCLE_API_KEY env var.
+* Returns a Redacted value to prevent accidental logging.
+*/
+function resolveApiKey(configKey) {
+	const raw = configKey || process.env.MONOCLE_API_KEY;
+	if (!raw) return Option.none();
+	return Option.some(Redacted.make(raw));
+}
+/**
+* Resolve the deployment environment.
+* Priority: config > MONOCLE_ENVIRONMENT > NODE_ENV > 'development'
+*/
+function resolveEnvironment(configEnv) {
+	return configEnv || process.env.MONOCLE_ENVIRONMENT || process.env.NODE_ENV || "development";
+}
+/**
+* Creates an Effect Layer that configures OpenTelemetry with Monocle.
+*
+* Sets up OTLP exporters for traces, metrics, and logs with the proper
+* Monocle authentication headers. Includes the MonocleSpanProcessor
+* for automatic exception enrichment.
+*
+* Returns an empty layer when no API key is available and dev mode
+* is disabled, making it safe for local development.
+*/
+function MonocleLayer(config) {
+	const isDev = config.dev;
+	const apiKey = resolveApiKey(config.apiKey);
+	if (!isDev && Option.isNone(apiKey)) return Layer.empty;
+	const endpoint = isDev ? config.endpoint || DEV_ENDPOINT : config.endpoint || DEFAULT_ENDPOINT;
+	const environment = resolveEnvironment(config.environment);
+	const batchConfig = isDev ? DEV_BATCH_CONFIG : DEFAULT_BATCH_CONFIG;
+	const headers = { "x-monocle-env": environment };
+	if (Option.isSome(apiKey)) headers["x-api-key"] = Redacted.value(apiKey.value);
+	const monocleProcessor = new MonocleSpanProcessor();
+	return NodeSdk.layer(() => ({
+		resource: {
+			serviceName: config.serviceName,
+			serviceVersion: config.serviceVersion ?? "0.0.0",
+			attributes: { "deployment.environment": environment }
+		},
+		spanProcessor: [monocleProcessor, new BatchSpanProcessor(new OTLPTraceExporter({
+			url: `${endpoint}/v1/traces`,
+			headers
+		}), {
+			maxExportBatchSize: batchConfig.maxExportBatchSize,
+			scheduledDelayMillis: batchConfig.scheduledDelayMillis,
+			exportTimeoutMillis: batchConfig.exportTimeoutMillis,
+			maxQueueSize: batchConfig.maxQueueSize
+		})],
+		metricReader: new PeriodicExportingMetricReader({
+			exporter: new OTLPMetricExporter({
+				url: `${endpoint}/v1/metrics`,
+				headers
+			}),
+			exportIntervalMillis: 1e4
+		}),
+		logRecordProcessor: new BatchLogRecordProcessor(new OTLPLogExporter({
+			url: `${endpoint}/v1/logs`,
+			headers
+		}), {
+			maxExportBatchSize: batchConfig.maxExportBatchSize,
+			scheduledDelayMillis: batchConfig.scheduledDelayMillis,
+			exportTimeoutMillis: batchConfig.exportTimeoutMillis,
+			maxQueueSize: batchConfig.maxQueueSize
+		})
+	}));
+}
+//#endregion
+export { MonocleLayer };

package/dist/src/types.d.mts

@@ -0,0 +1,35 @@
+//#region src/types.d.ts
+interface MonocleEffectConfig {
+  /**
+   * Enable local DevTools mode.
+   * Sends telemetry to Monocle DevTools (localhost:4200) with no compression
+   * and faster batch delays (100ms). No API key required.
+   */
+  dev?: boolean;
+  /**
+   * Monocle API key (format: mk_live_xxx or mk_test_xxx).
+   * Falls back to the MONOCLE_API_KEY environment variable.
+   * When neither is set and dev mode is off, returns an empty layer.
+   */
+  apiKey?: string;
+  /**
+   * Service name for this application.
+   */
+  serviceName: string;
+  /**
+   * Service version.
+   */
+  serviceVersion?: string;
+  /**
+   * Environment name sent via the x-monocle-env header.
+   * Falls back to MONOCLE_ENVIRONMENT, then NODE_ENV, then 'development'.
+   */
+  environment?: string;
+  /**
+   * OTLP endpoint URL.
+   * Defaults to 'https://ingest.monocle.sh' (or 'http://localhost:4200' in dev mode).
+   */
+  endpoint?: string;
+}
+//#endregion
+export { MonocleEffectConfig };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@monocle.sh/effect-agent",
+  "version": "0.0.1",
+  "description": "Monocle observability agent for Effect applications",
+  "keywords": [
+    "effect",
+    "monocle",
+    "observability",
+    "opentelemetry",
+    "tracing"
+  ],
+  "homepage": "https://github.com/monocle-sh/monocle/tree/main/packages/effect-agent",
+  "license": "ISC",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monocle-sh/monocle.git",
+    "directory": "packages/effect-agent"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/sdk-logs": "^0.214.0",
+    "@opentelemetry/sdk-metrics": "^2.6.1",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@monocle.sh/otel-utils": "1.0.1"
+  },
+  "devDependencies": {
+    "@adonisjs/tsconfig": "^2.0.0",
+    "tsdown": "^0.21.7"
+  },
+  "peerDependencies": {
+    "@effect/opentelemetry": ">=0.63.0",
+    "effect": ">=3.21.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown",
+    "typecheck": "tsgo --noEmit"
+  }
+}