@evenicanpm/common-core 1.8.0 → 2.0.0

package/package.json

@@ -1,10 +1,15 @@
 {
 	"name": "@evenicanpm/common-core",
-	"version": "1.8.0",
+	"version": "2.0.0",
 	"description": "Common module for Headless Storefront and Admin panel",
 	"author": "Evenica",
 	"type": "module",
 	"license": "ISC",
+	"exports": {
+		".": "./src/index.ts",
+		"./otel": "./src/otel/index.ts",
+		"./keyvault": "./src/lib/keyvault.ts"
+	},
 	"scripts": {
 		"test": "echo \"Error: no test specified\" && exit 1"
 	},
@@ -26,5 +31,5 @@
 	"devDependencies": {
 		"@types/node": "^24.0.13"
 	},
-	"gitHead": "485f77c5cce7c36849fb9d416d1e503d0f9299a3"
+	"gitHead": "7552c1e700a0027b8a65506c77cb10dae092fdfb"
 }

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./lib";
+export * from "./otel";

package/src/otel/README.md

@@ -1,44 +1,65 @@
-# Using Opentelemetry in e4
+# Using OpenTelemetry in e4
 
-- `setup.ts` has two main paths:
-  1. Azure Not Enabled - Will setup OLTP and @vercel/otel Registration for auto instrumentation with nextjs
-  2. Azure Enabled - Does the above AND Azure monitoring for metrics, logs, and traces
+## Setup in Next.js
 
-## Using a Tracer Example
+Call `setupOtel` in a server initialization file (NOT in `instrumentation.ts` due to environment variable timing issues).
 
-From https://opentelemetry.io/docs/languages/js/instrumentation/
+**Example: In your `src/lib/otel-init.ts` or similar:**
 
 ```ts
-import opentelemetry from "@opentelemetry/api";
-//...
+import { setupOtel } from "@evenicanpm/common-core/otel";
 
-const tracer = opentelemetry.trace.getTracer(
-  "instrumentation-scope-name",
-  "instrumentation-scope-version",
-);
+export async function initializeOTel() {
+  await setupOtel({
+    serviceName: "storefront",
+    azureMonitor: {
+      connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
+    },
+  });
+}
+```
+
+**Then import it early in your server startup** (e.g., in a route handler or API middleware that runs first):
 
-// You can now use a 'tracer' to do tracing!
+```ts
+// In your first API route or middleware
+import { initializeOTel } from "@/lib/otel-init";
+await initializeOTel();
 ```
 
-## Starting a Span
+## Configuration
 
+**Azure Monitor Only:**
 ```ts
-return tracer.startActiveSpan("rollTheDice", (span: Span) => {
-  const result: number[] = [];
-  for (let i = 0; i < rolls; i++) {
-    result.push(rollOnce(min, max));
-  }
-  // Be sure to end the span!
-  span.end();
-  return result;
+await setupOtel({
+  serviceName: "storefront",
+  azureMonitor: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
+  },
+});
+```
+
+**OTLP Only:**
+```ts
+await setupOtel({
+  serviceName: "storefront",
+  otlp: {
+    traceUrl: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+  },
 });
 ```
 
 ## Using the Logger
 
 ```ts
-import log from "@evenicanpm/common-core/src/otel/logger";
+import { logger } from "@evenicanpm/common-core/otel";
 
-const logger = log();
-logger.info("This is some e4 info!");
+const log = logger();
+log.info("Operation successful", { userId: "123" });
+log.error("Operation failed", error, { operation: "createUser" });
 ```
