@devopsplaybook.io/otel-utils 1.3.1 → 1.4.0-beta.32.a33ff6f

package/README.md

@@ -21,7 +21,6 @@ All classes accept a `ConfigOTelInterface` object:
 | `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.
@@ -50,10 +49,11 @@ 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.
 
 ### StandardLogger
 
-Initializes a `LoggerProvider` with an OTLP log exporter and a `BatchLogRecordProcessor` (`maxQueueSize: 2048`).
+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`.
 
 ```typescript
 import { StandardLogger } from "@devopsplaybook.io/otel-utils";
@@ -67,9 +67,10 @@ moduleLog.info("Hello world");
 
 **Methods:**
 
-- `initOTel(config)` — Initializes the logger provider and optional OTLP exporter.
+- `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`.
 - `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.
 
 ### ModuleLogger
 
@@ -122,6 +123,22 @@ const cpuGauge = meter.createObservableGauge(
 - `createUpDownCounter(key)` — Creates an `UpDownCounter`.
 - `createHistogram(key)` — Creates a `Histogram`.
 - `createObservableGauge(key, callback, description?)` — Creates an `ObservableGauge` with a callback. Description is optional.
+- `shutdown()` — Flushes buffered metrics and shuts the meter provider down.
+
+## 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:
+
+```typescript
+const shutdown = async () => {
+  await Promise.all([tracer.shutdown(), logger.shutdown(), meter.shutdown()]);
+  process.exit(0);
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+```
+
+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).
 
 ## Internal Utilities
 

package/dist/src/ModuleLogger.d.ts

@@ -1,8 +1,8 @@
+import type { Span } from "@opentelemetry/api";
 import { StandardLoggerInterface } from "./models/StandardLoggerInterface";
