@devopsplaybook.io/otel-utils 1.7.0-beta.38.e32e141 → 1.8.0-beta.39.883f25d

package/README.md

@@ -10,18 +10,26 @@ npm install @devopsplaybook.io/otel-utils
 
 ## Configuration
 
-All classes accept a `ConfigOTelInterface` object:
-
-| Field                                                     | Type       | Default | Description                     |
-| --------------------------------------------------------- | ---------- | ------- | ------------------------------- |
-| `SERVICE_ID`                                              | `string`   | —       | Service identifier (required)   |
-| `VERSION`                                                 | `string`   | —       | Service version (required)      |
-| `OPENTELEMETRY_COLLECTOR_HTTP_TRACES`                     | `string?`  | —       | OTLP HTTP endpoint for traces   |
-| `OPENTELEMETRY_COLLECTOR_HTTP_METRICS`                    | `string?`  | —       | OTLP HTTP endpoint for metrics  |
-| `OPENTELEMETRY_COLLECTOR_HTTP_LOGS`                       | `string?`  | —       | OTLP HTTP endpoint for logs     |
-| `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS`    | `number?`  | `60`    | Log export interval             |
-| `OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS` | `number?`  | `60`    | Metrics export interval         |
-| `OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER`              | `string?`  | —       | Bearer token for collector auth |
+All classes accept a `ConfigOTelInterface` object. The fields mirror environment variables in the consuming application (for example `common-utils`' `ConfigBase`); the library itself does not read `process.env`.
+
+| Field                                                     | Type                                | Default    | Description                                        |
+| --------------------------------------------------------- | ----------------------------------- | ---------- | -------------------------------------------------- |
+| `SERVICE_ID`                                              | `string`                            | —          | Service identifier (required, non-empty)           |
+| `VERSION`                                                 | `string`                            | —          | Service version (required, non-empty)              |
+| `OPENTELEMETRY_COLLECTOR_HTTP_TRACES`                     | `string?`                           | —          | OTLP HTTP endpoint for traces                      |
+| `OPENTELEMETRY_COLLECTOR_HTTP_METRICS`                    | `string?`                           | —          | OTLP HTTP endpoint for metrics                     |
+| `OPENTELEMETRY_COLLECTOR_HTTP_LOGS`                       | `string?`                           | —          | OTLP HTTP endpoint for logs                        |
+| `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS`    | `number?`                           | `60`       | Log export interval in seconds (clamped to ≥ 1)    |
+| `OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS` | `number?`                           | `60`       | Metrics export interval in seconds (clamped to ≥ 1) |
+| `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_QUEUE_SIZE`      | `number?`                           | `2048`     | Max log records buffered before export             |
+| `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_BATCH_SIZE`      | `number?`                           | `512`      | Max log records per export batch                   |
+| `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_TIMEOUT_MILLIS`      | `number?`                           | `30000`    | Log export timeout in milliseconds                 |
+| `OPENTELEMETRY_CONSOLE_LOG_MODE`                          | `"always" \| "fallback" \| "never"` | `"always"` | Console mirroring mode for `ModuleLogger`          |
+| `OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER`              | `string?`                           | —          | Bearer token for collector auth                    |
+
+`SERVICE_ID` and `VERSION` must be non-empty strings. `StandardTracer`/`StandardMeter` constructors and `StandardLogger.initOTel` fail fast with `[otel-utils] SERVICE_ID must be a non-empty string` / `[otel-utils] VERSION must be a non-empty string` otherwise. A failed re-initialisation of `StandardLogger` keeps the previous provider in place.
+
+Numeric export intervals below 1 s (including `0` and negative values from an empty environment variable) are clamped to 1 s; `NaN`/`Infinity` fall back to the 60 s default. Non-positive or non-integer batch values fall back to their defaults.
 
 When a collector endpoint is not provided, the corresponding signal (traces, logs, or metrics) is initialized with no export: traces and metrics still have a local provider but no data is sent, and `StandardLogger` creates no provider (its `getLogger()` returns `undefined`).
 
@@ -55,7 +63,7 @@ span.end();
 
 ### StandardLogger
 
-Initializes a `LoggerProvider` with an OTLP log exporter and a `BatchLogRecordProcessor` (`maxQueueSize: 2048`). When `OPENTELEMETRY_COLLECTOR_HTTP_LOGS` is set, the provider is also registered as the global OTel logger provider (first instance only), so `logs.getLogger(...)` from `@opentelemetry/api` returns loggers wired to the configured exporter. Each instance always logs through its own provider (`logger.createModuleLogger(...)`), so a second instance never mis-routes its records to the first one. Without that endpoint, `initOTel` still records the service identity but creates no provider and `getLogger()` returns `undefined`.
+Initializes a `LoggerProvider` with an OTLP log exporter and a `BatchLogRecordProcessor` (`maxQueueSize: 2048`, `maxExportBatchSize: 512`, `exportTimeoutMillis: 30000`, `scheduledDelayMillis: 60000` by default). When `OPENTELEMETRY_COLLECTOR_HTTP_LOGS` is set, the provider is also registered as the global OTel logger provider (first instance only), so `logs.getLogger(...)` from `@opentelemetry/api` returns loggers wired to the configured exporter. Each instance always logs through its own provider (`logger.createModuleLogger(...)`), so a second instance never mis-routes its records to the first one. Without that endpoint, `initOTel` still records the service identity but creates no provider and `getLogger()` returns `undefined`.
 
 ```typescript
 import { StandardLogger } from "@devopsplaybook.io/otel-utils";
@@ -74,15 +82,47 @@ moduleLog.info("Hello world");
 - `createModuleLogger(moduleName)` — Creates a `ModuleLogger` scoped to a module name.
 - `shutdown()` — Flushes buffered log records and shuts the logger provider down. Idempotent. No-op when no logs endpoint is configured.
 
+**Batch tunables and loss window**
+
+`BatchLogRecordProcessor` buffers records in memory and exports them periodically:
+
+| Option               | Config field                                           | Default    |
+| -------------------- | ------------------------------------------------------ | ---------- |
+| `scheduledDelayMillis` | `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS` | 60000 ms   |
+| `maxQueueSize`       | `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_QUEUE_SIZE`   | 2048       |
+| `maxExportBatchSize` | `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_BATCH_SIZE`   | 512        |
+| `exportTimeoutMillis` | `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_TIMEOUT_MILLIS`  | 30000 ms   |
+
+A record waits up to `scheduledDelayMillis` (60 s by default) before it is exported; each export sends at most `maxExportBatchSize` (512) records with a 30 s timeout, and at most `maxQueueSize` (2048) records are buffered. Records that arrive while the queue is full are **dropped silently** — no warning or fallback is emitted. A crash or restart loses every record buffered since the last export; call `shutdown()` or use `registerShutdownHooks` (see [Graceful shutdown](#graceful-shutdown)) to flush them. Keep `maxExportBatchSize` ≤ `maxQueueSize` (the SDK clamps it otherwise).
+
+```typescript
+await logger.initOTel({
+  ...config,
+  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: 5,
+  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_QUEUE_SIZE: 4096,
+  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_BATCH_SIZE: 512,
+  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_TIMEOUT_MILLIS: 10000,
+});
+```
+
 ### ModuleLogger
 
-Scoped logger that prefixes all output with a module name. Logs to both `console.log` and (when available) the OTel Logger.
+Scoped logger that prefixes all output with a module name. Every record carries a `log.module` attribute in addition to the `[module] message` body. Records are emitted to the OTel logger when one is available, and can additionally be mirrored to the console, controlled by `OPENTELEMETRY_CONSOLE_LOG_MODE`:
+
+| Mode                | Behaviour                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `always` (default)  | Mirror every record to the console, whether or not OTel logging is configured.                |
+| `fallback`          | Mirror only when no OTel logger is configured (`OPENTELEMETRY_COLLECTOR_HTTP_LOGS` unset).    |
+| `never`             | Never write to the console; records only go to OTel.                                          |
+
+Mirroring is level-aware: `info` uses `console.log`, `warn` uses `console.warn` and `error` uses `console.error` (stderr), so stderr-based alerting sees warnings and errors. An invalid mode value logs one `console.warn` and falls back to `always`. With `never`, a `ModuleLogger` writes nothing to the console even when no OTel logger is configured.
 
 ```typescript
 const log = logger.createModuleLogger("api");
 log.info("request received");
 log.warn("rate limit approaching");
 log.error("connection failed", new Error("timeout"));
+log.error("connection failed", "timeout"); // any unknown value is normalised
 log.info("processing complete", activeSpan); // attach trace context
 ```
 
@@ -90,7 +130,7 @@ log.info("processing complete", activeSpan); // attach trace context
 
 - `info(message, context?)` — Log at INFO level.
 - `warn(message, context?)` — Log at WARN level.
-- `error(message, error?, context?)` — Log at ERROR level with optional `Error` and span context. Attaches `exception.type`, `exception.message`, and `exception.stacktrace` attributes.
+- `error(message, error?, context?)` — Log at ERROR level. `error` accepts any value: `Error` instances are kept as-is, strings become `new Error(string)` and other values are serialised with `JSON.stringify` (falling back to `String`). `exception.type` and `exception.message` are always set; `exception.stacktrace` is set only when the error has a stack. `null`/`undefined` add no exception attributes. A `Span` passed as the second argument is treated as the context, so `error("failed", span)` and `error("failed", err, span)` both work.
 
 When a `Span` is passed as `context`, the log record includes `span.id` and `trace.id` attributes for trace correlation.
 

package/dist/src/ModuleLogger.d.ts

@@ -1,11 +1,16 @@
 import type { Span } from "@opentelemetry/api";
+import type { ConsoleLogMode } from "./models/ConfigOTelInterface";
 import { StandardLoggerInterface } from "./models/StandardLoggerInterface";
+export interface ModuleLoggerOptions {
+    consoleMode?: ConsoleLogMode;
+}
 export declare class ModuleLogger {
     private module;
     private standardLogger;
-    constructor(module: string, standardLogger: StandardLoggerInterface);
+    private consoleMode;
+    constructor(module: string, standardLogger: StandardLoggerInterface, options?: ModuleLoggerOptions);
     info(message: string, context?: Span): void;
     warn(message: string, context?: Span): void;
-    error(message: string, error?: Error, context?: Span): void;
+    error(message: string, error?: unknown, context?: Span): void;
     private display;
 }

package/dist/src/ModuleLogger.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModuleLogger = void 0;
 const api_1 = require("@opentelemetry/api");
 class ModuleLogger {
-    constructor(module, standardLogger) {
+    constructor(module, standardLogger, options = {}) {
+        var _a;
         this.module = module;
         this.standardLogger = standardLogger;
+        this.consoleMode = (_a = options.consoleMode) !== null && _a !== void 0 ? _a : "always";
     }
     info(message, context) {
         this.display("info", message, api_1.SeverityNumber.INFO, null, context);
@@ -14,23 +16,35 @@ class ModuleLogger {
         this.display("warn", message, api_1.SeverityNumber.WARN, null, context);
     }
     error(message, error, context) {
-        this.display("error", message, api_1.SeverityNumber.ERROR, error, context);
+        if (!context && isSpanLike(error)) {
+            context = error;
+            error = undefined;
+        }
+        this.display("error", message, api_1.SeverityNumber.ERROR, normalizeError(error), context);
     }
     display(level, message, severityNumber = api_1.SeverityNumber.INFO, error, context) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const attributes = { "log.type": "custom" };
+        const attributes = {
+            "log.type": "custom",
+            "log.module": this.module,
+        };
         if (error) {
             attributes["exception.type"] = error.name;
             attributes["exception.message"] = error.message;
-            attributes["exception.stacktrace"] = error.stack;
+            if (error.stack !== undefined) {
+                attributes["exception.stacktrace"] = error.stack;
+            }
         }
         if (context) {
             const spanCtx = context.spanContext();
             attributes["span.id"] = spanCtx.spanId;
             attributes["trace.id"] = spanCtx.traceId;
         }
-        console.log(`[${level}] [${this.module}] ${message}`);
         const logger = this.standardLogger.getLogger();
+        const mirrorToConsole = this.consoleMode === "always" ||
+            (this.consoleMode === "fallback" && !logger);
+        if (mirrorToConsole) {
+            writeToConsole(level, `[${level}] [${this.module}] ${message}`);
+        }
         if (!logger) {
             return;
         }
@@ -43,3 +57,48 @@ class ModuleLogger {
     }
 }
 exports.ModuleLogger = ModuleLogger;
+function normalizeError(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (value instanceof Error) {
+        return value;
+    }
+    return new Error(serializeUnknown(value));
+}
+function serializeUnknown(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        const json = JSON.stringify(value);
+        if (json !== undefined) {
+            return json;
+        }
+    }
+    catch {
+        // Not serialisable; fall back to String below.
+    }
+    try {
+        return String(value);
+    }
+    catch {
+        return "Unknown error";
+    }
+}
+function isSpanLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.spanContext === "function");
+}
+function writeToConsole(level, line) {
+    if (level === "error") {
+        console.error(line);
+    }
+    else if (level === "warn") {
+        console.warn(line);
+    }
+    else {
+        console.log(line);
+    }
+}

package/dist/src/StandardLogger.d.ts

@@ -1,5 +1,5 @@
 import { type Logger as OTelLogger } from "@opentelemetry/api";
-import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
+import type { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { ModuleLogger } from "./ModuleLogger";
 import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
 export declare class StandardLogger implements StandardLoggerInterface {
@@ -9,6 +9,7 @@ export declare class StandardLogger implements StandardLoggerInterface {
     private serviceName?;
     private ownsGlobalProvider;
     private shutdownPromise?;
+    private consoleMode;
     initOTel(config: ConfigOTelInterface): Promise<void>;
     shutdown(): Promise<void>;
     getLogger(): OTelLogger | undefined;

package/dist/src/StandardLogger.js

@@ -5,15 +5,20 @@ const api_1 = require("@opentelemetry/api");
 const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
 const sdk_logs_1 = require("@opentelemetry/sdk-logs");
 const createResource_1 = require("./utils/createResource");
+const configValidation_1 = require("./utils/configValidation");
 const ModuleLogger_1 = require("./ModuleLogger");
 let globalLoggerProvider;
 const ALREADY_REGISTERED_WARNING = "[otel-utils] A global logger provider is already registered; StandardLogger will not replace it. This instance still logs through its own provider, but logs.getLogger() keeps using the existing provider.";
 class StandardLogger {
     constructor() {
         this.ownsGlobalProvider = false;
+        this.consoleMode = "always";
     }
     async initOTel(config) {
-        var _a;
+        // Validate before releasing the previous provider: a bad re-init must keep
+        // the working provider in place.
+        (0, configValidation_1.validateServiceIdentity)(config);
+        this.consoleMode = (0, configValidation_1.normalizeConsoleLogMode)(config.OPENTELEMETRY_CONSOLE_LOG_MODE);
         // Re-initialisation flushes and unregisters the previous provider first.
         if (this.loggerProvider) {
             await this.releaseProvider();
@@ -37,8 +42,10 @@ class StandardLogger {
             processors: [
                 new sdk_logs_1.BatchLogRecordProcessor({
                     exporter,
-                    maxQueueSize: 2048,
-                    scheduledDelayMillis: ((_a = config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS) !== null && _a !== void 0 ? _a : 60) * 1000,
+                    maxQueueSize: (0, configValidation_1.normalizePositiveInteger)(config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_QUEUE_SIZE, 2048),
+                    maxExportBatchSize: (0, configValidation_1.normalizePositiveInteger)(config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_BATCH_SIZE, 512),
+                    exportTimeoutMillis: (0, configValidation_1.normalizePositiveInteger)(config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_TIMEOUT_MILLIS, 30000),
+                    scheduledDelayMillis: (0, configValidation_1.normalizeExportIntervalSeconds)(config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS, 60) * 1000,
                 }),
             ],
             resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
@@ -56,7 +63,7 @@ class StandardLogger {
         return this.logger;
     }
     createModuleLogger(moduleName) {
-        return new ModuleLogger_1.ModuleLogger(moduleName, this);
+        return new ModuleLogger_1.ModuleLogger(moduleName, this, { consoleMode: this.consoleMode });
     }
     registerGlobalProvider() {
         if (globalLoggerProvider) {

package/dist/src/StandardMeter.js

@@ -5,12 +5,13 @@ const api_1 = require("@opentelemetry/api");
 const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
 const createResource_1 = require("./utils/createResource");
 const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+const configValidation_1 = require("./utils/configValidation");
 let globalMeterProvider;
 const ALREADY_REGISTERED_WARNING = "[otel-utils] A global meter provider is already registered; StandardMeter will not replace it. This instance still records metrics through its own provider, but metrics.getMeter() keeps using the existing provider.";
 class StandardMeter {
     constructor(config) {
-        var _a;
         this.ownsGlobalProvider = false;
+        (0, configValidation_1.validateServiceIdentity)(config);
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
         let hasCollector = false;
@@ -31,7 +32,7 @@ class StandardMeter {
                 readers: [
                     new sdk_metrics_1.PeriodicExportingMetricReader({
                         exporter: metricExporter,
-                        exportIntervalMillis: ((_a = config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS) !== null && _a !== void 0 ? _a : 60) * 1000,
+                        exportIntervalMillis: (0, configValidation_1.normalizeExportIntervalSeconds)(config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS, 60) * 1000,
                     }),
                 ],
             });

package/dist/src/StandardTracer.js

@@ -8,6 +8,7 @@ const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-h
 const id_generator_aws_xray_1 = require("@opentelemetry/id-generator-aws-xray");
 const sdk_trace_1 = require("@opentelemetry/sdk-trace");
 const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const configValidation_1 = require("./utils/configValidation");
 const createResource_1 = require("./utils/createResource");
 let globalTracerProvider;
 let contextManagerInitialized = false;
@@ -21,6 +22,7 @@ const ALREADY_REGISTERED_WARNING = "[otel-utils] A global tracer provider is alr
 class StandardTracer {
     constructor(config) {
         this.ownsGlobalProvider = false;
+        (0, configValidation_1.validateServiceIdentity)(config);
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
         const spanProcessors = [];

package/dist/src/models/ConfigOTelInterface.d.ts

@@ -1,3 +1,4 @@
+export type ConsoleLogMode = "always" | "fallback" | "never";
 export interface ConfigOTelInterface {
     SERVICE_ID: string;
     VERSION: string;
@@ -6,5 +7,9 @@ export interface ConfigOTelInterface {
     OPENTELEMETRY_COLLECTOR_HTTP_LOGS?: string;
     OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS?: number;
     OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS?: number;
+    OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_QUEUE_SIZE?: number;
+    OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_BATCH_SIZE?: number;
+    OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_TIMEOUT_MILLIS?: number;
+    OPENTELEMETRY_CONSOLE_LOG_MODE?: ConsoleLogMode;
     OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER?: string;
 }

package/dist/src/utils/configValidation.d.ts

@@ -0,0 +1,5 @@
+import type { ConfigOTelInterface, ConsoleLogMode } from "../models/ConfigOTelInterface";
+export declare function validateServiceIdentity(config: Pick<ConfigOTelInterface, "SERVICE_ID" | "VERSION">): void;
+export declare function normalizeExportIntervalSeconds(value: number | undefined, defaultSeconds: number): number;
+export declare function normalizePositiveInteger(value: number | undefined, defaultValue: number): number;
+export declare function normalizeConsoleLogMode(value: unknown): ConsoleLogMode;

package/dist/src/utils/configValidation.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateServiceIdentity = validateServiceIdentity;
+exports.normalizeExportIntervalSeconds = normalizeExportIntervalSeconds;
+exports.normalizePositiveInteger = normalizePositiveInteger;
+exports.normalizeConsoleLogMode = normalizeConsoleLogMode;
+function validateServiceIdentity(config) {
+    if (typeof config.SERVICE_ID !== "string" ||
+        config.SERVICE_ID.trim() === "") {
+        throw new Error("[otel-utils] SERVICE_ID must be a non-empty string");
+    }
+    if (typeof config.VERSION !== "string" || config.VERSION.trim() === "") {
+        throw new Error("[otel-utils] VERSION must be a non-empty string");
+    }
+}
+function normalizeExportIntervalSeconds(value, defaultSeconds) {
+    if (value === undefined || !Number.isFinite(value)) {
+        return defaultSeconds;
+    }
+    return Math.max(1, value);
+}
+function normalizePositiveInteger(value, defaultValue) {
+    if (value === undefined || !Number.isInteger(value) || value <= 0) {
+        return defaultValue;
+    }
+    return value;
+}
+function normalizeConsoleLogMode(value) {
+    if (value === "always" || value === "fallback" || value === "never") {
+        return value;
+    }
+    if (value !== undefined) {
+        console.warn(`[otel-utils] Invalid OPENTELEMETRY_CONSOLE_LOG_MODE value "${String(value)}"; expected "always", "fallback" or "never". Defaulting to "always".`);
+    }
+    return "always";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils",
-  "version": "1.7.0-beta.38.e32e141",
+  "version": "1.8.0-beta.39.883f25d",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",

package/src/ModuleLogger.spec.ts

@@ -3,20 +3,26 @@ import {
   SeverityNumber,
   type Logger as OTelLogger,
 } from "@opentelemetry/api";
-import { ModuleLogger } from "./ModuleLogger";
+import { ModuleLogger, type ModuleLoggerOptions } from "./ModuleLogger";
 import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
 
 describe("ModuleLogger", () => {
-  let consoleSpy: jest.SpyInstance;
+  let logSpy: jest.SpyInstance;
+  let warnSpy: jest.SpyInstance;
+  let errorSpy: jest.SpyInstance;
   let emit: jest.Mock;
 
   beforeEach(() => {
     emit = jest.fn();
-    consoleSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
   });
 
   afterEach(() => {
-    consoleSpy.mockRestore();
+    logSpy.mockRestore();
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
   });
 
   function createLogger(
@@ -25,27 +31,47 @@ describe("ModuleLogger", () => {
     return { getLogger };
   }
 
-  function loggerWithEmit(): ModuleLogger {
+  function loggerWithEmit(options?: ModuleLoggerOptions): ModuleLogger {
     const fakeLogger = { emit } as unknown as OTelLogger;
-    return new ModuleLogger("billing", createLogger(() => fakeLogger));
+    return new ModuleLogger("billing", createLogger(() => fakeLogger), options);
   }
 
-  it("logs info to console and the OTel logger", () => {
+  function lastAttributes(): Record<string, unknown> {
+    const record = emit.mock.calls[emit.mock.calls.length - 1][0] as {
+      attributes: Record<string, unknown>;
+    };
+    return record.attributes;
+  }
+
+  function expectOnlyDefinedAttributes(): void {
+    for (const [key, value] of Object.entries(lastAttributes())) {
+      expect({ key, defined: value !== undefined }).toEqual({
+        key,
+        defined: true,
+      });
+    }
+  }
+
+  it("logs info to console.log and the OTel logger with the module attribute", () => {
     loggerWithEmit().info("hello");
 
-    expect(consoleSpy).toHaveBeenCalledWith("[info] [billing] hello");
+    expect(logSpy).toHaveBeenCalledWith("[info] [billing] hello");
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(errorSpy).not.toHaveBeenCalled();
     expect(emit).toHaveBeenCalledWith({
       severityNumber: SeverityNumber.INFO,
       severityText: "info",
       body: "[billing] hello",
-      attributes: { "log.type": "custom" },
+      attributes: { "log.type": "custom", "log.module": "billing" },
     });
   });
 
-  it("logs warn at WARN severity", () => {
+  it("mirrors warnings through console.warn", () => {
     loggerWithEmit().warn("careful");
 
-    expect(consoleSpy).toHaveBeenCalledWith("[warn] [billing] careful");
+    expect(warnSpy).toHaveBeenCalledWith("[warn] [billing] careful");
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(errorSpy).not.toHaveBeenCalled();
     expect(emit).toHaveBeenCalledWith(
       expect.objectContaining({
         severityNumber: SeverityNumber.WARN,
@@ -55,17 +81,24 @@ describe("ModuleLogger", () => {
     );
   });
 
+  it("mirrors errors through console.error", () => {
+    loggerWithEmit().error("failed");
+
+    expect(errorSpy).toHaveBeenCalledWith("[error] [billing] failed");
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
   it("logs errors without duplicating the stack in the record body", () => {
     const error = new Error("boom");
     loggerWithEmit().error("request failed", error);
 
-    expect(consoleSpy).toHaveBeenCalledWith("[error] [billing] request failed");
     expect(emit).toHaveBeenCalledWith({
       severityNumber: SeverityNumber.ERROR,
       severityText: "error",
       body: "[billing] request failed",
       attributes: {
         "log.type": "custom",
+        "log.module": "billing",
         "exception.type": "Error",
         "exception.message": "boom",
         "exception.stacktrace": error.stack,
@@ -73,6 +106,69 @@ describe("ModuleLogger", () => {
     });
   });
 
+  it("normalises a string error instead of losing its message", () => {
+    loggerWithEmit().error("failed", "string-error");
+
+    const attributes = lastAttributes();
+    expect(attributes["exception.type"]).toBe("Error");
+    expect(attributes["exception.message"]).toBe("string-error");
+    expect(typeof attributes["exception.stacktrace"]).toBe("string");
+    expectOnlyDefinedAttributes();
+  });
+
+  it("serialises a plain object error", () => {
+    loggerWithEmit().error("failed", { code: 42 });
+
+    const attributes = lastAttributes();
+    expect(attributes["exception.type"]).toBe("Error");
+    expect(attributes["exception.message"]).toBe('{"code":42}');
+    expect(typeof attributes["exception.stacktrace"]).toBe("string");
+    expectOnlyDefinedAttributes();
+  });
+
+  it("adds no exception attributes without an error", () => {
+    loggerWithEmit().error("failed");
+    expect(lastAttributes()).toEqual({
+      "log.type": "custom",
+      "log.module": "billing",
+    });
+
+    loggerWithEmit().error("failed", null);
+    expect(lastAttributes()).toEqual({
+      "log.type": "custom",
+      "log.module": "billing",
+    });
+  });
+
+  it("omits exception.stacktrace when the error has no stack", () => {
+    const error = new Error("no stack");
+    delete error.stack;
+
+    loggerWithEmit().error("failed", error);
+
+    const attributes = lastAttributes();
+    expect(attributes["exception.type"]).toBe("Error");
+    expect(attributes["exception.message"]).toBe("no stack");
+    expect(attributes).not.toHaveProperty("exception.stacktrace");
+    expectOnlyDefinedAttributes();
+  });
+
+  it("treats a span passed as the second argument as context", () => {
+    const span = {
+      spanContext: () => ({ spanId: "span-1", traceId: "trace-1" }),
+    } as unknown as Span;
+
+    loggerWithEmit().error("failed", span);
+
+    expect(errorSpy).toHaveBeenCalledWith("[error] [billing] failed");
+    expect(lastAttributes()).toEqual({
+      "log.type": "custom",
+      "log.module": "billing",
+      "span.id": "span-1",
+      "trace.id": "trace-1",
+    });
+  });
+
   it("adds span and trace ids when a span context is provided", () => {
     const span = {
       spanContext: () => ({ spanId: "span-1", traceId: "trace-1" }),
@@ -90,12 +186,68 @@ describe("ModuleLogger", () => {
     );
   });
 
-  it("falls back to console only when no OTel logger is available", () => {
-    const logger = new ModuleLogger("billing", createLogger(() => undefined));
+  it("combines exception attributes with a span context", () => {
+    const span = {
+      spanContext: () => ({ spanId: "span-2", traceId: "trace-2" }),
+    } as unknown as Span;
 
-    logger.warn("offline");
+    loggerWithEmit().error("failed", new Error("boom"), span);
 
-    expect(consoleSpy).toHaveBeenCalledWith("[warn] [billing] offline");
-    expect(emit).not.toHaveBeenCalled();
+    const attributes = lastAttributes();
+    expect(attributes["exception.message"]).toBe("boom");
+    expect(attributes["span.id"]).toBe("span-2");
+    expect(attributes["trace.id"]).toBe("trace-2");
+    expectOnlyDefinedAttributes();
+  });
+
+  describe("console modes", () => {
+    it("always mirrors with and without an OTel logger", () => {
+      loggerWithEmit({ consoleMode: "always" }).info("with logger");
+      expect(logSpy).toHaveBeenCalledWith("[info] [billing] with logger");
+      expect(emit).toHaveBeenCalledTimes(1);
+
+      const withoutLogger = new ModuleLogger(
+        "billing",
+        createLogger(() => undefined),
+        { consoleMode: "always" },
+      );
+      withoutLogger.info("without logger");
+      expect(logSpy).toHaveBeenCalledWith(
+        "[info] [billing] without logger",
+      );
+      expect(emit).toHaveBeenCalledTimes(1);
+    });
+
+    it("fallback mirrors only when no OTel logger is available", () => {
+      loggerWithEmit({ consoleMode: "fallback" }).info("with logger");
+      expect(logSpy).not.toHaveBeenCalled();
+      expect(emit).toHaveBeenCalledTimes(1);
+
+      const withoutLogger = new ModuleLogger(
+        "billing",
+        createLogger(() => undefined),
+        { consoleMode: "fallback" },
+      );
+      withoutLogger.warn("without logger");
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[warn] [billing] without logger",
+      );
+    });
+
+    it("never disables console output while records are still emitted", () => {
+      loggerWithEmit({ consoleMode: "never" }).error("silent");
+
+      expect(logSpy).not.toHaveBeenCalled();
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(errorSpy).not.toHaveBeenCalled();
+      expect(emit).toHaveBeenCalledWith(
+        expect.objectContaining({ severityText: "error" }),
+      );
+    });
+
+    it("defaults to always when no options are given", () => {
+      new ModuleLogger("billing", createLogger(() => undefined)).info("legacy");
+      expect(logSpy).toHaveBeenCalledWith("[info] [billing] legacy");
+    });
   });
 });