@devopsplaybook.io/otel-utils 1.0.18 → 1.1.0-beta.21.15fb757

package/README.md

@@ -1 +1,165 @@
-# otel-utils
+# otel-utils
+
+Utility library that simplifies OpenTelemetry integration for Node.js services. Provides standardized tracing, structured logging, and metrics export with minimal boilerplate.
+
+## Installation
+
+```bash
+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_COLLECTOR_AWS`                             | `boolean?` | —       | AWS-specific feature flag       |
+| `OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER`              | `string?`  | —       | Bearer token for collector auth |
+
+When a collector endpoint is not provided, the corresponding signal (traces, logs, or metrics) is initialized with no export — the provider is still available but no data is sent.
+
+## Exported Classes
+
+### StandardTracer
+
+Sets up a global `NodeTracerProvider` with:
+
+- AWS X-Ray ID generator (`AWSXRayIdGenerator`)
+- OTLP HTTP trace exporter (optional, when `OPENTELEMETRY_COLLECTOR_HTTP_TRACES` is set)
+- `AsyncHooksContextManager` for automatic context propagation
+- Service resource attributes (name, version, hostname)
+
+```typescript
+import { StandardTracer } from "@devopsplaybook.io/otel-utils";
+
+const tracer = new StandardTracer(config);
+const span = tracer.startSpan("my-operation");
+// ... do work ...
+span.end();
+```
+
+**Methods:**
+
+- `startSpan(name, parentSpan?)` — Creates a span. When no `parentSpan` is provided, adds `http.request_method=BACKEND` and `http.route` attributes. Span names are sanitized to `[a-zA-Z0-9-_/]`.
+- `static updateHttpHeader(context, headers?)` — Injects W3C trace context into an HTTP headers object for propagation to downstream services.
+
+### StandardLogger
+
+Initializes a `LoggerProvider` with an OTLP log exporter and a `BatchLogRecordProcessor` (`maxQueueSize: 2048`).
+
+```typescript
+import { StandardLogger } from "@devopsplaybook.io/otel-utils";
+
+const logger = new StandardLogger();
+logger.initOTel(config);
+
+const moduleLog = logger.createModuleLogger("my-module");
+moduleLog.info("Hello world");
+```
+
+**Methods:**
+
+- `initOTel(config)` — Initializes the logger provider and optional OTLP exporter.
+- `getLogger()` — Returns the underlying OTel `Logger` or `undefined`.
+- `createModuleLogger(moduleName)` — Creates a `ModuleLogger` scoped to a module name.
+
+### ModuleLogger
+
+Scoped logger that prefixes all output with a module name. Logs to both `console.log` and (when available) the OTel Logger.
+
+```typescript
+const log = logger.createModuleLogger("api");
+log.info("request received");
+log.warn("rate limit approaching");
+log.error("connection failed", new Error("timeout"));
+log.info("processing complete", activeSpan); // attach trace context
+```
+
+**Methods:**
+
+- `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.
+
+When a `Span` is passed as `context`, the log record includes `span.id` and `trace.id` attributes for trace correlation.
+
+### StandardMeter
+
+Creates a `MeterProvider` with an optional `PeriodicExportingMetricReader` (`concurrencyLimit: 5`). Provides convenience factories for common metric types.
+
+```typescript
+import { StandardMeter } from "@devopsplaybook.io/otel-utils";
+
+const meter = new StandardMeter(config);
+
+const requestCount = meter.createCounter("requests.total");
+requestCount.add(1);
+
+const latency = meter.createHistogram("requests.latency");
+latency.record(42);
+
+const activeUsers = meter.createUpDownCounter("users.active");
+activeUsers.add(1);
+
+const cpuGauge = meter.createObservableGauge(
+  "cpu.usage",
+  (result) => result.observe(cpuPercent),
+  "Current CPU usage",
+);
+```
+
+**Methods:**
+
+- `createCounter(key)` — Creates a `Counter` with name `${serviceName}.${key}`.
+- `createUpDownCounter(key)` — Creates an `UpDownCounter`.
+- `createHistogram(key)` — Creates a `Histogram`.
+- `createObservableGauge(key, callback, description?)` — Creates an `ObservableGauge` with a callback. Description is optional.
+
+## Internal Utilities
+
+### createOTelResource
+
+Shared internal utility that creates an `OTelResource` with `service.name`, `service.version`, and `network.local.address` (hostname). The hostname is cached at module load time to minimize system calls.
+
+```typescript
+// Used internally by StandardTracer, StandardLogger, and StandardMeter
+```
+
+## Architecture
+
+```
+Application
+  ├── StandardTracer  ──► OTLP Trace Exporter  ──► Collector / otel-light
+  ├── StandardLogger  ──► OTLP Log Exporter     ──► Collector / otel-light
+  │     └── ModuleLogger (scoped per module)
+  └── StandardMeter   ──► OTLP Metric Exporter  ──► Collector / otel-light
+                           └── PeriodicExportingMetricReader
+```
+
+All three signals share the same service identity (name + version) and resource attributes via `createOTelResource`. Export is optional per signal — only configured when the corresponding `OPENTELEMETRY_COLLECTOR_HTTP_*` endpoint is set.
+
+## Dependencies
+
+- `@opentelemetry/api` / `@opentelemetry/api-logs` — OpenTelemetry API interfaces
+- `@opentelemetry/sdk-trace-node` / `@opentelemetry/sdk-trace-base` — Tracing SDK
+- `@opentelemetry/sdk-metrics` — Metrics SDK
+- `@opentelemetry/sdk-logs` — Logging SDK
+- `@opentelemetry/exporter-trace-otlp-http` / `@opentelemetry/exporter-metrics-otlp-http` / `@opentelemetry/exporter-logs-otlp-http` — OTLP HTTP exporters
+- `@opentelemetry/id-generator-aws-xray` — AWS X-Ray trace ID format
+- `@opentelemetry/context-async-hooks` — Async context management
+- `@opentelemetry/core` — W3C trace context propagation
+- `@opentelemetry/resources` / `@opentelemetry/semantic-conventions` — Resource attributes
+
+## Build
+
+```bash
+npm run build   # tsc → dist/
+```

package/dist/src/ModuleLogger.js

@@ -21,7 +21,6 @@ class ModuleLogger {
         let formattedMessage = message;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const attributes = { "log.type": "custom" };
-        formattedMessage = message;
         if (error) {
             attributes["exception.type"] = error.name;
             attributes["exception.message"] = error.message;

package/dist/src/StandardLogger.d.ts

@@ -1,7 +1,8 @@
 import type { Logger as OTelLogger } from "@opentelemetry/api-logs";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { ModuleLogger } from "./ModuleLogger";
-export declare class StandardLogger {
+import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
+export declare class StandardLogger implements StandardLoggerInterface {
     private logger?;
     private serviceVersion?;
     private serviceName?;

package/dist/src/StandardLogger.js

@@ -1,53 +1,20 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StandardLogger = void 0;
 const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
-const resources_1 = require("@opentelemetry/resources");
 const sdk_logs_1 = require("@opentelemetry/sdk-logs");
-const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
-const os = __importStar(require("os"));
+const createResource_1 = require("./utils/createResource");
 const ModuleLogger_1 = require("./ModuleLogger");
 class StandardLogger {
     initOTel(config) {
+        var _a;
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
         if (config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS) {
             const exporterHeaders = {};
             if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-                exporterHeaders["Authorization"] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+                exporterHeaders["Authorization"] =
+                    `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
             }
             const exporter = new exporter_logs_otlp_http_1.OTLPLogExporter({
                 url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
@@ -56,16 +23,11 @@ class StandardLogger {
             const loggerProvider = new sdk_logs_1.LoggerProvider({
                 processors: [
                     new sdk_logs_1.BatchLogRecordProcessor(exporter, {
-                        maxQueueSize: 100,
-                        scheduledDelayMillis: config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS *
-                            1000,
+                        maxQueueSize: 2048,
+                        scheduledDelayMillis: ((_a = config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS) !== null && _a !== void 0 ? _a : 60) * 1000,
                     }),
                 ],
-                resource: (0, resources_1.resourceFromAttributes)({
-                    [semantic_conventions_1.ATTR_SERVICE_NAME]: `${this.serviceName}`,
-                    [semantic_conventions_1.ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-                    [semantic_conventions_1.ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-                }),
+                resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             });
             this.logger = loggerProvider.getLogger(`${this.serviceName}:${this.serviceVersion}`);
         }

package/dist/src/StandardMeter.d.ts

@@ -1,4 +1,4 @@
-import { Counter, Histogram, ObservableGauge } from "@opentelemetry/api";
+import { Counter, Histogram, ObservableGauge, UpDownCounter } from "@opentelemetry/api";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 export declare class StandardMeter {
     private meter;
@@ -6,7 +6,7 @@ export declare class StandardMeter {
     private serviceName;
     constructor(config: ConfigOTelInterface);
     createCounter(key: string): Counter;
-    createUpDownCounter(key: string): Counter;
+    createUpDownCounter(key: string): UpDownCounter;
     createHistogram(key: string): Histogram;
-    createObservableGauge(key: string, callback: (observableResult: any) => void, description?: any): ObservableGauge;
+    createObservableGauge(key: string, callback: (observableResult: any) => void, description?: string): ObservableGauge;
 }

package/dist/src/StandardMeter.js

@@ -1,46 +1,12 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StandardMeter = void 0;
 const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
-const resources_1 = require("@opentelemetry/resources");
+const createResource_1 = require("./utils/createResource");
 const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
-const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
-const os = __importStar(require("os"));
 class StandardMeter {
     constructor(config) {
+        var _a;
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
         let meterProvider;
@@ -48,34 +14,26 @@ class StandardMeter {
             const collectorOptions = {
                 url: config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS,
                 headers: {},
-                concurrencyLimit: 1,
+                concurrencyLimit: 5,
             };
             if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-                collectorOptions.headers["Authorization"] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+                collectorOptions.headers["Authorization"] =
+                    `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
             }
             const metricExporter = new exporter_metrics_otlp_http_1.OTLPMetricExporter(collectorOptions);
             meterProvider = new sdk_metrics_1.MeterProvider({
-                resource: (0, resources_1.resourceFromAttributes)({
-                    [semantic_conventions_1.ATTR_SERVICE_NAME]: `${this.serviceName}`,
-                    [semantic_conventions_1.ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-                    [semantic_conventions_1.ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-                }),
+                resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
                 readers: [
                     new sdk_metrics_1.PeriodicExportingMetricReader({
                         exporter: metricExporter,
-                        exportIntervalMillis: config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS *
-                            1000,
+                        exportIntervalMillis: ((_a = config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS) !== null && _a !== void 0 ? _a : 60) * 1000,
                     }),
                 ],
             });
         }
         else {
             meterProvider = new sdk_metrics_1.MeterProvider({
-                resource: (0, resources_1.resourceFromAttributes)({
-                    [semantic_conventions_1.ATTR_SERVICE_NAME]: `${this.serviceName}`,
-                    [semantic_conventions_1.ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-                    [semantic_conventions_1.ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-                }),
+                resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             });
         }
         this.meter = meterProvider.getMeter(`${this.serviceName}:${this.serviceVersion}`);
@@ -91,10 +49,8 @@ class StandardMeter {
     }
     createObservableGauge(key, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    callback, 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    description = null) {
-        const observableGauge = this.meter.createObservableGauge(key, description);
+    callback, description) {
+        const observableGauge = this.meter.createObservableGauge(key, description ? { description } : undefined);
         observableGauge.addCallback(callback);
         return observableGauge;
     }

package/dist/src/StandardTracer.d.ts

@@ -1,6 +1,8 @@
 import { Span } from "@opentelemetry/sdk-trace-base";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 export declare class StandardTracer {
+    private static readonly SPAN_NAME_SANITIZE_RE;
+    private static readonly PROPAGATOR;
     private tracer;
     private serviceVersion;
     private serviceName;

package/dist/src/StandardTracer.js

@@ -39,11 +39,10 @@ const context_async_hooks_1 = require("@opentelemetry/context-async-hooks");
 const core_1 = require("@opentelemetry/core");
 const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
 const id_generator_aws_xray_1 = require("@opentelemetry/id-generator-aws-xray");
-const resources_1 = require("@opentelemetry/resources");
 const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
 const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
 const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
-const os = __importStar(require("os"));
+const createResource_1 = require("./utils/createResource");
 class StandardTracer {
     constructor(config) {
         this.serviceName = config.SERVICE_ID;
@@ -52,7 +51,8 @@ class StandardTracer {
         if (config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES) {
             const exporterHeaders = {};
             if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-                exporterHeaders["Authorization"] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+                exporterHeaders["Authorization"] =
+                    `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
             }
             const exporter = new exporter_trace_otlp_http_1.OTLPTraceExporter({
                 url: config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES,
@@ -62,11 +62,7 @@ class StandardTracer {
         }
         const traceProvider = new sdk_trace_node_1.NodeTracerProvider({
             idGenerator: new id_generator_aws_xray_1.AWSXRayIdGenerator(),
-            resource: (0, resources_1.resourceFromAttributes)({
-                [semantic_conventions_1.ATTR_SERVICE_NAME]: `${this.serviceName}`,
-                [semantic_conventions_1.ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-                [semantic_conventions_1.ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-            }),
+            resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             spanProcessors,
         });
         traceProvider.register();
@@ -76,7 +72,7 @@ class StandardTracer {
         this.tracer = api_1.default.trace.getTracer(`${this.serviceName}:${this.serviceVersion}`);
     }
     startSpan(name, parentSpan) {
-        const sanitizedName = String(name).replace(/[^a-zA-Z0-9-_/]/g, "_");
+        const sanitizedName = String(name).replace(StandardTracer.SPAN_NAME_SANITIZE_RE, "_");
         if (parentSpan) {
             return this.tracer.startSpan(sanitizedName, undefined, api_1.default.trace.setSpan(api_1.default.context.active(), parentSpan));
         }
@@ -90,11 +86,12 @@ class StandardTracer {
         if (!headers) {
             headers = {};
         }
-        const propagator = new core_1.W3CTraceContextPropagator();
-        propagator.inject(api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, context.spanContext()), 
+        StandardTracer.PROPAGATOR.inject(api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, context.spanContext()), 
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         headers, api_1.defaultTextMapSetter);
         return headers;
     }
 }
 exports.StandardTracer = StandardTracer;
+StandardTracer.SPAN_NAME_SANITIZE_RE = /[^a-zA-Z0-9-_/]/g;
+StandardTracer.PROPAGATOR = new core_1.W3CTraceContextPropagator();

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

@@ -1,11 +1,11 @@
 export interface ConfigOTelInterface {
     SERVICE_ID: string;
     VERSION: string;
-    OPENTELEMETRY_COLLECTOR_HTTP_TRACES: string;
-    OPENTELEMETRY_COLLECTOR_HTTP_METRICS: string;
-    OPENTELEMETRY_COLLECTOR_HTTP_LOGS: string;
-    OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: number;
-    OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: number;
-    OPENTELEMETRY_COLLECTOR_AWS: boolean;
-    OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: string;
+    OPENTELEMETRY_COLLECTOR_HTTP_TRACES?: string;
+    OPENTELEMETRY_COLLECTOR_HTTP_METRICS?: string;
+    OPENTELEMETRY_COLLECTOR_HTTP_LOGS?: string;
+    OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS?: number;
+    OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS?: number;
+    OPENTELEMETRY_COLLECTOR_AWS?: boolean;
+    OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER?: string;
 }

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

@@ -0,0 +1 @@
+export declare function createOTelResource(serviceName: string, serviceVersion: string): import("@opentelemetry/resources").Resource;

package/dist/src/utils/createResource.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOTelResource = createOTelResource;
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const os = __importStar(require("os"));
+const CACHED_HOSTNAME = os.hostname();
+function createOTelResource(serviceName, serviceVersion) {
+    return (0, resources_1.resourceFromAttributes)({
+        [semantic_conventions_1.ATTR_SERVICE_NAME]: serviceName,
+        [semantic_conventions_1.ATTR_SERVICE_VERSION]: serviceVersion,
+        [semantic_conventions_1.ATTR_NETWORK_LOCAL_ADDRESS]: CACHED_HOSTNAME,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils",
-  "version": "1.0.18",
+  "version": "1.1.0-beta.21.15fb757",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",
@@ -20,24 +20,29 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.217.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.75.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.217.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
+    "@opentelemetry/api-logs": "^0.218.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.76.0",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/id-generator-aws-xray": "^2.1.0",
     "@opentelemetry/resources": "^2.7.1",
-    "@opentelemetry/sdk-logs": "^0.217.0",
-    "@opentelemetry/sdk-node": "^0.217.0",
+    "@opentelemetry/sdk-logs": "^0.218.0",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
     "@opentelemetry/sdk-trace-web": "^2.7.1",
-    "@opentelemetry/semantic-conventions": "^1.40.0"
+    "@opentelemetry/semantic-conventions": "^1.41.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.1",
     "@types/sqlite3": "^5.1.0",
     "ts-node": "^10.9.2",
-    "typescript-eslint": "^8.59.3",
+    "typescript-eslint": "^8.59.4",
     "typescript": "^6.0.3"
   },
   "publishConfig": {

package/src/ModuleLogger.ts

@@ -28,14 +28,13 @@ export class ModuleLogger {
     message: string,
     severityNumber = SeverityNumber.INFO,
     error?: Error | null,
-    context?: Span
+    context?: Span,
   ): void {
     let formattedMessage = message;
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const attributes: Record<string, any> = { "log.type": "custom" };
 
-    formattedMessage = message;
     if (error) {
       attributes["exception.type"] = error.name;
       attributes["exception.message"] = error.message;

package/src/StandardLogger.ts

@@ -1,21 +1,17 @@
-import type { Logger, Logger as OTelLogger } from "@opentelemetry/api-logs";
+import type { Logger as OTelLogger } from "@opentelemetry/api-logs";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
 import {
   BatchLogRecordProcessor,
   LoggerProvider,
 } from "@opentelemetry/sdk-logs";
-import {
-  ATTR_NETWORK_LOCAL_ADDRESS,
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-} from "@opentelemetry/semantic-conventions";
-import * as os from "os";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
+import { createOTelResource } from "./utils/createResource";
 import { ModuleLogger } from "./ModuleLogger";
 
-export class StandardLogger {
-  private logger?: Logger;
+import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
+
+export class StandardLogger implements StandardLoggerInterface {
+  private logger?: OTelLogger;
   private serviceVersion?: string;
   private serviceName?: string;
 
@@ -26,9 +22,8 @@ export class StandardLogger {
     if (config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS) {
       const exporterHeaders: Record<string, string> = {};
       if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-        exporterHeaders[
-          "Authorization"
-        ] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+        exporterHeaders["Authorization"] =
+          `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
       }
       const exporter = new OTLPLogExporter({
         url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
@@ -38,21 +33,17 @@ export class StandardLogger {
       const loggerProvider = new LoggerProvider({
         processors: [
           new BatchLogRecordProcessor(exporter, {
-            maxQueueSize: 100,
+            maxQueueSize: 2048,
             scheduledDelayMillis:
-              config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS *
-              1000,
+              (config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS ??
+                60) * 1000,
           }),
         ],
-        resource: resourceFromAttributes({
-          [ATTR_SERVICE_NAME]: `${this.serviceName}`,
-          [ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-          [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-        }),
+        resource: createOTelResource(this.serviceName, this.serviceVersion),
       });
 
       this.logger = loggerProvider.getLogger(
-        `${this.serviceName}:${this.serviceVersion}`
+        `${this.serviceName}:${this.serviceVersion}`,
       );
     }
   }

package/src/StandardMeter.ts

@@ -1,16 +1,16 @@
-import { Counter, Histogram, Meter, ObservableGauge } from "@opentelemetry/api";
+import {
+  Counter,
+  Histogram,
+  Meter,
+  ObservableGauge,
+  UpDownCounter,
+} from "@opentelemetry/api";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
+import { createOTelResource } from "./utils/createResource";
 import {
   MeterProvider,
   PeriodicExportingMetricReader,
 } from "@opentelemetry/sdk-metrics";
-import {
-  ATTR_NETWORK_LOCAL_ADDRESS,
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-} from "@opentelemetry/semantic-conventions";
-import * as os from "os";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 
 export class StandardMeter {
@@ -26,40 +26,31 @@ export class StandardMeter {
       const collectorOptions = {
         url: config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS,
         headers: {} as Record<string, string>,
-        concurrencyLimit: 1,
+        concurrencyLimit: 5,
       };
       if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-        collectorOptions.headers[
-          "Authorization"
-        ] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+        collectorOptions.headers["Authorization"] =
+          `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
       }
       const metricExporter = new OTLPMetricExporter(collectorOptions);
       meterProvider = new MeterProvider({
-        resource: resourceFromAttributes({
-          [ATTR_SERVICE_NAME]: `${this.serviceName}`,
-          [ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-          [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-        }),
+        resource: createOTelResource(this.serviceName, this.serviceVersion),
         readers: [
           new PeriodicExportingMetricReader({
             exporter: metricExporter,
             exportIntervalMillis:
-              config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS *
-              1000,
+              (config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS ??
+                60) * 1000,
           }),
         ],
       });
     } else {
       meterProvider = new MeterProvider({
-        resource: resourceFromAttributes({
-          [ATTR_SERVICE_NAME]: `${this.serviceName}`,
-          [ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-          [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-        }),
+        resource: createOTelResource(this.serviceName, this.serviceVersion),
       });
     }
     this.meter = meterProvider.getMeter(
-      `${this.serviceName}:${this.serviceVersion}`
+      `${this.serviceName}:${this.serviceVersion}`,
     );
   }
 
@@ -67,7 +58,7 @@ export class StandardMeter {
     return this.meter.createCounter(`${this.serviceName}.${key}`);
   }
 
-  public createUpDownCounter(key: string): Counter {
+  public createUpDownCounter(key: string): UpDownCounter {
     return this.meter.createUpDownCounter(`${this.serviceName}.${key}`);
   }
 
@@ -79,10 +70,12 @@ export class StandardMeter {
     key: string,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     callback: (observableResult: any) => void,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    description: any = null
+    description?: string,
   ): ObservableGauge {
-    const observableGauge = this.meter.createObservableGauge(key, description);
+    const observableGauge = this.meter.createObservableGauge(
+      key,
+      description ? { description } : undefined,
+    );
     observableGauge.addCallback(callback);
     return observableGauge;
   }

package/src/StandardTracer.ts

@@ -8,20 +8,19 @@ import { AsyncHooksContextManager } from "@opentelemetry/context-async-hooks";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
-import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchSpanProcessor, Span } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import {
   ATTR_HTTP_REQUEST_METHOD,
   ATTR_HTTP_ROUTE,
-  ATTR_NETWORK_LOCAL_ADDRESS,
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
 } from "@opentelemetry/semantic-conventions";
-import * as os from "os";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
+import { createOTelResource } from "./utils/createResource";
 
 export class StandardTracer {
+  private static readonly SPAN_NAME_SANITIZE_RE = /[^a-zA-Z0-9-_/]/g;
+  private static readonly PROPAGATOR = new W3CTraceContextPropagator();
+
   private tracer: Tracer;
   private serviceVersion: string;
   private serviceName: string;
@@ -34,9 +33,8 @@ export class StandardTracer {
     if (config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES) {
       const exporterHeaders: Record<string, string> = {};
       if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-        exporterHeaders[
-          "Authorization"
-        ] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+        exporterHeaders["Authorization"] =
+          `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
       }
       const exporter = new OTLPTraceExporter({
         url: config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES,
@@ -46,11 +44,7 @@ export class StandardTracer {
     }
     const traceProvider = new NodeTracerProvider({
       idGenerator: new AWSXRayIdGenerator(),
-      resource: resourceFromAttributes({
-        [ATTR_SERVICE_NAME]: `${this.serviceName}`,
-        [ATTR_SERVICE_VERSION]: `${this.serviceVersion}`,
-        [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
-      }),
+      resource: createOTelResource(this.serviceName, this.serviceVersion),
       spanProcessors,
     });
     traceProvider.register();
@@ -58,24 +52,27 @@ export class StandardTracer {
     contextManager.enable();
     opentelemetry.context.setGlobalContextManager(contextManager);
     this.tracer = opentelemetry.trace.getTracer(
-      `${this.serviceName}:${this.serviceVersion}`
+      `${this.serviceName}:${this.serviceVersion}`,
     );
   }
 
   public startSpan(name: string, parentSpan?: Span): Span {
-    const sanitizedName = String(name).replace(/[^a-zA-Z0-9-_/]/g, "_");
+    const sanitizedName = String(name).replace(
+      StandardTracer.SPAN_NAME_SANITIZE_RE,
+      "_",
+    );
     if (parentSpan) {
       return this.tracer.startSpan(
         sanitizedName,
         undefined,
-        opentelemetry.trace.setSpan(opentelemetry.context.active(), parentSpan)
+        opentelemetry.trace.setSpan(opentelemetry.context.active(), parentSpan),
       ) as Span;
     }
     const span = this.tracer.startSpan(sanitizedName) as Span;
     span.setAttribute(ATTR_HTTP_REQUEST_METHOD, `BACKEND`);
     span.setAttribute(
       ATTR_HTTP_ROUTE,
-      `${this.serviceName}-${this.serviceVersion}-${sanitizedName}`
+      `${this.serviceName}-${this.serviceVersion}-${sanitizedName}`,
     );
     return span;
   }
@@ -85,12 +82,11 @@ export class StandardTracer {
     if (!headers) {
       headers = {};
     }
-    const propagator = new W3CTraceContextPropagator();
-    propagator.inject(
+    StandardTracer.PROPAGATOR.inject(
       trace.setSpanContext(ROOT_CONTEXT, context.spanContext()),
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       headers as any,
-      defaultTextMapSetter
+      defaultTextMapSetter,
     );
     return headers;
   }

package/src/models/ConfigOTelInterface.ts

@@ -1,11 +1,11 @@
 export interface ConfigOTelInterface {
   SERVICE_ID: string;
   VERSION: string;
-  OPENTELEMETRY_COLLECTOR_HTTP_TRACES: string;
-  OPENTELEMETRY_COLLECTOR_HTTP_METRICS: string;
-  OPENTELEMETRY_COLLECTOR_HTTP_LOGS: string;
-  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: number;
-  OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: number;
-  OPENTELEMETRY_COLLECTOR_AWS: boolean;
-  OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: string;
+  OPENTELEMETRY_COLLECTOR_HTTP_TRACES?: string;
+  OPENTELEMETRY_COLLECTOR_HTTP_METRICS?: string;
+  OPENTELEMETRY_COLLECTOR_HTTP_LOGS?: string;
+  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS?: number;
+  OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS?: number;
+  OPENTELEMETRY_COLLECTOR_AWS?: boolean;
+  OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER?: string;
 }

package/src/utils/createResource.ts

@@ -0,0 +1,20 @@
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  ATTR_NETWORK_LOCAL_ADDRESS,
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+import * as os from "os";
+
+const CACHED_HOSTNAME = os.hostname();
+
+export function createOTelResource(
+  serviceName: string,
+  serviceVersion: string,
+) {
+  return resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: serviceName,
+    [ATTR_SERVICE_VERSION]: serviceVersion,
+    [ATTR_NETWORK_LOCAL_ADDRESS]: CACHED_HOSTNAME,
+  });
+}