@devopsplaybook.io/otel-utils 1.8.0-beta.39.883f25d → 1.9.0-beta.40.3ebb823

package/src/StandardMeter.spec.ts

@@ -1,446 +0,0 @@
-import { metrics } from "@opentelemetry/api";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import {
-  DataPointType,
-  type InMemoryMetricExporter,
-  MeterProvider,
-  type MetricData,
-} from "@opentelemetry/sdk-metrics";
-import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
-import { StandardMeter } from "./StandardMeter";
-
-jest.mock("@opentelemetry/sdk-metrics", () => {
-  const actual =
-    jest.requireActual<typeof import("@opentelemetry/sdk-metrics")>(
-      "@opentelemetry/sdk-metrics",
-    );
-  const metricReaderOptions: unknown[] = [];
-  class RecordingPeriodicExportingMetricReader extends actual.PeriodicExportingMetricReader {
-    constructor(
-      options: ConstructorParameters<
-        typeof actual.PeriodicExportingMetricReader
-      >[0],
-    ) {
-      super(options);
-      metricReaderOptions.push(options);
-    }
-  }
-  return {
-    ...actual,
-    PeriodicExportingMetricReader: RecordingPeriodicExportingMetricReader,
-    __metricReaderOptions: metricReaderOptions,
-  };
-});
-
-interface SdkMetricsMock {
-  __metricReaderOptions: unknown[];
-}
-
-function metricReaderOptions(): unknown[] {
-  return (jest.requireMock("@opentelemetry/sdk-metrics") as SdkMetricsMock)
-    .__metricReaderOptions;
-}
-
-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 exporterAt(index: number): InMemoryMetricExporter {
-  return mockExporterConstructor.mock.results[index]
-    .value as InMemoryMetricExporter;
-}
-
-function lastExporter(): InMemoryMetricExporter {
-  return exporterAt(mockExporterConstructor.mock.results.length - 1);
-}
-
-function metricNames(exporter: InMemoryMetricExporter): string[] {
-  return exporter
-    .getMetrics()
-    .flatMap((resourceMetrics) => resourceMetrics.scopeMetrics)
-    .flatMap((scopeMetrics) => scopeMetrics.metrics)
-    .map((metric) => metric.descriptor.name);
-}
-
-function metricData(
-  exporter: InMemoryMetricExporter,
-  name: string,
-): MetricData | undefined {
-  return exporter
-    .getMetrics()
-    .flatMap((resourceMetrics) => resourceMetrics.scopeMetrics)
-    .flatMap((scopeMetrics) => scopeMetrics.metrics)
-    .find((metric) => metric.descriptor.name === name);
-}
-
-const SEMCONV_HTTP_DURATION_BOUNDARIES = [
-  0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
-];
-
-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();
-    metricReaderOptions().length = 0;
-    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 = makeMeter({
-      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 = makeMeter({
-      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 = makeMeter(
-      meterConfig("metric-service", "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();
-
-    const exporter = lastExporter();
-    expect(metricNames(exporter)).toEqual(
-      expect.arrayContaining([
-        "metric-service.requests.total",
-        "metric-service.users.active",
-        "metric-service.requests.latency",
-        "cpu.usage",
-      ]),
-    );
-    expect(metricData(exporter, "cpu.usage")?.descriptor.description).toBe(
-      "Current CPU usage",
-    );
-    const counter = metricData(exporter, "metric-service.requests.total");
-    expect(counter?.descriptor.unit).toBe("");
-    expect(counter?.descriptor.description).toBe("");
-  });
-
-  it("records histogram values into the configured semconv seconds buckets", async () => {
-    const meter = makeMeter(
-      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
-    );
-
-    const histogram = meter.createHistogram("http.server.request.duration", {
-      description: "Duration of HTTP server requests",
-      unit: "s",
-      advice: { explicitBucketBoundaries: SEMCONV_HTTP_DURATION_BOUNDARIES },
-    });
-    for (const seconds of [0.005, 0.042, 0.08, 0.3, 1.2, 4.5]) {
-      histogram.record(seconds);
-    }
-
-    await meter.shutdown();
-
-    const metric = metricData(
-      lastExporter(),
-      "metric-service.http.server.request.duration",
-    );
-    expect(metric).toBeDefined();
-    expect(metric?.descriptor.description).toBe(
-      "Duration of HTTP server requests",
-    );
-    expect(metric?.descriptor.unit).toBe("s");
-    if (!metric || metric.dataPointType !== DataPointType.HISTOGRAM) {
-      throw new Error("expected a histogram metric");
-    }
-    const [dataPoint] = metric.dataPoints;
-    expect(dataPoint.value.count).toBe(6);
-    expect(dataPoint.value.buckets.boundaries).toEqual(
-      SEMCONV_HTTP_DURATION_BOUNDARIES,
-    );
-    expect(dataPoint.value.buckets.counts).toEqual([
-      1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 0,
-    ]);
-  });
-
-  it("forwards description and unit options for counters and up-down counters", async () => {
-    const meter = makeMeter(
-      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
-    );
-
-    meter
-      .createCounter("requests.total", {
-        description: "Total requests",
-        unit: "1",
-      })
-      .add(1);
-    meter
-      .createUpDownCounter("users.active", {
-        description: "Active users",
-        unit: "{user}",
-      })
-      .add(1);
-
-    await meter.shutdown();
-
-    const exporter = lastExporter();
-    const counter = metricData(exporter, "metric-service.requests.total");
-    expect(counter?.descriptor.description).toBe("Total requests");
-    expect(counter?.descriptor.unit).toBe("1");
-    const upDownCounter = metricData(exporter, "metric-service.users.active");
-    expect(upDownCounter?.descriptor.description).toBe("Active users");
-    expect(upDownCounter?.descriptor.unit).toBe("{user}");
-  });
-
-  it("accepts an options object for observable gauges and keeps them unprefixed", async () => {
-    const meter = makeMeter(
-      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
-    );
-
-    meter.createObservableGauge(
-      "cpu.usage",
-      (observableResult) => observableResult.observe(0.5),
-      { description: "Current CPU usage", unit: "1" },
-    );
-
-    await meter.shutdown();
-
-    const exporter = lastExporter();
-    const names = metricNames(exporter);
-    expect(names).toContain("cpu.usage");
-    expect(names).not.toContain("metric-service.cpu.usage");
-    const gauge = metricData(exporter, "cpu.usage");
-    expect(gauge?.descriptor.description).toBe("Current CPU usage");
-    expect(gauge?.descriptor.unit).toBe("1");
-  });
-
-  it("creates a histogram without the service-name prefix when the unprefixed option is set", async () => {
-    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);
-
-    await meter.shutdown();
-
-    const names = metricNames(lastExporter());
-    expect(names).toContain("session.duration");
-    expect(names).toContain("metric-service.requests.latency");
-    expect(names).not.toContain("metric-service.session.duration");
-  });
-
-  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),
-    );
-    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);
-  });
-
-  describe("export interval tuning", () => {
-    it("uses the documented default interval", async () => {
-      const meter = makeMeter(
-        meterConfig("metric-service", "http://collector:4318/v1/metrics"),
-      );
-
-      expect(metricReaderOptions()).toHaveLength(1);
-      expect(metricReaderOptions()[0]).toEqual({
-        exporter: expect.anything(),
-        exportIntervalMillis: 60000,
-      });
-      await meter.shutdown();
-    });
-
-    it.each([0, -5, 0.5])(
-      "clamps the export interval of %p seconds to one second",
-      async (interval) => {
-        const meter = makeMeter({
-          ...meterConfig("metric-service", "http://collector:4318/v1/metrics"),
-          OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: interval,
-        });
-
-        expect(
-          (metricReaderOptions()[0] as { exportIntervalMillis: number })
-            .exportIntervalMillis,
-        ).toBe(1000);
-        await meter.shutdown();
-      },
-    );
-
-    it("falls back to the default interval for a NaN value", async () => {
-      const meter = makeMeter({
-        ...meterConfig("metric-service", "http://collector:4318/v1/metrics"),
-        OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: NaN,
-      });
-
-      expect(
-        (metricReaderOptions()[0] as { exportIntervalMillis: number })
-          .exportIntervalMillis,
-      ).toBe(60000);
-      await meter.shutdown();
-    });
-  });
-
-  describe("service identity validation", () => {
-    it("rejects an empty SERVICE_ID without creating an exporter", () => {
-      expect(
-        () =>
-          new StandardMeter({
-            SERVICE_ID: "   ",
-            VERSION: "1.0.0",
-            OPENTELEMETRY_COLLECTOR_HTTP_METRICS:
-              "http://collector:4318/v1/metrics",
-          }),
-      ).toThrow("[otel-utils] SERVICE_ID must be a non-empty string");
-      expect(mockExporterConstructor).not.toHaveBeenCalled();
-    });
-
-    it("rejects an empty VERSION without creating an exporter", () => {
-      expect(
-        () =>
-          new StandardMeter({
-            SERVICE_ID: "metric-service",
-            VERSION: "",
-            OPENTELEMETRY_COLLECTOR_HTTP_METRICS:
-              "http://collector:4318/v1/metrics",
-          }),
-      ).toThrow("[otel-utils] VERSION must be a non-empty string");
-      expect(mockExporterConstructor).not.toHaveBeenCalled();
-    });
-  });
-});

