@devopsplaybook.io/otel-utils 1.5.3 → 1.6.0

package/src/ShutdownHooks.spec.ts

@@ -0,0 +1,75 @@
+import { registerShutdownHooks, shutdownAll } from "./ShutdownHooks";
+
+describe("shutdownAll", () => {
+  it("shuts down every provider", async () => {
+    const first = { shutdown: jest.fn().mockResolvedValue(undefined) };
+    const second = { shutdown: jest.fn().mockResolvedValue(undefined) };
+
+    await shutdownAll([first, second]);
+
+    expect(first.shutdown).toHaveBeenCalledTimes(1);
+    expect(second.shutdown).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves when a provider fails and reports it", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const failure = new Error("boom");
+    const failing = { shutdown: jest.fn().mockRejectedValue(failure) };
+    const healthy = { shutdown: jest.fn().mockResolvedValue(undefined) };
+
+    await expect(shutdownAll([failing, healthy])).resolves.toBeUndefined();
+
+    expect(healthy.shutdown).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[otel-utils] shutdown failed",
+      failure,
+    );
+    warnSpy.mockRestore();
+  });
+});
+
+describe("registerShutdownHooks", () => {
+  it("flushes the providers and exits once on SIGTERM/SIGINT", async () => {
+    const exitSpy = jest
+      .spyOn(process, "exit")
+      .mockImplementation((() => undefined) as never);
+    const provider = { shutdown: jest.fn().mockResolvedValue(undefined) };
+    const sigtermListeners = process.listenerCount("SIGTERM");
+    const sigintListeners = process.listenerCount("SIGINT");
+
+    const cleanup = registerShutdownHooks([provider]);
+    try {
+      expect(process.listenerCount("SIGTERM")).toBe(sigtermListeners + 1);
+      expect(process.listenerCount("SIGINT")).toBe(sigintListeners + 1);
+
+      process.emit("SIGTERM");
+      await new Promise((resolve) => setImmediate(resolve));
+      expect(provider.shutdown).toHaveBeenCalledTimes(1);
+      expect(exitSpy).toHaveBeenCalledWith(0);
+
+      process.emit("SIGINT");
+      await new Promise((resolve) => setImmediate(resolve));
+      expect(provider.shutdown).toHaveBeenCalledTimes(1);
+      expect(exitSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      cleanup();
+      exitSpy.mockRestore();
+    }
+
+    expect(process.listenerCount("SIGTERM")).toBe(sigtermListeners);
+    expect(process.listenerCount("SIGINT")).toBe(sigintListeners);
+  });
+
+  it("the cleanup function removes both listeners without shutting down", () => {
+    const provider = { shutdown: jest.fn().mockResolvedValue(undefined) };
+    const sigtermListeners = process.listenerCount("SIGTERM");
+    const sigintListeners = process.listenerCount("SIGINT");
+
+    const cleanup = registerShutdownHooks([provider]);
+    cleanup();
+
+    expect(process.listenerCount("SIGTERM")).toBe(sigtermListeners);
+    expect(process.listenerCount("SIGINT")).toBe(sigintListeners);
+    expect(provider.shutdown).not.toHaveBeenCalled();
+  });
+});

package/src/ShutdownHooks.ts

@@ -0,0 +1,45 @@
+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 async function shutdownAll(
+  providers: ReadonlyArray<ShutdownableInterface>,
+): Promise<void> {
+  await Promise.all(
+    providers.map((provider) =>
+      provider.shutdown().catch((error: unknown) => {
+        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.
+ */
+export function registerShutdownHooks(
+  providers: ReadonlyArray<ShutdownableInterface>,
+): () => void {
+  let shuttingDown = false;
+  const onSignal = (): void => {
+    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/src/StandardLogger.spec.ts

@@ -1,6 +1,7 @@
 import { logs, SeverityNumber } from "@opentelemetry/api";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
+import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { StandardLogger } from "./StandardLogger";
 
 jest.mock("@opentelemetry/exporter-logs-otlp-http", () => {
@@ -34,12 +35,19 @@ interface MockLogExporter {
 
 const mockExporterConstructor = OTLPLogExporter as unknown as jest.Mock;
 
+function exporterAt(index: number): MockLogExporter {
+  return mockExporterConstructor.mock.results[index].value as MockLogExporter;
+}
+
 function lastExporter(): MockLogExporter {
-  const results = mockExporterConstructor.mock.results;
-  return results[results.length - 1].value as MockLogExporter;
+  return exporterAt(mockExporterConstructor.mock.results.length - 1);
+}
+
+function exportedBodies(exporter: MockLogExporter): unknown[] {
+  return exporter.getExportedRecords().map((record) => record.body);
 }
 
-function collectorConfig(logsUrl: string) {
+function collectorConfig(logsUrl: string): ConfigOTelInterface {
   return {
     SERVICE_ID: "log-service",
     VERSION: "1.0.0",
@@ -48,18 +56,35 @@ function collectorConfig(logsUrl: string) {
 }
 
 describe("StandardLogger", () => {
+  const createdLoggers: StandardLogger[] = [];
+  let warnSpy: jest.SpyInstance;
+  let logSpy: jest.SpyInstance;
+
+  function makeLogger(): StandardLogger {
+    const logger = new StandardLogger();
+    createdLoggers.push(logger);
+    return logger;
+  }
+
   beforeEach(() => {
     jest.clearAllMocks();
     logs.disable();
+    warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
   });
 
-  afterEach(() => {
+  afterEach(async () => {
+    for (const logger of createdLoggers.splice(0)) {
+      await logger.shutdown();
+    }
     logs.disable();
+    warnSpy.mockRestore();
+    logSpy.mockRestore();
   });
 
   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"));
+    const logger = makeLogger();
+    await logger.initOTel(collectorConfig("http://collector:4318/v1/logs"));
 
     expect(mockExporterConstructor).toHaveBeenCalledTimes(1);
     expect(mockExporterConstructor.mock.calls[0][0]).toEqual({
@@ -70,8 +95,8 @@ describe("StandardLogger", () => {
   });
 
   it("adds the Authorization header when configured", async () => {
-    const logger = new StandardLogger();
-    logger.initOTel({
+    const logger = makeLogger();
+    await logger.initOTel({
       ...collectorConfig("http://collector:4318/v1/logs"),
       OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: "secret",
     });
@@ -84,16 +109,16 @@ describe("StandardLogger", () => {
   });
 
   it("registers the provider as the global logger provider", async () => {
-    const logger = new StandardLogger();
-    logger.initOTel(collectorConfig("http://collector:4318/v1/logs"));
+    const logger = makeLogger();
+    await logger.initOTel(collectorConfig("http://collector:4318/v1/logs"));
 
     expect(logs.getLoggerProvider()).toBeInstanceOf(LoggerProvider);
     await logger.shutdown();
   });
 
   it("flushes OTel logs and module logger records on shutdown", async () => {
-    const logger = new StandardLogger();
-    logger.initOTel({
+    const logger = makeLogger();
+    await logger.initOTel({
       ...collectorConfig("http://collector:4318/v1/logs"),
       OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: 5,
     });
@@ -107,22 +132,105 @@ describe("StandardLogger", () => {
 
     await logger.shutdown();
 
-    const bodies = lastExporter()
-      .getExportedRecords()
-      .map((record) => record.body);
-    expect(bodies).toEqual(
+    expect(exportedBodies(lastExporter())).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" });
+    const logger = makeLogger();
+    await 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();
   });
+
+  it("routes each instance to its own exporter and warns on the second registration", async () => {
+    const first = makeLogger();
+    const second = makeLogger();
+    await first.initOTel(collectorConfig("http://collector-1/v1/logs"));
+    await second.initOTel(collectorConfig("http://collector-2/v1/logs"));
+
+    first.createModuleLogger("first").info("from-first");
+    second.createModuleLogger("second").info("from-second");
+    logs.getLogger("external-lib").emit({
+      body: "from-global",
+      severityNumber: SeverityNumber.INFO,
+    });
+
+    await first.shutdown();
+    await second.shutdown();
+
+    expect(exportedBodies(exporterAt(0))).toEqual(
+      expect.arrayContaining(["[first] from-first", "from-global"]),
+    );
+    expect(exportedBodies(exporterAt(1))).toEqual(["[second] from-second"]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("A global logger provider is already registered"),
+    );
+  });
+
+  it("re-initialisation flushes the previous provider and keeps records", async () => {
+    const logger = makeLogger();
+    await logger.initOTel(collectorConfig("http://collector-1/v1/logs"));
+    logger.createModuleLogger("billing").info("before-reinit");
+
+    await logger.initOTel(collectorConfig("http://collector-2/v1/logs"));
+
+    expect(exportedBodies(exporterAt(0))).toContain("[billing] before-reinit");
+    expect(logs.getLoggerProvider()).toBeInstanceOf(LoggerProvider);
+
+    logs.getLogger("external-lib").emit({
+      body: "after-reinit",
+      severityNumber: SeverityNumber.INFO,
+    });
+    logger.createModuleLogger("billing").info("after-reinit-module");
+    await logger.shutdown();
+
+    expect(exportedBodies(exporterAt(1))).toEqual(
+      expect.arrayContaining(["after-reinit", "[billing] after-reinit-module"]),
+    );
+  });
+
+  it("can re-initialise after shutdown", async () => {
+    const logger = makeLogger();
+    await logger.initOTel(collectorConfig("http://collector/v1/logs"));
+    await logger.shutdown();
+
+    expect(logger.getLogger()).toBeUndefined();
+    expect(logs.getLoggerProvider()).not.toBeInstanceOf(LoggerProvider);
+
+    await logger.initOTel(collectorConfig("http://collector/v1/logs"));
+    expect(logger.getLogger()).toBeDefined();
+    expect(logs.getLoggerProvider()).toBeInstanceOf(LoggerProvider);
+
+    logs.getLogger("external-lib").emit({
+      body: "after-restart",
+      severityNumber: SeverityNumber.INFO,
+    });
+    await logger.shutdown();
+
+    expect(exportedBodies(exporterAt(1))).toContain("after-restart");
+  });
+
+  it("shuts down idempotently and leaves the global API on Noop", async () => {
+    const logger = makeLogger();
+    await logger.initOTel(collectorConfig("http://collector/v1/logs"));
+    logger.createModuleLogger("billing").info("recorded");
+
+    await logger.shutdown();
+    await logger.shutdown();
+
+    expect(exporterAt(0).shutdown).toHaveBeenCalledTimes(1);
+    expect(exportedBodies(exporterAt(0))).toContain("[billing] recorded");
+    expect(logger.getLogger()).toBeUndefined();
+    expect(logs.getLoggerProvider()).not.toBeInstanceOf(LoggerProvider);
+    expect(() =>
+      logs.getLogger("external-lib").emit({ body: "dropped" }),
+    ).not.toThrow();
+  });
 });

package/src/StandardLogger.ts

@@ -10,49 +10,66 @@ import { ModuleLogger } from "./ModuleLogger";
 
 import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
 
+let globalLoggerProvider: LoggerProvider | undefined;
+
+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.";
+
 export class StandardLogger implements StandardLoggerInterface {
   private logger?: OTelLogger;
   private loggerProvider?: LoggerProvider;
   private serviceVersion?: string;
   private serviceName?: string;
+  private ownsGlobalProvider = false;
+  private shutdownPromise?: Promise<void>;
 
-  public initOTel(config: ConfigOTelInterface) {
+  public async initOTel(config: ConfigOTelInterface): Promise<void> {
+    // 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: Record<string, string> = {};
-      if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-        exporterHeaders["Authorization"] =
-          `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
-      }
-      const exporter = new OTLPLogExporter({
-        url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
-        headers: exporterHeaders,
-      });
-
-      this.loggerProvider = new LoggerProvider({
-        processors: [
-          new BatchLogRecordProcessor({
-            exporter,
-            maxQueueSize: 2048,
-            scheduledDelayMillis:
-              (config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS ??
-                60) * 1000,
-          }),
-        ],
-        resource: createOTelResource(this.serviceName, this.serviceVersion),
-      });
+    if (!config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS) {
+      return;
+    }
 
-      logs.setGlobalLoggerProvider(this.loggerProvider);
-      this.logger = this.loggerProvider.getLogger(
-        `${this.serviceName}:${this.serviceVersion}`,
-      );
+    const exporterHeaders: Record<string, string> = {};
+    if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
+      exporterHeaders["Authorization"] =
+        `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
     }
+    const exporter = new OTLPLogExporter({
+      url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
+      headers: exporterHeaders,
+    });
+
+    this.loggerProvider = new LoggerProvider({
+      processors: [
+        new BatchLogRecordProcessor({
+          exporter,
+          maxQueueSize: 2048,
+          scheduledDelayMillis:
+            (config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS ??
+              60) * 1000,
+        }),
+      ],
+      resource: createOTelResource(this.serviceName, this.serviceVersion),
+    });
+
+    this.logger = this.loggerProvider.getLogger(
+      `${this.serviceName}:${this.serviceVersion}`,
+    );
+    this.registerGlobalProvider();
   }
 
-  public async shutdown(): Promise<void> {
-    await this.loggerProvider?.shutdown();
+  public shutdown(): Promise<void> {
+    if (!this.shutdownPromise) {
+      this.shutdownPromise = this.releaseProvider();
+    }
+    return this.shutdownPromise;
   }
 
   public getLogger(): OTelLogger | undefined {
@@ -62,4 +79,42 @@ export class StandardLogger implements StandardLoggerInterface {
   public createModuleLogger(moduleName: string): ModuleLogger {
     return new ModuleLogger(moduleName, this);
   }
+
+  private registerGlobalProvider(): void {
+    if (globalLoggerProvider) {
+      if (globalLoggerProvider === logs.getLoggerProvider()) {
+        console.warn(ALREADY_REGISTERED_WARNING);
+        return;
+      }
+      // The previous provider is no longer registered (disabled elsewhere).
+      globalLoggerProvider = undefined;
+    }
+    if (
+      this.loggerProvider &&
+      logs.setGlobalLoggerProvider(this.loggerProvider)
+    ) {
+      globalLoggerProvider = this.loggerProvider;
+      this.ownsGlobalProvider = true;
+    } else {
+      console.warn(ALREADY_REGISTERED_WARNING);
+    }
+  }
+
+  private async releaseProvider(): Promise<void> {
+    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 && logs.getLoggerProvider() === provider) {
+      logs.disable();
+    }
+    if (globalLoggerProvider === provider) {
+      globalLoggerProvider = undefined;
+    }
+  }
 }

package/src/StandardMeter.spec.ts

@@ -1,5 +1,10 @@
+import { metrics } from "@opentelemetry/api";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import type { InMemoryMetricExporter } from "@opentelemetry/sdk-metrics";
+import {
+  type InMemoryMetricExporter,
+  MeterProvider,
+} from "@opentelemetry/sdk-metrics";
+import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { StandardMeter } from "./StandardMeter";
 
 jest.mock("@opentelemetry/exporter-metrics-otlp-http", () => {
@@ -18,9 +23,13 @@ jest.mock("@opentelemetry/exporter-metrics-otlp-http", () => {
 
 const mockExporterConstructor = OTLPMetricExporter as unknown as jest.Mock;
 
+function exporterAt(index: number): InMemoryMetricExporter {
+  return mockExporterConstructor.mock.results[index]
+    .value as InMemoryMetricExporter;
+}
+
 function lastExporter(): InMemoryMetricExporter {
-  const results = mockExporterConstructor.mock.results;
-  return results[results.length - 1].value as InMemoryMetricExporter;
+  return exporterAt(mockExporterConstructor.mock.results.length - 1);
 }
 
 function metricNames(exporter: InMemoryMetricExporter): string[] {
@@ -31,13 +40,43 @@ function metricNames(exporter: InMemoryMetricExporter): string[] {
     .map((metric) => metric.descriptor.name);
 }
 
+function meterConfig(
+  serviceId: string,
+  url?: string,
+): ConfigOTelInterface {
+  return {
+    SERVICE_ID: serviceId,
+    VERSION: "1.0.0",
+    OPENTELEMETRY_COLLECTOR_HTTP_METRICS: url,
+  };
+}
+
 describe("StandardMeter", () => {
+  const createdMeters: StandardMeter[] = [];
+  let warnSpy: jest.SpyInstance;
+
+  function makeMeter(config: ConfigOTelInterface): StandardMeter {
+    const meter = new StandardMeter(config);
+    createdMeters.push(meter);
+    return meter;
+  }
+
   beforeEach(() => {
     jest.clearAllMocks();
+    metrics.disable();
+    warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    for (const meter of createdMeters.splice(0)) {
+      await meter.shutdown();
+    }
+    metrics.disable();
+    warnSpy.mockRestore();
   });
 
   it("builds the metric exporter with URL and concurrency limit and honors the export interval", async () => {
-    const meter = new StandardMeter({
+    const meter = makeMeter({
       SERVICE_ID: "metric-service",
       VERSION: "1.0.0",
       OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "http://collector:4318/v1/metrics",
@@ -53,7 +92,7 @@ describe("StandardMeter", () => {
   });
 
   it("adds the Authorization header when configured", async () => {
-    const meter = new StandardMeter({
+    const meter = makeMeter({
       SERVICE_ID: "metric-service",
       VERSION: "1.0.0",
       OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "http://collector:4318/v1/metrics",
@@ -69,11 +108,9 @@ describe("StandardMeter", () => {
   });
 
   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",
-    });
+    const meter = makeMeter(
+      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
+    );
 
     meter.createCounter("requests.total").add(1);
     meter.createUpDownCounter("users.active").add(1);
@@ -98,11 +135,9 @@ describe("StandardMeter", () => {
   });
 
   it("creates a histogram without the service-name prefix when the unprefixed option is set", async () => {
-    const meter = new StandardMeter({
-      SERVICE_ID: "metric-service",
-      VERSION: "1.0.0",
-      OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "http://collector:4318/v1/metrics",
-    });
+    const meter = makeMeter(
+      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
+    );
 
     meter.createHistogram("session.duration", { unprefixed: true }).record(1);
     meter.createHistogram("requests.latency").record(42);
@@ -115,13 +150,13 @@ describe("StandardMeter", () => {
     expect(names).not.toContain("metric-service.session.duration");
   });
 
-  it("works without a collector and without a gauge description", async () => {
-    const meter = new StandardMeter({
-      SERVICE_ID: "metric-service",
-      VERSION: "1.0.0",
-    });
+  it("works without a collector, leaves the global API untouched and without a gauge description", async () => {
+    const meter = makeMeter(meterConfig("metric-service"));
 
     expect(mockExporterConstructor).not.toHaveBeenCalled();
+    expect(metrics.getMeterProvider()).not.toBeInstanceOf(MeterProvider);
+    expect(warnSpy).not.toHaveBeenCalled();
+
     meter.createCounter("requests.total").add(1);
     const gauge = meter.createObservableGauge("cpu.usage", (observableResult) =>
       observableResult.observe(0.5),
@@ -129,4 +164,65 @@ describe("StandardMeter", () => {
     expect(gauge).toBeDefined();
     await expect(meter.shutdown()).resolves.toBeUndefined();
   });
+
+  it("registers a configured meter as the global provider", async () => {
+    const meter = makeMeter(
+      meterConfig("metric-service", "http://collector-1/v1/metrics"),
+    );
+
+    expect(metrics.getMeterProvider()).toBeInstanceOf(MeterProvider);
+    metrics.getMeter("global").createCounter("global.counter").add(1);
+
+    await meter.shutdown();
+
+    expect(metricNames(exporterAt(0))).toContain("global.counter");
+  });
+
+  it("keeps each instance on its own exporter and warns on the second registration", async () => {
+    const first = makeMeter(
+      meterConfig("metric-a", "http://collector-1/v1/metrics"),
+    );
+    const second = makeMeter(
+      meterConfig("metric-b", "http://collector-2/v1/metrics"),
+    );
+
+    first.createCounter("a.total").add(1);
+    second.createCounter("b.total").add(1);
+    metrics.getMeter("global").createCounter("global.counter").add(1);
+
+    await first.shutdown();
+    await second.shutdown();
+
+    expect(metricNames(exporterAt(0))).toEqual(
+      expect.arrayContaining(["metric-a.a.total", "global.counter"]),
+    );
+    expect(metricNames(exporterAt(1))).toEqual(["metric-b.b.total"]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("A global meter provider is already registered"),
+    );
+  });
+
+  it("owner shutdown releases the global provider so a new meter can register", async () => {
+    const first = makeMeter(
+      meterConfig("metric-a", "http://collector-1/v1/metrics"),
+    );
+    expect(metrics.getMeterProvider()).toBeInstanceOf(MeterProvider);
+
+    await first.shutdown();
+    expect(metrics.getMeterProvider()).not.toBeInstanceOf(MeterProvider);
+
+    const second = makeMeter(
+      meterConfig("metric-b", "http://collector-2/v1/metrics"),
+    );
+    expect(metrics.getMeterProvider()).toBeInstanceOf(MeterProvider);
+    const shutdownSpy = jest.spyOn(exporterAt(1), "shutdown");
+
+    metrics.getMeter("global").createCounter("after-reinit").add(1);
+    await second.shutdown();
+    await second.shutdown();
+
+    expect(metricNames(exporterAt(1))).toContain("after-reinit");
+    expect(shutdownSpy).toHaveBeenCalledTimes(1);
+  });
 });