@devopsplaybook.io/otel-utils 1.5.3 → 1.6.0

package/src/StandardMeter.ts

@@ -2,6 +2,7 @@ import {
   Counter,
   Histogram,
   Meter,
+  metrics,
   ObservableGauge,
   UpDownCounter,
 } from "@opentelemetry/api";
@@ -13,6 +14,11 @@ import {
 } from "@opentelemetry/sdk-metrics";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 
+let globalMeterProvider: MeterProvider | undefined;
+
+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.";
+
 /**
  * Options accepted by {@link StandardMeter.createHistogram}.
  */
@@ -29,11 +35,15 @@ export class StandardMeter {
   private meterProvider: MeterProvider;
   private serviceVersion: string;
   private serviceName: string;
+  private ownsGlobalProvider = false;
+  private shutdownPromise?: Promise<void>;
 
   constructor(config: ConfigOTelInterface) {
     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: {} as Record<string, string>,
@@ -63,10 +73,16 @@ export class StandardMeter {
     this.meter = this.meterProvider.getMeter(
       `${this.serviceName}:${this.serviceVersion}`,
     );
+    if (hasCollector) {
+      this.registerGlobalProvider();
+    }
   }
 
-  public async shutdown(): Promise<void> {
-    await this.meterProvider.shutdown();
+  public shutdown(): Promise<void> {
+    if (!this.shutdownPromise) {
+      this.shutdownPromise = this.doShutdown();
+    }
+    return this.shutdownPromise;
   }
 
   public createCounter(key: string): Counter {
@@ -99,4 +115,35 @@ export class StandardMeter {
     observableGauge.addCallback(callback);
     return observableGauge;
   }
+
+  private registerGlobalProvider(): void {
+    if (globalMeterProvider) {
+      if (globalMeterProvider === metrics.getMeterProvider()) {
+        console.warn(ALREADY_REGISTERED_WARNING);
+        return;
+      }
+      // The previous provider is no longer registered (disabled elsewhere).
+      globalMeterProvider = undefined;
+    }
+    if (metrics.setGlobalMeterProvider(this.meterProvider)) {
+      globalMeterProvider = this.meterProvider;
+      this.ownsGlobalProvider = true;
+    } else {
+      console.warn(ALREADY_REGISTERED_WARNING);
+    }
+  }
+
+  private async doShutdown(): Promise<void> {
+    await this.meterProvider.shutdown();
+    if (
+      this.ownsGlobalProvider &&
+      metrics.getMeterProvider() === this.meterProvider
+    ) {
+      metrics.disable();
+    }
+    if (globalMeterProvider === this.meterProvider) {
+      globalMeterProvider = undefined;
+    }
+    this.ownsGlobalProvider = false;
+  }
 }

package/src/StandardTracer.spec.ts

@@ -1,9 +1,16 @@
-import { SpanKind } from "@opentelemetry/api";
+import {
+  diag,
+  DiagLogLevel,
+  SpanKind,
+  trace,
+} from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { TracerProvider } from "@opentelemetry/sdk-trace";
 import {
   ATTR_HTTP_REQUEST_METHOD,
   ATTR_HTTP_ROUTE,
 } from "@opentelemetry/semantic-conventions";
+import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { StandardTracer } from "./StandardTracer";
 
 jest.mock("@opentelemetry/exporter-trace-otlp-http", () => {
@@ -12,53 +19,104 @@ jest.mock("@opentelemetry/exporter-trace-otlp-http", () => {
   >("@opentelemetry/core");
   return {
     OTLPTraceExporter: jest.fn().mockImplementation(function () {
+      const exportedSpans: ExportedSpan[] = [];
       return {
         export: (
-          _spans: unknown,
+          spans: ExportedSpan[],
           resultCallback: (result: { code: number }) => void,
-        ) => resultCallback({ code: ExportResultCode.SUCCESS }),
+        ) => {
+          exportedSpans.push(...spans);
+          resultCallback({ code: ExportResultCode.SUCCESS });
+        },
         forceFlush: jest.fn().mockResolvedValue(undefined),
         shutdown: jest.fn().mockResolvedValue(undefined),
+        getExportedSpans: () => exportedSpans,
       };
     }),
   };
 });
 
+interface ExportedSpan {
+  name: string;
+  resource: { attributes: Record<string, unknown> };
+}
+
 interface MockTraceExporter {
   export: jest.Mock;
   forceFlush: jest.Mock;
   shutdown: jest.Mock;
+  getExportedSpans: () => ExportedSpan[];
 }
 
 const mockExporterConstructor = OTLPTraceExporter as unknown as jest.Mock;
 
+function exporterAt(index: number): MockTraceExporter {
+  return mockExporterConstructor.mock.results[index]
+    .value as MockTraceExporter;
+}
+
 function lastExporter(): MockTraceExporter {
-  const results = mockExporterConstructor.mock.results;
-  return results[results.length - 1].value as MockTraceExporter;
+  return exporterAt(mockExporterConstructor.mock.results.length - 1);
+}
+
+function registeredTracerProvider(): unknown {
+  const provider = trace.getTracerProvider() as unknown as {
+    getDelegate?: () => unknown;
+  };
+  return typeof provider.getDelegate === "function"
+    ? provider.getDelegate()
+    : provider;
+}
+
+function tracerConfig(
+  serviceId: string,
+  url?: string,
+): ConfigOTelInterface {
+  return {
+    SERVICE_ID: serviceId,
+    VERSION: "1.0.0",
+    OPENTELEMETRY_COLLECTOR_HTTP_TRACES: url,
+  };
+}
+
+function spanNames(exporter: MockTraceExporter): string[] {
+  return exporter.getExportedSpans().map((span) => span.name);
 }
 
 describe("StandardTracer", () => {
-  let tracer: StandardTracer;
+  const createdTracers: StandardTracer[] = [];
+  let warnSpy: jest.SpyInstance;
 
-  beforeAll(() => {
-    tracer = new StandardTracer({
-      SERVICE_ID: "test-service",
-      VERSION: "1.0.0",
-    });
-  });
+  function makeTracer(config: ConfigOTelInterface): StandardTracer {
+    const tracer = new StandardTracer(config);
+    createdTracers.push(tracer);
+    return tracer;
+  }
 
   beforeEach(() => {
     jest.clearAllMocks();
+    trace.disable();
+    warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    for (const tracer of createdTracers.splice(0)) {
+      await tracer.shutdown();
+    }
+    trace.disable();
+    warnSpy.mockRestore();
   });
 
   describe("startSpan", () => {
     it("sanitizes span names", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const span = tracer.startSpan("GET-/api/files/:id");
       expect(span.name).toBe("GET-/api/files/_id");
       span.end();
     });
 
     it("keeps the default parentless behavior when no options are given", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const span = tracer.startSpan("my-operation");
       expect(span.kind).toBe(SpanKind.INTERNAL);
       expect(span.attributes[ATTR_HTTP_REQUEST_METHOD]).toBe("BACKEND");
@@ -69,6 +127,7 @@ describe("StandardTracer", () => {
     });
 
     it("creates a child of the parent span without synthetic attributes", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const parent = tracer.startSpan("parent-operation");
       const child = tracer.startSpan("child-operation", parent);
       expect(child.spanContext().traceId).toBe(parent.spanContext().traceId);
@@ -80,6 +139,7 @@ describe("StandardTracer", () => {
     });
 
     it("applies the options instead of the synthetic attributes", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const span = tracer.startSpan("GET-/api/files/:id", undefined, {
         kind: SpanKind.SERVER,
       });
@@ -90,6 +150,7 @@ describe("StandardTracer", () => {
     });
 
     it("combines the options with a parent span", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const parent = tracer.startSpan("parent-operation");
       const child = tracer.startSpan("child-operation", parent, {
         kind: SpanKind.CLIENT,
@@ -104,6 +165,7 @@ describe("StandardTracer", () => {
 
   describe("updateHttpHeader", () => {
     it("injects the W3C trace context into a new headers object", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const span = tracer.startSpan("propagated");
       const headers = StandardTracer.updateHttpHeader(span);
 
@@ -113,6 +175,7 @@ describe("StandardTracer", () => {
     });
 
     it("injects into and returns the provided headers object", () => {
+      const tracer = makeTracer(tracerConfig("test-service"));
       const span = tracer.startSpan("propagated");
       const headers: Record<string, string> = { "x-custom": "value" };
       const result = StandardTracer.updateHttpHeader(span, headers);
@@ -124,9 +187,9 @@ describe("StandardTracer", () => {
     });
   });
 
-  describe("shutdown", () => {
+  describe("exporter configuration", () => {
     it("builds the trace exporter with URL and auth header and shuts it down", async () => {
-      const exportTracer = new StandardTracer({
+      const exportTracer = makeTracer({
         SERVICE_ID: "export-service",
         VERSION: "2.0.0",
         OPENTELEMETRY_COLLECTOR_HTTP_TRACES: "http://collector:4318/v1/traces",
@@ -143,7 +206,7 @@ describe("StandardTracer", () => {
     });
 
     it("builds the trace exporter without auth header", async () => {
-      const exportTracer = new StandardTracer({
+      const exportTracer = makeTracer({
         SERVICE_ID: "export-service",
         VERSION: "2.0.0",
         OPENTELEMETRY_COLLECTOR_HTTP_TRACES: "http://collector:4318/v1/traces",
@@ -157,12 +220,116 @@ describe("StandardTracer", () => {
     });
 
     it("resolves without a collector", async () => {
-      const plainTracer = new StandardTracer({
-        SERVICE_ID: "plain-service",
-        VERSION: "1.0.0",
-      });
-
+      const plainTracer = makeTracer(tracerConfig("plain-service"));
       await expect(plainTracer.shutdown()).resolves.toBeUndefined();
     });
   });
+
+  describe("provider ownership and global registration", () => {
+    it("routes each instance to its own exporter and resource", async () => {
+      const first = makeTracer(
+        tracerConfig("svc-1", "http://collector-1/v1/traces"),
+      );
+      const second = makeTracer(
+        tracerConfig("svc-2", "http://collector-2/v1/traces"),
+      );
+
+      first.startSpan("span-from-svc1").end();
+      second.startSpan("span-from-svc2").end();
+
+      await first.shutdown();
+      await second.shutdown();
+
+      const firstSpans = exporterAt(0).getExportedSpans();
+      const secondSpans = exporterAt(1).getExportedSpans();
+      expect(firstSpans.map((span) => span.name)).toEqual(["span-from-svc1"]);
+      expect(secondSpans.map((span) => span.name)).toEqual(["span-from-svc2"]);
+      expect(firstSpans[0].resource.attributes["service.name"]).toBe("svc-1");
+      expect(secondSpans[0].resource.attributes["service.name"]).toBe("svc-2");
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("A global tracer provider is already registered"),
+      );
+    });
+
+    it("routes global API spans to the first registered provider", async () => {
+      const first = makeTracer(
+        tracerConfig("svc-1", "http://collector-1/v1/traces"),
+      );
+      const second = makeTracer(
+        tracerConfig("svc-2", "http://collector-2/v1/traces"),
+      );
+
+      trace.getTracer("global").startSpan("global-span").end();
+      second.startSpan("second-span").end();
+
+      await first.shutdown();
+      await second.shutdown();
+
+      expect(spanNames(exporterAt(0))).toEqual(["global-span"]);
+      expect(spanNames(exporterAt(1))).toEqual(["second-span"]);
+    });
+
+    it("only the owner disables the global provider and re-registration works", async () => {
+      const first = makeTracer(
+        tracerConfig("svc-1", "http://collector-1/v1/traces"),
+      );
+      const second = makeTracer(
+        tracerConfig("svc-2", "http://collector-2/v1/traces"),
+      );
+
+      await second.shutdown();
+      expect(registeredTracerProvider()).toBeInstanceOf(TracerProvider);
+
+      trace.getTracer("global").startSpan("after-second-shutdown").end();
+      await first.shutdown();
+      expect(registeredTracerProvider()).not.toBeInstanceOf(TracerProvider);
+      expect(spanNames(exporterAt(0))).toContain("after-second-shutdown");
+
+      const third = makeTracer(
+        tracerConfig("svc-3", "http://collector-3/v1/traces"),
+      );
+      trace.getTracer("global").startSpan("after-reinit").end();
+      await third.shutdown();
+
+      expect(spanNames(exporterAt(2))).toEqual(["after-reinit"]);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("shuts down idempotently", async () => {
+      const tracer = makeTracer(
+        tracerConfig("svc-1", "http://collector-1/v1/traces"),
+      );
+      tracer.startSpan("only-span").end();
+
+      await tracer.shutdown();
+      await tracer.shutdown();
+
+      expect(exporterAt(0).shutdown).toHaveBeenCalledTimes(1);
+      expect(spanNames(exporterAt(0))).toEqual(["only-span"]);
+    });
+
+    it("emits no duplicate-registration diagnostics for a normal startup", async () => {
+      const errors: unknown[][] = [];
+      diag.setLogger(
+        {
+          error: (...args: unknown[]) => errors.push(args),
+          warn: () => {},
+          info: () => {},
+          debug: () => {},
+          verbose: () => {},
+        },
+        DiagLogLevel.ERROR,
+      );
+      try {
+        makeTracer(tracerConfig("svc-1", "http://collector-1/v1/traces"));
+        makeTracer(tracerConfig("svc-2", "http://collector-2/v1/traces"));
+      } finally {
+        diag.disable();
+      }
+
+      expect(errors).toEqual([]);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/StandardTracer.ts

@@ -1,4 +1,5 @@
-import opentelemetry, {
+import {
+  context,
   defaultTextMapSetter,
   ROOT_CONTEXT,
   SpanKind,
@@ -22,6 +23,21 @@ import {
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { createOTelResource } from "./utils/createResource";
 
+let globalTracerProvider: TracerProvider | undefined;
+let contextManagerInitialized = false;
+
+function getRegisteredTracerProvider(): unknown {
+  const provider = trace.getTracerProvider() as unknown as {
+    getDelegate?: () => unknown;
+  };
+  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.";
+
 /**
  * Options accepted by {@link StandardTracer.startSpan}.
  */
@@ -44,6 +60,8 @@ export class StandardTracer {
   private tracer: Tracer;
   private serviceVersion: string;
   private serviceName: string;
+  private ownsGlobalProvider = false;
+  private shutdownPromise?: Promise<void>;
 
   constructor(config: ConfigOTelInterface) {
     this.serviceName = config.SERVICE_ID;
@@ -67,19 +85,20 @@ export class StandardTracer {
       resource: 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.
-    trace.setGlobalTracerProvider(this.traceProvider);
-    const contextManager = new AsyncLocalStorageContextManager();
-    contextManager.enable();
-    opentelemetry.context.setGlobalContextManager(contextManager);
-    this.tracer = opentelemetry.trace.getTracer(
+    // 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();
   }
 
-  public async shutdown(): Promise<void> {
-    await this.traceProvider.shutdown();
+  public shutdown(): Promise<void> {
+    if (!this.shutdownPromise) {
+      this.shutdownPromise = this.doShutdown();
+    }
+    return this.shutdownPromise;
   }
 
   public startSpan(
@@ -95,7 +114,7 @@ export class StandardTracer {
       return this.tracer.startSpan(
         sanitizedName,
         options,
-        opentelemetry.trace.setSpan(opentelemetry.context.active(), parentSpan),
+        trace.setSpan(context.active(), parentSpan),
       ) as Span;
     }
     if (options) {
@@ -120,4 +139,50 @@ export class StandardTracer {
     );
     return headers;
   }
+
+  private registerGlobalProvider(): void {
+    if (globalTracerProvider) {
+      if (getRegisteredTracerProvider() === globalTracerProvider) {
+        console.warn(ALREADY_REGISTERED_WARNING);
+        return;
+      }
+      // The previous provider is no longer registered (disabled elsewhere).
+      globalTracerProvider = undefined;
+    }
+    if (trace.setGlobalTracerProvider(this.traceProvider)) {
+      globalTracerProvider = this.traceProvider;
+      this.ownsGlobalProvider = true;
+    } else {
+      console.warn(ALREADY_REGISTERED_WARNING);
+    }
+  }
+
+  private async doShutdown(): Promise<void> {
+    await this.traceProvider.shutdown();
+    if (
+      this.ownsGlobalProvider &&
+      getRegisteredTracerProvider() === this.traceProvider
+    ) {
+      trace.disable();
+    }
+    if (globalTracerProvider === this.traceProvider) {
+      globalTracerProvider = undefined;
+    }
+    this.ownsGlobalProvider = false;
+  }
+}
+
+function initializeContextManager(): void {
+  if (contextManagerInitialized) {
+    return;
+  }
+  contextManagerInitialized = true;
+  const contextManager = new AsyncLocalStorageContextManager();
+  if (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.",
+    );
+  }
 }