package/src/StandardMeter.ts

@@ -1,167 +0,0 @@
-import {
-  Counter,
-  Histogram,
-  Meter,
-  metrics,
-  type MetricOptions,
-  ObservableGauge,
-  UpDownCounter,
-} from "@opentelemetry/api";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { createOTelResource } from "./utils/createResource";
-import {
-  MeterProvider,
-  PeriodicExportingMetricReader,
-} from "@opentelemetry/sdk-metrics";
-import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
-import {
-  normalizeExportIntervalSeconds,
-  validateServiceIdentity,
-} from "./utils/configValidation";
-
-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}.
- * `description`, `unit`, `valueType` and `advice` are forwarded to the
- * OpenTelemetry Meter; `advice.explicitBucketBoundaries` sets the histogram
- * bucket boundaries.
- */
-export interface StandardMeterCreateHistogramOptions extends MetricOptions {
-  /**
-   * Create the histogram without the `${serviceName}.` prefix:
-   * exported exactly as `key`.
-   */
-  unprefixed?: boolean;
-}
-
-export class StandardMeter {
-  private meter: Meter;
-  private meterProvider: MeterProvider;
-  private serviceVersion: string;
-  private serviceName: string;
-  private ownsGlobalProvider = false;
-  private shutdownPromise?: Promise<void>;
-
-  constructor(config: ConfigOTelInterface) {
-    validateServiceIdentity(config);
-    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>,
-        concurrencyLimit: 5,
-      };
-      if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-        collectorOptions.headers["Authorization"] =
-          `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
-      }
-      const metricExporter = new OTLPMetricExporter(collectorOptions);
-      this.meterProvider = new MeterProvider({
-        resource: createOTelResource(this.serviceName, this.serviceVersion),
-        readers: [
-          new PeriodicExportingMetricReader({
-            exporter: metricExporter,
-            exportIntervalMillis:
-              normalizeExportIntervalSeconds(
-                config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS,
-                60,
-              ) * 1000,
-          }),
-        ],
-      });
-    } else {
-      this.meterProvider = new MeterProvider({
-        resource: createOTelResource(this.serviceName, this.serviceVersion),
-      });
-    }
-    this.meter = this.meterProvider.getMeter(
-      `${this.serviceName}:${this.serviceVersion}`,
-    );
-    if (hasCollector) {
-      this.registerGlobalProvider();
-    }
-  }
-
-  public shutdown(): Promise<void> {
-    if (!this.shutdownPromise) {
-      this.shutdownPromise = this.doShutdown();
-    }
-    return this.shutdownPromise;
-  }
-
-  public createCounter(key: string, options?: MetricOptions): Counter {
-    return this.meter.createCounter(`${this.serviceName}.${key}`, options);
-  }
-
-  public createUpDownCounter(
-    key: string,
-    options?: MetricOptions,
-  ): UpDownCounter {
-    return this.meter.createUpDownCounter(`${this.serviceName}.${key}`, options);
-  }
-
-  public createHistogram(
-    key: string,
-    options?: StandardMeterCreateHistogramOptions,
-  ): Histogram {
-    const { unprefixed, ...instrumentOptions } = options ?? {};
-    return this.meter.createHistogram(
-      unprefixed ? key : `${this.serviceName}.${key}`,
-      instrumentOptions,
-    );
-  }
-
-  public createObservableGauge(
-    key: string,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    callback: (observableResult: any) => void,
-    descriptionOrOptions?: string | MetricOptions,
-  ): ObservableGauge {
-    const observableGauge = this.meter.createObservableGauge(
-      key,
-      typeof descriptionOrOptions === "string"
-        ? { description: descriptionOrOptions }
-        : descriptionOrOptions,
-    );
-    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;
-  }
-}