-import { Span } from "@opentelemetry/sdk-trace-base";
 export declare class ModuleLogger {
     private module;
-    private standardLogger?;
+    private standardLogger;
     constructor(module: string, standardLogger: StandardLoggerInterface);
     info(message: string, context?: Span): void;
     warn(message: string, context?: Span): void;

package/dist/src/ModuleLogger.js

@@ -17,31 +17,27 @@ class ModuleLogger {
         this.display("error", message, api_logs_1.SeverityNumber.ERROR, error, context);
     }
     display(level, message, severityNumber = api_logs_1.SeverityNumber.INFO, error, context) {
-        var _a, _b;
-        let formattedMessage = message;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const attributes = { "log.type": "custom" };
         if (error) {
             attributes["exception.type"] = error.name;
             attributes["exception.message"] = error.message;
             attributes["exception.stacktrace"] = error.stack;
-            formattedMessage += "\n" + error.stack;
         }
         if (context) {
             const spanCtx = context.spanContext();
-            if (spanCtx) {
-                attributes["span.id"] = spanCtx.spanId;
-                attributes["trace.id"] = spanCtx.traceId;
-            }
+            attributes["span.id"] = spanCtx.spanId;
+            attributes["trace.id"] = spanCtx.traceId;
         }
-        console.log(`[${level}] [${this.module}] ${formattedMessage}`);
-        if (!((_a = this.standardLogger) === null || _a === void 0 ? void 0 : _a.getLogger())) {
+        console.log(`[${level}] [${this.module}] ${message}`);
+        const logger = this.standardLogger.getLogger();
+        if (!logger) {
             return;
         }
-        (_b = this.standardLogger.getLogger()) === null || _b === void 0 ? void 0 : _b.emit({
+        logger.emit({
             severityNumber,
             severityText: level,
-            body: `[${this.module}] ${formattedMessage}`,
+            body: `[${this.module}] ${message}`,
             attributes,
         });
     }

package/dist/src/StandardLogger.d.ts

@@ -1,12 +1,14 @@
-import type { Logger as OTelLogger } from "@opentelemetry/api-logs";
+import { type Logger as OTelLogger } from "@opentelemetry/api-logs";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { ModuleLogger } from "./ModuleLogger";
 import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
 export declare class StandardLogger implements StandardLoggerInterface {
     private logger?;
+    private loggerProvider?;
     private serviceVersion?;
     private serviceName?;
     initOTel(config: ConfigOTelInterface): void;
+    shutdown(): Promise<void>;
     getLogger(): OTelLogger | undefined;
     createModuleLogger(moduleName: string): ModuleLogger;
 }

package/dist/src/StandardLogger.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StandardLogger = void 0;
+const api_logs_1 = require("@opentelemetry/api-logs");
 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");
@@ -20,7 +21,7 @@ class StandardLogger {
                 url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
                 headers: exporterHeaders,
             });
-            const loggerProvider = new sdk_logs_1.LoggerProvider({
+            this.loggerProvider = new sdk_logs_1.LoggerProvider({
                 processors: [
                     new sdk_logs_1.BatchLogRecordProcessor({
                         exporter,
@@ -30,9 +31,14 @@ class StandardLogger {
                 ],
                 resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             });
-            this.logger = loggerProvider.getLogger(`${this.serviceName}:${this.serviceVersion}`);
+            api_logs_1.logs.setGlobalLoggerProvider(this.loggerProvider);
+            this.logger = this.loggerProvider.getLogger(`${this.serviceName}:${this.serviceVersion}`);
         }
     }
+    async shutdown() {
+        var _a;
+        await ((_a = this.loggerProvider) === null || _a === void 0 ? void 0 : _a.shutdown());
+    }
     getLogger() {
         return this.logger;
     }

package/dist/src/StandardMeter.d.ts

@@ -2,9 +2,11 @@ import { Counter, Histogram, ObservableGauge, UpDownCounter } from "@opentelemet
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 export declare class StandardMeter {
     private meter;
+    private meterProvider;
     private serviceVersion;
     private serviceName;
     constructor(config: ConfigOTelInterface);
+    shutdown(): Promise<void>;
     createCounter(key: string): Counter;
     createUpDownCounter(key: string): UpDownCounter;
     createHistogram(key: string): Histogram;

package/dist/src/StandardMeter.js

@@ -9,7 +9,6 @@ class StandardMeter {
         var _a;
         this.serviceName = config.SERVICE_ID;
         this.serviceVersion = config.VERSION;
-        let meterProvider;
         if (config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS) {
             const collectorOptions = {
                 url: config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS,
@@ -21,7 +20,7 @@ class StandardMeter {
                     `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
             }
             const metricExporter = new exporter_metrics_otlp_http_1.OTLPMetricExporter(collectorOptions);
-            meterProvider = new sdk_metrics_1.MeterProvider({
+            this.meterProvider = new sdk_metrics_1.MeterProvider({
                 resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
                 readers: [
                     new sdk_metrics_1.PeriodicExportingMetricReader({
@@ -32,11 +31,14 @@ class StandardMeter {
             });
         }
         else {
-            meterProvider = new sdk_metrics_1.MeterProvider({
+            this.meterProvider = new sdk_metrics_1.MeterProvider({
                 resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             });
         }
-        this.meter = meterProvider.getMeter(`${this.serviceName}:${this.serviceVersion}`);
+        this.meter = this.meterProvider.getMeter(`${this.serviceName}:${this.serviceVersion}`);
+    }
+    async shutdown() {
+        await this.meterProvider.shutdown();
     }
     createCounter(key) {
         return this.meter.createCounter(`${this.serviceName}.${key}`);

package/dist/src/StandardTracer.d.ts

@@ -1,4 +1,5 @@
 import { SpanKind } from "@opentelemetry/api";
+import type { Span as ApiSpan } from "@opentelemetry/api";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 /**
@@ -17,10 +18,12 @@ export interface StandardTracerStartSpanOptions {
 export declare class StandardTracer {
     private static readonly SPAN_NAME_SANITIZE_RE;
     private static readonly PROPAGATOR;
+    private traceProvider;
     private tracer;
     private serviceVersion;
     private serviceName;
     constructor(config: ConfigOTelInterface);
+    shutdown(): Promise<void>;
     startSpan(name: string, parentSpan?: Span, options?: StandardTracerStartSpanOptions): Span;
-    static updateHttpHeader(context: Span, headers?: {}): any;
+    static updateHttpHeader(context: ApiSpan, headers?: {}): any;
 }

package/dist/src/StandardTracer.js

@@ -60,19 +60,22 @@ class StandardTracer {
             });
             spanProcessors.push(new sdk_trace_base_1.BatchSpanProcessor(exporter));
         }
-        const traceProvider = new sdk_trace_node_1.NodeTracerProvider({
+        this.traceProvider = new sdk_trace_node_1.NodeTracerProvider({
             idGenerator: new id_generator_aws_xray_1.AWSXRayIdGenerator(),
             resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             spanProcessors,
         });
-        traceProvider.register();
+        this.traceProvider.register();
         const contextManager = new context_async_hooks_1.AsyncHooksContextManager();
         contextManager.enable();
         api_1.default.context.setGlobalContextManager(contextManager);
         this.tracer = api_1.default.trace.getTracer(`${this.serviceName}:${this.serviceVersion}`);
     }
+    async shutdown() {
+        await this.traceProvider.shutdown();
+    }
     startSpan(name, parentSpan, options) {
-        const sanitizedName = String(name).replace(StandardTracer.SPAN_NAME_SANITIZE_RE, "_");
+        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));
         }
@@ -86,9 +89,6 @@ class StandardTracer {
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static updateHttpHeader(context, headers = {}) {
-        if (!headers) {
-            headers = {};
-        }
         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);

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

@@ -6,6 +6,5 @@ export interface ConfigOTelInterface {
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils",
-  "version": "1.3.1",
+  "version": "1.4.0-beta.32.a33ff6f",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",
@@ -23,7 +23,6 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.222.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
     "@opentelemetry/context-async-hooks": "^2.11.0",
     "@opentelemetry/core": "^2.11.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
@@ -33,10 +32,8 @@
     "@opentelemetry/resources": "^2.11.0",
     "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.11.0",
-    "@opentelemetry/sdk-node": "^0.222.0",
     "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
-    "@opentelemetry/sdk-trace-web": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0"
   },
   "devDependencies": {

package/src/ModuleLogger.spec.ts

@@ -0,0 +1,101 @@
+import type { Span } from "@opentelemetry/api";
+import {
+  SeverityNumber,
+  type Logger as OTelLogger,
+} from "@opentelemetry/api-logs";
+import { ModuleLogger } from "./ModuleLogger";
+import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
+
+describe("ModuleLogger", () => {
+  let consoleSpy: jest.SpyInstance;
+  let emit: jest.Mock;
+
+  beforeEach(() => {
+    emit = jest.fn();
+    consoleSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  function createLogger(
+    getLogger: () => OTelLogger | undefined,
+  ): StandardLoggerInterface {
+    return { getLogger };
+  }
+
+  function loggerWithEmit(): ModuleLogger {
+    const fakeLogger = { emit } as unknown as OTelLogger;
+    return new ModuleLogger("billing", createLogger(() => fakeLogger));
+  }
+
+  it("logs info to console and the OTel logger", () => {
+    loggerWithEmit().info("hello");
+
+    expect(consoleSpy).toHaveBeenCalledWith("[info] [billing] hello");
+    expect(emit).toHaveBeenCalledWith({
+      severityNumber: SeverityNumber.INFO,
+      severityText: "info",
+      body: "[billing] hello",
+      attributes: { "log.type": "custom" },
+    });
+  });
+
+  it("logs warn at WARN severity", () => {
+    loggerWithEmit().warn("careful");
+
+    expect(consoleSpy).toHaveBeenCalledWith("[warn] [billing] careful");
+    expect(emit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        severityNumber: SeverityNumber.WARN,
+        severityText: "warn",
+        body: "[billing] careful",
+      }),
+    );
+  });
+
+  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",
+        "exception.type": "Error",
+        "exception.message": "boom",
+        "exception.stacktrace": error.stack,
+      },
+    });
+  });
+
+  it("adds span and trace ids when a span context is provided", () => {
+    const span = {
+      spanContext: () => ({ spanId: "span-1", traceId: "trace-1" }),
+    } as unknown as Span;
+
+    loggerWithEmit().info("inside a span", span);
+
+    expect(emit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({
+          "span.id": "span-1",
+          "trace.id": "trace-1",
+        }),
+      }),
+    );
+  });
+
+  it("falls back to console only when no OTel logger is available", () => {
+    const logger = new ModuleLogger("billing", createLogger(() => undefined));
+
+    logger.warn("offline");
+
+    expect(consoleSpy).toHaveBeenCalledWith("[warn] [billing] offline");
+    expect(emit).not.toHaveBeenCalled();
+  });
+});

package/src/ModuleLogger.ts

@@ -1,10 +1,10 @@
 import { SeverityNumber } from "@opentelemetry/api-logs";
+import type { Span } from "@opentelemetry/api";
 import { StandardLoggerInterface } from "./models/StandardLoggerInterface";
-import { Span } from "@opentelemetry/sdk-trace-base";
 
 export class ModuleLogger {
   private module: string;
-  private standardLogger?: StandardLoggerInterface;
+  private standardLogger: StandardLoggerInterface;
 
   constructor(module: string, standardLogger: StandardLoggerInterface) {
     this.module = module;
@@ -30,8 +30,6 @@ export class ModuleLogger {
     error?: Error | null,
     context?: Span,
   ): void {
-    let formattedMessage = message;
-
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const attributes: Record<string, any> = { "log.type": "custom" };
 
@@ -39,25 +37,23 @@ export class ModuleLogger {
       attributes["exception.type"] = error.name;
       attributes["exception.message"] = error.message;
       attributes["exception.stacktrace"] = error.stack;
-      formattedMessage += "\n" + error.stack;
     }
 
     if (context) {
       const spanCtx = context.spanContext();
-      if (spanCtx) {
-        attributes["span.id"] = spanCtx.spanId;
-        attributes["trace.id"] = spanCtx.traceId;
-      }
+      attributes["span.id"] = spanCtx.spanId;
+      attributes["trace.id"] = spanCtx.traceId;
     }
 
-    console.log(`[${level}] [${this.module}] ${formattedMessage}`);
-    if (!this.standardLogger?.getLogger()) {
+    console.log(`[${level}] [${this.module}] ${message}`);
+    const logger = this.standardLogger.getLogger();
+    if (!logger) {
       return;
     }
-    this.standardLogger.getLogger()?.emit({
+    logger.emit({
       severityNumber,
       severityText: level,
-      body: `[${this.module}] ${formattedMessage}`,
+      body: `[${this.module}] ${message}`,
       attributes,
     });
   }

package/src/StandardLogger.spec.ts

@@ -0,0 +1,128 @@
+import { logs, SeverityNumber } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { LoggerProvider } from "@opentelemetry/sdk-logs";
+import { StandardLogger } from "./StandardLogger";
+
+jest.mock("@opentelemetry/exporter-logs-otlp-http", () => {
+  const { ExportResultCode } = jest.requireActual<
+    typeof import("@opentelemetry/core")
+  >("@opentelemetry/core");
+  return {
+    OTLPLogExporter: jest.fn().mockImplementation(function () {
+      const exportedRecords: { body?: unknown }[] = [];
+      return {
+        export: (
+          records: { body?: unknown }[],
+          resultCallback: (result: { code: number }) => void,
+        ) => {
+          exportedRecords.push(...records);
+          resultCallback({ code: ExportResultCode.SUCCESS });
+        },
+        forceFlush: jest.fn().mockResolvedValue(undefined),
+        shutdown: jest.fn().mockResolvedValue(undefined),
+        getExportedRecords: () => exportedRecords,
+      };
+    }),
+  };
+});
+
+interface MockLogExporter {
+  forceFlush: jest.Mock;
+  shutdown: jest.Mock;
+  getExportedRecords: () => { body?: unknown }[];
+}
+
+const mockExporterConstructor = OTLPLogExporter as unknown as jest.Mock;
+
+function lastExporter(): MockLogExporter {
+  const results = mockExporterConstructor.mock.results;
+  return results[results.length - 1].value as MockLogExporter;
+}
+
+function collectorConfig(logsUrl: string) {
+  return {
+    SERVICE_ID: "log-service",
+    VERSION: "1.0.0",
+    OPENTELEMETRY_COLLECTOR_HTTP_LOGS: logsUrl,
+  };
+}
+
+describe("StandardLogger", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    logs.disable();
+  });
+
+  afterEach(() => {
+    logs.disable();
+  });
+
+  it("builds the log exporter with the collector URL and no auth header", async () => {
+    const logger = new StandardLogger();
+    logger.initOTel(collectorConfig("http://collector:4318/v1/logs"));
+
+    expect(mockExporterConstructor).toHaveBeenCalledTimes(1);
+    expect(mockExporterConstructor.mock.calls[0][0]).toEqual({
+      url: "http://collector:4318/v1/logs",
+      headers: {},
+    });
+    await logger.shutdown();
+  });
+
+  it("adds the Authorization header when configured", async () => {
+    const logger = new StandardLogger();
+    logger.initOTel({
+      ...collectorConfig("http://collector:4318/v1/logs"),
+      OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: "secret",
+    });
+
+    expect(mockExporterConstructor.mock.calls[0][0]).toEqual({
+      url: "http://collector:4318/v1/logs",
+      headers: { Authorization: "Bearer secret" },
+    });
+    await logger.shutdown();
+  });
+
+  it("registers the provider as the global logger provider", async () => {
+    const logger = new StandardLogger();
+    logger.initOTel(collectorConfig("http://collector:4318/v1/logs"));
+
+    expect(logs.getLoggerProvider()).toBeInstanceOf(LoggerProvider);
+    await logger.shutdown();
+  });
+
+  it("flushes api-logs and module logger records on shutdown", async () => {
+    const logger = new StandardLogger();
+    logger.initOTel({
+      ...collectorConfig("http://collector:4318/v1/logs"),
+      OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: 5,
+    });
+
+    logs.getLogger("external-lib").emit({
+      body: "from-global",
+      severityNumber: SeverityNumber.INFO,
+    });
+    logger.createModuleLogger("billing").info("hello");
+    expect(logger.getLogger()).toBeDefined();
+
+    await logger.shutdown();
+
+    const bodies = lastExporter()
+      .getExportedRecords()
+      .map((record) => record.body);
+    expect(bodies).toEqual(
+      expect.arrayContaining(["from-global", "[billing] hello"]),
+    );
+    expect(lastExporter().shutdown).toHaveBeenCalled();
+  });
+
+  it("does not register a global provider without a logs endpoint", async () => {
+    const logger = new StandardLogger();
+    logger.initOTel({ SERVICE_ID: "log-service", VERSION: "1.0.0" });
+
+    expect(logger.getLogger()).toBeUndefined();
+    expect(mockExporterConstructor).not.toHaveBeenCalled();
+    expect(logs.getLoggerProvider()).not.toBeInstanceOf(LoggerProvider);
+    await expect(logger.shutdown()).resolves.toBeUndefined();
+  });
+});

package/src/StandardLogger.ts

@@ -1,4 +1,4 @@
-import type { Logger as OTelLogger } from "@opentelemetry/api-logs";
+import { logs, type Logger as OTelLogger } from "@opentelemetry/api-logs";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 import {
   BatchLogRecordProcessor,
@@ -12,6 +12,7 @@ import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
 
 export class StandardLogger implements StandardLoggerInterface {
   private logger?: OTelLogger;
+  private loggerProvider?: LoggerProvider;
   private serviceVersion?: string;
   private serviceName?: string;
 
@@ -30,7 +31,7 @@ export class StandardLogger implements StandardLoggerInterface {
         headers: exporterHeaders,
       });
 
-      const loggerProvider = new LoggerProvider({
+      this.loggerProvider = new LoggerProvider({
         processors: [
           new BatchLogRecordProcessor({
             exporter,
@@ -43,12 +44,17 @@ export class StandardLogger implements StandardLoggerInterface {
         resource: createOTelResource(this.serviceName, this.serviceVersion),
       });
 
-      this.logger = loggerProvider.getLogger(
+      logs.setGlobalLoggerProvider(this.loggerProvider);
+      this.logger = this.loggerProvider.getLogger(
         `${this.serviceName}:${this.serviceVersion}`,
       );
     }
   }
 
+  public async shutdown(): Promise<void> {
+    await this.loggerProvider?.shutdown();
+  }
+
   public getLogger(): OTelLogger | undefined {
     return this.logger;
   }

package/src/StandardMeter.spec.ts

@@ -0,0 +1,114 @@
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import type { InMemoryMetricExporter } from "@opentelemetry/sdk-metrics";
+import { StandardMeter } from "./StandardMeter";
+
+jest.mock("@opentelemetry/exporter-metrics-otlp-http", () => {
+  const {
+    AggregationTemporality,
+    InMemoryMetricExporter,
+  } = jest.requireActual<typeof import("@opentelemetry/sdk-metrics")>(
+    "@opentelemetry/sdk-metrics",
+  );
+  return {
+    OTLPMetricExporter: jest.fn().mockImplementation(function () {
+      return new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+    }),
+  };
+});
+
+const mockExporterConstructor = OTLPMetricExporter as unknown as jest.Mock;
+
+function lastExporter(): InMemoryMetricExporter {
+  const results = mockExporterConstructor.mock.results;
+  return results[results.length - 1].value as InMemoryMetricExporter;
+}
+
+function metricNames(exporter: InMemoryMetricExporter): string[] {
+  return exporter
+    .getMetrics()
+    .flatMap((resourceMetrics) => resourceMetrics.scopeMetrics)
+    .flatMap((scopeMetrics) => scopeMetrics.metrics)
+    .map((metric) => metric.descriptor.name);
+}
+
+describe("StandardMeter", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("builds the metric exporter with URL and concurrency limit and honors the export interval", async () => {
+    const meter = new StandardMeter({
+      SERVICE_ID: "metric-service",
+      VERSION: "1.0.0",
+      OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "http://collector:4318/v1/metrics",
+      OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: 5,
+    });
+
+    expect(mockExporterConstructor).toHaveBeenCalledWith({
+      url: "http://collector:4318/v1/metrics",
+      headers: {},
+      concurrencyLimit: 5,
+    });
+    await meter.shutdown();
+  });
+
+  it("adds the Authorization header when configured", async () => {
+    const meter = new StandardMeter({
+      SERVICE_ID: "metric-service",
+      VERSION: "1.0.0",
+      OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "http://collector:4318/v1/metrics",
+      OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: "secret",
+    });
+
+    expect(mockExporterConstructor).toHaveBeenCalledWith({
+      url: "http://collector:4318/v1/metrics",
+      headers: { Authorization: "Bearer secret" },
+      concurrencyLimit: 5,
+    });
+    await meter.shutdown();
+  });
+
+  it("creates the four metric types and flushes them on shutdown", async () => {
+    const meter = new StandardMeter({
+      SERVICE_ID: "metric-service",
+      VERSION: "1.0.0",
+      OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "http://collector:4318/v1/metrics",
+    });
+
+    meter.createCounter("requests.total").add(1);
+    meter.createUpDownCounter("users.active").add(1);
+    meter.createHistogram("requests.latency").record(42);
+    const gauge = meter.createObservableGauge(
+      "cpu.usage",
+      (observableResult) => observableResult.observe(0.5),
+      "Current CPU usage",
+    );
+    expect(gauge).toBeDefined();
+
+    await meter.shutdown();
+
+    expect(metricNames(lastExporter())).toEqual(
+      expect.arrayContaining([
+        "metric-service.requests.total",
+        "metric-service.users.active",
+        "metric-service.requests.latency",
+        "cpu.usage",
+      ]),
+    );
+  });
+
+  it("works without a collector and without a gauge description", async () => {
+    const meter = new StandardMeter({
+      SERVICE_ID: "metric-service",
+      VERSION: "1.0.0",
+    });
+
+    expect(mockExporterConstructor).not.toHaveBeenCalled();
+    meter.createCounter("requests.total").add(1);
+    const gauge = meter.createObservableGauge("cpu.usage", (observableResult) =>
+      observableResult.observe(0.5),
+    );
+    expect(gauge).toBeDefined();
+    await expect(meter.shutdown()).resolves.toBeUndefined();
+  });
+});

package/src/StandardMeter.ts

@@ -15,13 +15,13 @@ import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 
 export class StandardMeter {
   private meter: Meter;
+  private meterProvider: MeterProvider;
   private serviceVersion: string;
   private serviceName: string;
 
   constructor(config: ConfigOTelInterface) {
     this.serviceName = config.SERVICE_ID;
     this.serviceVersion = config.VERSION;
-    let meterProvider;
     if (config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS) {
       const collectorOptions = {
         url: config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS,
@@ -33,7 +33,7 @@ export class StandardMeter {
           `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
       }
       const metricExporter = new OTLPMetricExporter(collectorOptions);
-      meterProvider = new MeterProvider({
+      this.meterProvider = new MeterProvider({
         resource: createOTelResource(this.serviceName, this.serviceVersion),
         readers: [
           new PeriodicExportingMetricReader({
@@ -45,15 +45,19 @@ export class StandardMeter {
         ],
       });
     } else {
-      meterProvider = new MeterProvider({
+      this.meterProvider = new MeterProvider({
         resource: createOTelResource(this.serviceName, this.serviceVersion),
       });
     }
-    this.meter = meterProvider.getMeter(
+    this.meter = this.meterProvider.getMeter(
       `${this.serviceName}:${this.serviceVersion}`,
     );
   }
 
+  public async shutdown(): Promise<void> {
+    await this.meterProvider.shutdown();
+  }
+
   public createCounter(key: string): Counter {
     return this.meter.createCounter(`${this.serviceName}.${key}`);
   }

package/src/StandardTracer.spec.ts

@@ -1,10 +1,42 @@
 import { SpanKind } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import {
   ATTR_HTTP_REQUEST_METHOD,
   ATTR_HTTP_ROUTE,
 } from "@opentelemetry/semantic-conventions";
 import { StandardTracer } from "./StandardTracer";
 
+jest.mock("@opentelemetry/exporter-trace-otlp-http", () => {
+  const { ExportResultCode } = jest.requireActual<
+    typeof import("@opentelemetry/core")
+  >("@opentelemetry/core");
+  return {
+    OTLPTraceExporter: jest.fn().mockImplementation(function () {
+      return {
+        export: (
+          _spans: unknown,
+          resultCallback: (result: { code: number }) => void,
+        ) => resultCallback({ code: ExportResultCode.SUCCESS }),
+        forceFlush: jest.fn().mockResolvedValue(undefined),
+        shutdown: jest.fn().mockResolvedValue(undefined),
+      };
+    }),
+  };
+});
+
+interface MockTraceExporter {
+  export: jest.Mock;
+  forceFlush: jest.Mock;
+  shutdown: jest.Mock;
+}
+
+const mockExporterConstructor = OTLPTraceExporter as unknown as jest.Mock;
+
+function lastExporter(): MockTraceExporter {
+  const results = mockExporterConstructor.mock.results;
+  return results[results.length - 1].value as MockTraceExporter;
+}
+
 describe("StandardTracer", () => {
   let tracer: StandardTracer;
 
@@ -15,6 +47,10 @@ describe("StandardTracer", () => {
     });
   });
 
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
   describe("startSpan", () => {
     it("sanitizes span names", () => {
       const span = tracer.startSpan("GET-/api/files/:id");
@@ -65,4 +101,68 @@ describe("StandardTracer", () => {
       parent.end();
     });
   });
+
+  describe("updateHttpHeader", () => {
+    it("injects the W3C trace context into a new headers object", () => {
+      const span = tracer.startSpan("propagated");
+      const headers = StandardTracer.updateHttpHeader(span);
+
+      expect(headers.traceparent).toMatch(/^00-/);
+      expect(headers.traceparent).toContain(span.spanContext().traceId);
+      span.end();
+    });
+
+    it("injects into and returns the provided headers object", () => {
+      const span = tracer.startSpan("propagated");
+      const headers: Record<string, string> = { "x-custom": "value" };
+      const result = StandardTracer.updateHttpHeader(span, headers);
+
+      expect(result).toBe(headers);
+      expect(headers["x-custom"]).toBe("value");
+      expect(headers["traceparent"]).toContain(span.spanContext().traceId);
+      span.end();
+    });
+  });
+
+  describe("shutdown", () => {
+    it("builds the trace exporter with URL and auth header and shuts it down", async () => {
+      const exportTracer = new StandardTracer({
+        SERVICE_ID: "export-service",
+        VERSION: "2.0.0",
+        OPENTELEMETRY_COLLECTOR_HTTP_TRACES: "http://collector:4318/v1/traces",
+        OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: "secret",
+      });
+
+      expect(mockExporterConstructor).toHaveBeenCalledWith({
+        url: "http://collector:4318/v1/traces",
+        headers: { Authorization: "Bearer secret" },
+      });
+
+      await exportTracer.shutdown();
+      expect(lastExporter().shutdown).toHaveBeenCalled();
+    });
+
+    it("builds the trace exporter without auth header", async () => {
+      const exportTracer = new StandardTracer({
+        SERVICE_ID: "export-service",
+        VERSION: "2.0.0",
+        OPENTELEMETRY_COLLECTOR_HTTP_TRACES: "http://collector:4318/v1/traces",
+      });
+
+      expect(mockExporterConstructor).toHaveBeenCalledWith({
+        url: "http://collector:4318/v1/traces",
+        headers: {},
+      });
+      await exportTracer.shutdown();
+    });
+
+    it("resolves without a collector", async () => {
+      const plainTracer = new StandardTracer({
+        SERVICE_ID: "plain-service",
+        VERSION: "1.0.0",
+      });
+
+      await expect(plainTracer.shutdown()).resolves.toBeUndefined();
+    });
+  });
 });

package/src/StandardTracer.ts

@@ -5,6 +5,7 @@ import opentelemetry, {
   trace,
   Tracer,
 } from "@opentelemetry/api";
+import type { Span as ApiSpan } from "@opentelemetry/api";
 import { AsyncHooksContextManager } from "@opentelemetry/context-async-hooks";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
@@ -36,6 +37,7 @@ export class StandardTracer {
   private static readonly SPAN_NAME_SANITIZE_RE = /[^a-zA-Z0-9-_/]/g;
   private static readonly PROPAGATOR = new W3CTraceContextPropagator();
 
+  private traceProvider: NodeTracerProvider;
   private tracer: Tracer;
   private serviceVersion: string;
   private serviceName: string;
@@ -57,12 +59,12 @@ export class StandardTracer {
       });
       spanProcessors.push(new BatchSpanProcessor(exporter));
     }
-    const traceProvider = new NodeTracerProvider({
+    this.traceProvider = new NodeTracerProvider({
       idGenerator: new AWSXRayIdGenerator(),
       resource: createOTelResource(this.serviceName, this.serviceVersion),
       spanProcessors,
     });
-    traceProvider.register();
+    this.traceProvider.register();
     const contextManager = new AsyncHooksContextManager();
     contextManager.enable();
     opentelemetry.context.setGlobalContextManager(contextManager);
@@ -71,12 +73,16 @@ export class StandardTracer {
     );
   }
 
+  public async shutdown(): Promise<void> {
+    await this.traceProvider.shutdown();
+  }
+
   public startSpan(
     name: string,
     parentSpan?: Span,
     options?: StandardTracerStartSpanOptions,
   ): Span {
-    const sanitizedName = String(name).replace(
+    const sanitizedName = name.replace(
       StandardTracer.SPAN_NAME_SANITIZE_RE,
       "_",
     );
@@ -100,10 +106,7 @@ export class StandardTracer {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  public static updateHttpHeader(context: Span, headers = {}): any {
-    if (!headers) {
-      headers = {};
-    }
+  public static updateHttpHeader(context: ApiSpan, headers = {}): any {
     StandardTracer.PROPAGATOR.inject(
       trace.setSpanContext(ROOT_CONTEXT, context.spanContext()),
       // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/models/ConfigOTelInterface.ts

@@ -6,6 +6,5 @@ export interface ConfigOTelInterface {
   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;
 }