@devopsplaybook.io/otel-utils 1.5.3 → 1.6.0-beta.37.40daec3

package/README.md

@@ -23,19 +23,21 @@ All classes accept a `ConfigOTelInterface` object:
 | `OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS` | `number?`  | `60`    | Metrics export interval         |
 | `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.
+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`).
 
 ## Exported Classes
 
 ### StandardTracer
 
-Sets up a global `NodeTracerProvider` with:
+Creates a `TracerProvider` with:
 
 - AWS X-Ray ID generator (`AWSXRayIdGenerator`)
 - OTLP HTTP trace exporter (optional, when `OPENTELEMETRY_COLLECTOR_HTTP_TRACES` is set)
-- `AsyncHooksContextManager` for automatic context propagation
+- one process-wide `AsyncLocalStorageContextManager`, installed on first construction when no other context manager is registered (kept for the process lifetime)
 - Service resource attributes (name, version, hostname)
 
+The instance exports its spans through its own provider (`tracer.startSpan(...)` is always routed to this instance). The first `StandardTracer` constructed in a process also registers its provider as the global one, so `trace.getTracer(...)` from `@opentelemetry/api` resolves to it. Later instances do not replace the global provider: they log a warning and keep exporting through their own provider — see [Provider lifecycle](#provider-lifecycle).
+
 ```typescript
 import { StandardTracer } from "@devopsplaybook.io/otel-utils";
 
@@ -49,17 +51,17 @@ span.end();
 
 - `startSpan(name, parentSpan?, options?)` — Creates a span. Span names are sanitized to `[a-zA-Z0-9-_/]`. When neither `parentSpan` nor `options` is given, the span is `SpanKind.INTERNAL` and carries `http.request_method=BACKEND` and a synthetic `http.route` attribute. Passing `options` (e.g. `{ kind: SpanKind.SERVER }`) forwards them to the OpenTelemetry SDK instead and skips those synthetic attributes, because the caller then describes the span itself.
 - `static updateHttpHeader(context, headers?)` — Injects W3C trace context into an HTTP headers object for propagation to downstream services.
-- `shutdown()` — Flushes buffered spans and shuts the tracer provider down.
+- `shutdown()` — Flushes buffered spans and shuts the tracer provider down. Idempotent.
 
 ### 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, so `logs.getLogger(...)` from `@opentelemetry/api-logs` returns loggers wired to the configured exporter. Without that endpoint, `initOTel` still records the service identity but registers nothing globally and `getLogger()` returns `undefined`.
+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`.
 
 ```typescript
 import { StandardLogger } from "@devopsplaybook.io/otel-utils";
 
 const logger = new StandardLogger();
-logger.initOTel(config);
+await logger.initOTel(config);
 
 const moduleLog = logger.createModuleLogger("my-module");
 moduleLog.info("Hello world");
@@ -67,10 +69,10 @@ moduleLog.info("Hello world");
 
 **Methods:**
 
-- `initOTel(config)` — Initializes the logger provider and optional OTLP exporter, and registers the provider globally when a logs endpoint is configured.
-- `getLogger()` — Returns the underlying OTel `Logger` or `undefined`.
+- `initOTel(config)` — Initializes the logger provider and optional OTLP exporter, and registers the provider globally when a logs endpoint is configured and no other logger provider is registered. Returns `Promise<void>`: the first call initializes synchronously; await it when re-initializing, because a previous provider is flushed and shut down first.
+- `getLogger()` — Returns the underlying OTel `Logger` or `undefined` (also `undefined` after `shutdown()`).
 - `createModuleLogger(moduleName)` — Creates a `ModuleLogger` scoped to a module name.
-- `shutdown()` — Flushes buffered log records and shuts the logger provider down. No-op when no logs endpoint is configured.
+- `shutdown()` — Flushes buffered log records and shuts the logger provider down. Idempotent. No-op when no logs endpoint is configured.
 
 ### ModuleLogger
 
@@ -94,7 +96,7 @@ When a `Span` is passed as `context`, the log record includes `span.id` and `tra
 
 ### StandardMeter
 
-Creates a `MeterProvider` with an optional `PeriodicExportingMetricReader` (`concurrencyLimit: 5`). Provides convenience factories for common metric types.
+Creates a `MeterProvider` with an optional `PeriodicExportingMetricReader` (`concurrencyLimit: 5`). Provides convenience factories for common metric types. When `OPENTELEMETRY_COLLECTOR_HTTP_METRICS` is set, the provider is registered as the global meter provider (first instance only), so metrics emitted through `metrics.getMeter(...)` reach the configured exporter. Unconfigured meters leave the global API untouched (Noop).
 
 ```typescript
 import { StandardMeter } from "@devopsplaybook.io/otel-utils";
@@ -123,22 +125,44 @@ const cpuGauge = meter.createObservableGauge(
 - `createUpDownCounter(key)` — Creates an `UpDownCounter`.
 - `createHistogram(key, options?)` — Creates a `Histogram` named `${serviceName}.${key}`; with `{ unprefixed: true }` the histogram is created exactly as `key`, without the service-name prefix.
 - `createObservableGauge(key, callback, description?)` — Creates an `ObservableGauge` with a callback. Description is optional.
-- `shutdown()` — Flushes buffered metrics and shuts the meter provider down.
+- `shutdown()` — Flushes buffered metrics and shuts the meter provider down. Idempotent.
+
+## Provider lifecycle
+
+OpenTelemetry's global API accepts one provider per signal per process, and the registration is one-shot until the global API is disabled. `otel-utils` manages this as follows:
+
+- **One provider per signal per process.** The first `StandardTracer`, configured `StandardLogger` and configured `StandardMeter` created in a process each register their provider globally. Global-API calls (`trace.getTracer`, `logs.getLogger`, `metrics.getMeter`) resolve to those first providers until they shut down.
+- **Additional instances keep working, locally.** A second instance does not replace the global provider: it logs a `console.warn` and still exports through its own provider, with its own `service.name`/`service.version`. Its records/spans/metrics are never attributed to another service.
+- **Re-initialisation.** Calling `StandardLogger.initOTel()` again on the same instance flushes and shuts down the previous provider (its buffered records are exported), then registers the new one as the global provider if possible. Await the returned promise when re-initializing.
+- **Shutdown.** `shutdown()` flushes pending telemetry, shuts the provider down and is idempotent. If the instance owns the global provider, it also calls `trace.disable()` / `logs.disable()` / `metrics.disable()`, returning the global API to Noop and allowing a later instance to register again. Shutting down a non-owner leaves the global provider untouched. After `StandardLogger.shutdown()`, `getLogger()` is `undefined`.
+- **Context propagation.** One `AsyncLocalStorageContextManager` is installed per process on the first `StandardTracer` construction, only when no other context manager is registered. It stays active for the process lifetime (it is never disabled), so re-initialisation keeps working.
 
 ## Graceful shutdown
 
-`StandardTracer`, `StandardLogger` and `StandardMeter` buffer telemetry: `BatchSpanProcessor`, `BatchLogRecordProcessor` and `PeriodicExportingMetricReader` hold data until their next export cycle. On process exit that buffered data would be lost, so wire the `shutdown()` methods to `SIGTERM`/`SIGINT` handlers:
+`StandardTracer`, `StandardLogger` and `StandardMeter` buffer telemetry: `BatchSpanProcessor`, `BatchLogRecordProcessor` and `PeriodicExportingMetricReader` hold data until their next export cycle. On process exit that buffered data would be lost, so flush it on `SIGTERM`/`SIGINT`.
+
+The opt-in `registerShutdownHooks` helper does this for every configured provider and exits the process with code 0 after flushing:
+
+```typescript
+import { registerShutdownHooks } from "@devopsplaybook.io/otel-utils";
+
+const cleanup = registerShutdownHooks([tracer, logger, meter]);
+// later, if the application manages its own signals:
+// cleanup();
+```
+
+Register it once, with all configured providers. A second signal received while shutting down does not exit or flush again. The returned function only removes the signal listeners.
+
+For custom flows, `shutdownAll` flushes every provider and always resolves — a failing provider is reported with `console.warn` and does not block the others:
 
 ```typescript
-const shutdown = async () => {
-  await Promise.all([tracer.shutdown(), logger.shutdown(), meter.shutdown()]);
-  process.exit(0);
-};
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
+import { shutdownAll } from "@devopsplaybook.io/otel-utils";
+
+await shutdownAll([tracer, logger, meter]);
+process.exit(0);
 ```
 
-Each `shutdown()` flushes pending telemetry to the collector before resolving; the methods are idempotent and can be called even when a signal was not configured (they resolve immediately).
+Each `shutdown()` flushes pending telemetry to the collector before resolving; the methods are idempotent and can be called even when no collector was configured (they resolve immediately).
 
 ## Internal Utilities
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./src/models/ConfigOTelInterface";
 export * from "./src/models/StandardLoggerInterface";
 export * from "./src/ModuleLogger";
+export * from "./src/ShutdownHooks";
 export * from "./src/StandardLogger";
 export * from "./src/StandardMeter";
 export * from "./src/StandardTracer";

package/dist/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./src/models/ConfigOTelInterface"), exports);
 __exportStar(require("./src/models/StandardLoggerInterface"), exports);
 __exportStar(require("./src/ModuleLogger"), exports);
+__exportStar(require("./src/ShutdownHooks"), exports);
 __exportStar(require("./src/StandardLogger"), exports);
 __exportStar(require("./src/StandardMeter"), exports);
 __exportStar(require("./src/StandardTracer"), exports);

package/dist/src/ShutdownHooks.d.ts

@@ -0,0 +1,16 @@
+export interface ShutdownableInterface {
+    shutdown(): Promise<void>;
+}
+/**
+ * Flushes and shuts down every provider, resolving even when one of them
+ * fails (the failure is reported with `console.warn`).
+ */
+export declare function shutdownAll(providers: ReadonlyArray<ShutdownableInterface>): Promise<void>;
+/**
+ * Registers one-shot `SIGTERM`/`SIGINT` handlers that flush and shut down all
+ * providers, then exit the process with code 0.
+ *
+ * Register once with every configured provider. The returned function removes
+ * the handlers without shutting anything down.
+ */
+export declare function registerShutdownHooks(providers: ReadonlyArray<ShutdownableInterface>): () => void;

package/dist/src/ShutdownHooks.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdownAll = shutdownAll;
+exports.registerShutdownHooks = registerShutdownHooks;
+/**
+ * Flushes and shuts down every provider, resolving even when one of them
+ * fails (the failure is reported with `console.warn`).
+ */
+async function shutdownAll(providers) {
+    await Promise.all(providers.map((provider) => provider.shutdown().catch((error) => {
+        console.warn("[otel-utils] shutdown failed", error);
+    })));
+}
+/**
+ * Registers one-shot `SIGTERM`/`SIGINT` handlers that flush and shut down all
+ * providers, then exit the process with code 0.
+ *
+ * Register once with every configured provider. The returned function removes
+ * the handlers without shutting anything down.
+ */
+function registerShutdownHooks(providers) {
+    let shuttingDown = false;
+    const onSignal = () => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        void shutdownAll(providers).then(() => process.exit(0));
+    };
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+    return () => {
+        process.removeListener("SIGTERM", onSignal);
+        process.removeListener("SIGINT", onSignal);
+    };
+}

package/dist/src/StandardLogger.d.ts

@@ -7,8 +7,12 @@ export declare class StandardLogger implements StandardLoggerInterface {
     private loggerProvider?;
     private serviceVersion?;
     private serviceName?;
-    initOTel(config: ConfigOTelInterface): void;
+    private ownsGlobalProvider;
+    private shutdownPromise?;
+    initOTel(config: ConfigOTelInterface): Promise<void>;
     shutdown(): Promise<void>;
     getLogger(): OTelLogger | undefined;
     createModuleLogger(moduleName: string): ModuleLogger;
+    private registerGlobalProvider;
+    private releaseProvider;
 }

package/dist/src/StandardLogger.js

@@ -6,38 +6,51 @@ const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-htt
 const sdk_logs_1 = require("@opentelemetry/sdk-logs");
 const createResource_1 = require("./utils/createResource");
 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 {
-    initOTel(config) {
+    constructor() {
+        this.ownsGlobalProvider = false;
+    }
+    async initOTel(config) {
         var _a;
+        // Re-initialisation flushes and unregisters the previous provider first.
+        if (this.loggerProvider) {
+            await this.releaseProvider();
+        }
+        this.shutdownPromise = undefined;
         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}`;
-            }
-            const exporter = new exporter_logs_otlp_http_1.OTLPLogExporter({
-                url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
-                headers: exporterHeaders,
-            });
-            this.loggerProvider = new sdk_logs_1.LoggerProvider({
-                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,
-                    }),
-                ],
-                resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
-            });
-            api_1.logs.setGlobalLoggerProvider(this.loggerProvider);
-            this.logger = this.loggerProvider.getLogger(`${this.serviceName}:${this.serviceVersion}`);
+        if (!config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS) {
+            return;
+        }
+        const exporterHeaders = {};
+        if (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,
+            headers: exporterHeaders,
+        });
+        this.loggerProvider = new sdk_logs_1.LoggerProvider({
+            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,
+                }),
+            ],
+            resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
+        });
+        this.logger = this.loggerProvider.getLogger(`${this.serviceName}:${this.serviceVersion}`);
+        this.registerGlobalProvider();
     }