+
+## References
+
+- [OpenTelemetry JS Docs](https://opentelemetry.io/docs/languages/js/)
+- [Azure Monitor Exporter](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/monitor/monitor-opentelemetry-exporter)

package/src/otel/index.ts

@@ -0,0 +1,3 @@
+export { default as logger } from "./logger";
+export type { AzureMonitorConfig, OtelConfig, OtlpConfig } from "./setup";
+export { setupOtel } from "./setup";

package/src/otel/setup.ts

@@ -13,87 +13,143 @@ import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
 import { registerOTel } from "@vercel/otel";
 
 /**
- * The configuration object passed to setupOtel function.
+ * Configuration for OTLP trace export.
+ */
+interface OtlpConfig {
+	/**
+	 * Full OTLP HTTP endpoint used for trace export.
+	 *
+	 * Example: `http://otel-collector:4318/v1/traces`
+	 */
+	traceUrl: string;
+}
+
+/**
+ * Configuration for Azure Monitor exporters.
+ */
+interface AzureMonitorConfig {
+	/**
+	 * Azure Monitor connection string used by the exporter instances.
+	 */
+	connectionString: string;
+	/**
+	 * Enables Azure Monitor trace exporting.
+	 *
+	 * Defaults to `true` when `azureMonitor` is provided.
+	 */
+	traces?: boolean;
+	/**
+	 * Enables Azure Monitor log exporting and registers a global logger provider.
+	 *
+	 * Defaults to `true` when `azureMonitor` is provided.
+	 */
+	logs?: boolean;
+	/**
+	 * Enables Azure Monitor metric exporting and registers a global meter provider.
+	 *
+	 * Defaults to `true` when `azureMonitor` is provided.
+	 */
+	metrics?: boolean;
+	/**
+	 * Enables host-level metric collection when Azure Monitor metrics are enabled.
+	 *
+	 * Defaults to the value of `metrics`.
+	 */
+	hostMetrics?: boolean;
+}
+
+/**
+ * Public configuration for OTel setup.
  */
 interface OtelConfig {
+	/**
+	 * Logical service name attached to emitted telemetry.
+	 */
 	serviceName: string;
-	AzureEnabled?: boolean;
-	AzureMonitorKey?: string;
+	/**
+	 * Optional OTLP trace exporter configuration.
+	 */
+	otlp?: OtlpConfig;
+	/**
+	 * Optional Azure Monitor exporter configuration.
+	 */
+	azureMonitor?: AzureMonitorConfig;
 }
 
 /**
- * The core setup for Azure Insights and opentelemetry for
- * admin and storefront. Config can be extended to support multiple
- * opentelemetry exports.
+ * Registers telemetry exporters and providers for the current runtime.
+ *
+ * The caller owns environment-variable lookup and passes only the
+ * configuration needed for the current project.
+ *
+ * @param otelConfig Configuration for service naming and enabled exporters.
+ * @returns The result of `registerOTel` after span processors are attached.
  */
-async function setupOtel(otelConfig?: OtelConfig) {
-	if (!process.env.OTELCOL_URL) {
-		throw new Error("Missing OTELCOL_URL environment variable.");
-	}
-
-	const { serviceName, AzureEnabled, AzureMonitorKey } = otelConfig ?? {};
+async function setupOtel(otelConfig: OtelConfig) {
+	const { serviceName, otlp, azureMonitor } = otelConfig;
+	const spanProcessors: BatchSpanProcessor[] = [];
 
-	if (!AzureEnabled) {
-		return registerOTel({
-			serviceName: otelConfig?.serviceName,
-			spanProcessors: [
-				new BatchSpanProcessor(
-					new OTLPTraceExporter({ url: process.env.OTELCOL_URL }),
-				),
-			],
-		});
+	if (otlp?.traceUrl) {
+		spanProcessors.push(
+			new BatchSpanProcessor(new OTLPTraceExporter({ url: otlp.traceUrl })),
+		);
 	}
 
-	/** Azure Enabled */
-	if (!AzureMonitorKey)
-		throw new Error("No Azure Monitor Connection String Provided.");
+	if (azureMonitor) {
+		const enableAzureTraces = azureMonitor.traces ?? true;
+		const enableAzureLogs = azureMonitor.logs ?? true;
+		const enableAzureMetrics = azureMonitor.metrics ?? true;
+		const enableHostMetrics = azureMonitor.hostMetrics ?? enableAzureMetrics;
+		const config = {
+			connectionString: azureMonitor.connectionString,
+		};
 
-	const connectionString = AzureMonitorKey;
-	const config = { connectionString };
+		const {
+			AzureMonitorMetricExporter,
+			AzureMonitorTraceExporter,
+			AzureMonitorLogExporter,
+		} = await import("@azure/monitor-opentelemetry-exporter");
 
-	// Azure - Imports
-	const {
-		AzureMonitorMetricExporter,
-		AzureMonitorTraceExporter,
-		AzureMonitorLogExporter,
-	} = await import("@azure/monitor-opentelemetry-exporter");
-	const { HostMetrics } = await import("@opentelemetry/host-metrics");
+		if (enableAzureTraces) {
+			spanProcessors.push(
+				new BatchSpanProcessor(new AzureMonitorTraceExporter(config)),
+			);
+		}
 
-	// Azure - Monitor Exporters
-	const metricsExporter = new AzureMonitorMetricExporter(config);
-	const logExporter = new AzureMonitorLogExporter(config);
-	const traceExporter = new AzureMonitorTraceExporter(config);
+		if (enableAzureLogs) {
+			const logExporter = new AzureMonitorLogExporter(config);
+			const logProcessor = new BatchLogRecordProcessor(logExporter, {
+				maxExportBatchSize: 100,
+			});
+			const loggerProvider = new LoggerProvider({
+				processors: [logProcessor],
+			});
+			logs.setGlobalLoggerProvider(loggerProvider);
+		}
 
-	// Azure - Logging
-	const logProcessor = new BatchLogRecordProcessor(logExporter, {
-		maxExportBatchSize: 100,
-	});
-	const loggerProvider = new LoggerProvider({ processors: [logProcessor] });
-	logs.setGlobalLoggerProvider(loggerProvider);
+		if (enableAzureMetrics) {
+			const metricsExporter = new AzureMonitorMetricExporter(config);
+			const metricReader = new PeriodicExportingMetricReader({
+				exporter: metricsExporter,
+			});
+			const meterProvider = new MeterProvider({
+				readers: [metricReader],
+			});
+			metrics.setGlobalMeterProvider(meterProvider);
 
-	// Azure - Metrics
-	const metricReaderOptions = {
-		exporter: metricsExporter,
-	};
-	const metricReader = new PeriodicExportingMetricReader(metricReaderOptions);
-	const meterProvider = new MeterProvider({
-		readers: [metricReader],
-	});
-	metrics.setGlobalMeterProvider(meterProvider);
-	// OS level Metrics
-	const hostMetrics = new HostMetrics({ meterProvider });
-	hostMetrics.start();
+			if (enableHostMetrics) {
+				const { HostMetrics } = await import("@opentelemetry/host-metrics");
+				const hostMetrics = new HostMetrics({ meterProvider });
+				hostMetrics.start();
+			}
+		}
+	}
 
-	/** NextJS Otel Registration */
-	registerOTel({
-		serviceName: serviceName,
-		spanProcessors: [
-			new BatchSpanProcessor(traceExporter),
-			new BatchSpanProcessor(
-				new OTLPTraceExporter({ url: process.env.OTELCOL_URL }),
-			),
-		],
+	return registerOTel({
+		serviceName,
+		...(spanProcessors.length > 0 ? { spanProcessors } : {}),
 	});
 }
 
+export type { AzureMonitorConfig, OtelConfig, OtlpConfig };
 export { setupOtel };