-    async shutdown() {
-        var _a;
-        await ((_a = this.loggerProvider) === null || _a === void 0 ? void 0 : _a.shutdown());
+    shutdown() {
+        if (!this.shutdownPromise) {
+            this.shutdownPromise = this.releaseProvider();
+        }
+        return this.shutdownPromise;
     }
     getLogger() {
         return this.logger;
@@ -45,5 +58,40 @@ class StandardLogger {
     createModuleLogger(moduleName) {
         return new ModuleLogger_1.ModuleLogger(moduleName, this);
     }
+    registerGlobalProvider() {
+        if (globalLoggerProvider) {
+            if (globalLoggerProvider === api_1.logs.getLoggerProvider()) {
+                console.warn(ALREADY_REGISTERED_WARNING);
+                return;
+            }
+            // The previous provider is no longer registered (disabled elsewhere).
+            globalLoggerProvider = undefined;
+        }
+        if (this.loggerProvider &&
+            api_1.logs.setGlobalLoggerProvider(this.loggerProvider)) {
+            globalLoggerProvider = this.loggerProvider;
+            this.ownsGlobalProvider = true;
+        }
+        else {
+            console.warn(ALREADY_REGISTERED_WARNING);
+        }
+    }
+    async releaseProvider() {
+        const provider = this.loggerProvider;
+        const ownedGlobalProvider = this.ownsGlobalProvider;
+        this.logger = undefined;
+        this.loggerProvider = undefined;
+        this.ownsGlobalProvider = false;
+        if (!provider) {
+            return;
+        }
+        await provider.shutdown();
+        if (ownedGlobalProvider && api_1.logs.getLoggerProvider() === provider) {
+            api_1.logs.disable();
+        }
+        if (globalLoggerProvider === provider) {
+            globalLoggerProvider = undefined;
+        }
+    }
 }
 exports.StandardLogger = StandardLogger;

package/dist/src/StandardMeter.d.ts

@@ -15,10 +15,14 @@ export declare class StandardMeter {
     private meterProvider;
     private serviceVersion;
     private serviceName;
+    private ownsGlobalProvider;
+    private shutdownPromise?;
     constructor(config: ConfigOTelInterface);
     shutdown(): Promise<void>;
     createCounter(key: string): Counter;
     createUpDownCounter(key: string): UpDownCounter;
     createHistogram(key: string, options?: StandardMeterCreateHistogramOptions): Histogram;
     createObservableGauge(key: string, callback: (observableResult: any) => void, description?: string): ObservableGauge;
+    private registerGlobalProvider;
+    private doShutdown;
 }

package/dist/src/StandardMeter.js

@@ -1,15 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StandardMeter = void 0;
+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");
+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;
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
+        let hasCollector = false;
         if (config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS) {
+            hasCollector = true;
             const collectorOptions = {
                 url: config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS,
                 headers: {},
@@ -36,9 +42,15 @@ class StandardMeter {
             });
         }
         this.meter = this.meterProvider.getMeter(`${this.serviceName}:${this.serviceVersion}`);
+        if (hasCollector) {
+            this.registerGlobalProvider();
+        }
     }
-    async shutdown() {
-        await this.meterProvider.shutdown();
+    shutdown() {
+        if (!this.shutdownPromise) {
+            this.shutdownPromise = this.doShutdown();
+        }
+        return this.shutdownPromise;
     }
     createCounter(key) {
         return this.meter.createCounter(`${this.serviceName}.${key}`);
@@ -56,5 +68,33 @@ class StandardMeter {
         observableGauge.addCallback(callback);
         return observableGauge;
     }
+    registerGlobalProvider() {
+        if (globalMeterProvider) {
+            if (globalMeterProvider === api_1.metrics.getMeterProvider()) {
+                console.warn(ALREADY_REGISTERED_WARNING);
+                return;
+            }
+            // The previous provider is no longer registered (disabled elsewhere).
+            globalMeterProvider = undefined;
+        }
+        if (api_1.metrics.setGlobalMeterProvider(this.meterProvider)) {
+            globalMeterProvider = this.meterProvider;
+            this.ownsGlobalProvider = true;
+        }
+        else {
+            console.warn(ALREADY_REGISTERED_WARNING);
+        }
+    }
+    async doShutdown() {
+        await this.meterProvider.shutdown();
+        if (this.ownsGlobalProvider &&
+            api_1.metrics.getMeterProvider() === this.meterProvider) {
+            api_1.metrics.disable();
+        }
+        if (globalMeterProvider === this.meterProvider) {
+            globalMeterProvider = undefined;
+        }
+        this.ownsGlobalProvider = false;
+    }
 }
 exports.StandardMeter = StandardMeter;

package/dist/src/StandardTracer.d.ts

@@ -22,8 +22,12 @@ export declare class StandardTracer {
     private tracer;
     private serviceVersion;
     private serviceName;
+    private ownsGlobalProvider;
+    private shutdownPromise?;
     constructor(config: ConfigOTelInterface);
     shutdown(): Promise<void>;
     startSpan(name: string, parentSpan?: Span, options?: StandardTracerStartSpanOptions): Span;
     static updateHttpHeader(context: ApiSpan, headers?: {}): any;
+    private registerGlobalProvider;
+    private doShutdown;
 }

package/dist/src/StandardTracer.js

@@ -1,40 +1,7 @@
 "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.StandardTracer = void 0;
-const api_1 = __importStar(require("@opentelemetry/api"));
+const api_1 = require("@opentelemetry/api");
 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");
@@ -42,8 +9,18 @@ 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 createResource_1 = require("./utils/createResource");
+let globalTracerProvider;
+let contextManagerInitialized = false;
+function getRegisteredTracerProvider() {
+    const provider = api_1.trace.getTracerProvider();
+    return typeof provider.getDelegate === "function"
+        ? provider.getDelegate()
+        : provider;
+}
+const ALREADY_REGISTERED_WARNING = "[otel-utils] A global tracer provider is already registered; StandardTracer will not replace it. This instance still exports spans through its own provider, but trace.getTracer() keeps using the existing provider.";
 class StandardTracer {
     constructor(config) {
+        this.ownsGlobalProvider = false;
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
         const spanProcessors = [];
@@ -64,21 +41,22 @@ class StandardTracer {
             resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             spanProcessors,
         });
-        // OTel v3 removed TracerProvider.register(): the provider and the context
-        // manager must be installed on the global API explicitly.
-        api_1.trace.setGlobalTracerProvider(this.traceProvider);
-        const contextManager = new context_async_hooks_1.AsyncLocalStorageContextManager();
-        contextManager.enable();
-        api_1.default.context.setGlobalContextManager(contextManager);
-        this.tracer = api_1.default.trace.getTracer(`${this.serviceName}:${this.serviceVersion}`);
+        // Resolve the tracer from this instance's provider: the global API may be
+        // owned by another instance and would silently export through it.
+        this.tracer = this.traceProvider.getTracer(`${this.serviceName}:${this.serviceVersion}`);
+        this.registerGlobalProvider();
+        initializeContextManager();
     }
-    async shutdown() {
-        await this.traceProvider.shutdown();
+    shutdown() {
+        if (!this.shutdownPromise) {
+            this.shutdownPromise = this.doShutdown();
+        }
+        return this.shutdownPromise;
     }
     startSpan(name, parentSpan, options) {
         const sanitizedName = name.replace(StandardTracer.SPAN_NAME_SANITIZE_RE, "_");
         if (parentSpan) {
-            return this.tracer.startSpan(sanitizedName, options, api_1.default.trace.setSpan(api_1.default.context.active(), parentSpan));
+            return this.tracer.startSpan(sanitizedName, options, api_1.trace.setSpan(api_1.context.active(), parentSpan));
         }
         if (options) {
             return this.tracer.startSpan(sanitizedName, options);
@@ -95,7 +73,48 @@ class StandardTracer {
         headers, api_1.defaultTextMapSetter);
         return headers;
     }
+    registerGlobalProvider() {
+        if (globalTracerProvider) {
+            if (getRegisteredTracerProvider() === globalTracerProvider) {
+                console.warn(ALREADY_REGISTERED_WARNING);
+                return;
+            }
+            // The previous provider is no longer registered (disabled elsewhere).
+            globalTracerProvider = undefined;
+        }
+        if (api_1.trace.setGlobalTracerProvider(this.traceProvider)) {
+            globalTracerProvider = this.traceProvider;
+            this.ownsGlobalProvider = true;
+        }
+        else {
+            console.warn(ALREADY_REGISTERED_WARNING);
+        }
+    }
+    async doShutdown() {
+        await this.traceProvider.shutdown();
+        if (this.ownsGlobalProvider &&
+            getRegisteredTracerProvider() === this.traceProvider) {
+            api_1.trace.disable();
+        }
+        if (globalTracerProvider === this.traceProvider) {
+            globalTracerProvider = undefined;
+        }
+        this.ownsGlobalProvider = false;
+    }
 }
 exports.StandardTracer = StandardTracer;
 StandardTracer.SPAN_NAME_SANITIZE_RE = /[^a-zA-Z0-9-_/]/g;
 StandardTracer.PROPAGATOR = new core_1.W3CTraceContextPropagator();
+function initializeContextManager() {
+    if (contextManagerInitialized) {
+        return;
+    }
+    contextManagerInitialized = true;
+    const contextManager = new context_async_hooks_1.AsyncLocalStorageContextManager();
+    if (api_1.context.setGlobalContextManager(contextManager)) {
+        contextManager.enable();
+    }
+    else {
+        console.warn("[otel-utils] A global context manager is already registered; StandardTracer will keep using it for context propagation.");
+    }
+}

package/index.ts

@@ -1,6 +1,7 @@
 export * from "./src/models/ConfigOTelInterface";
 export * from "./src/models/StandardLoggerInterface";
 export * from "./src/ModuleLogger";
+export * from "./src/ShutdownHooks";
 export * from "./src/StandardLogger";
 export * from "./src/StandardMeter";
 export * from "./src/StandardTracer";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils",
-  "version": "1.5.3",
+  "version": "1.6.0-beta.37.40daec3",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",