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

package/src/StandardTracer.spec.ts

@@ -1,349 +0,0 @@
-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", () => {
-  const { ExportResultCode } = jest.requireActual<
-    typeof import("@opentelemetry/core")
-  >("@opentelemetry/core");
-  return {
-    OTLPTraceExporter: jest.fn().mockImplementation(function () {
-      const exportedSpans: ExportedSpan[] = [];
-      return {
-        export: (
-          spans: ExportedSpan[],
-          resultCallback: (result: { code: number }) => void,
-        ) => {
-          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 {
-  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", () => {
-  const createdTracers: StandardTracer[] = [];
-  let warnSpy: jest.SpyInstance;
-
-  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");
-      expect(span.attributes[ATTR_HTTP_ROUTE]).toBe(
-        "test-service-1.0.0-my-operation",
-      );
-      span.end();
-    });
-
-    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);
-      expect(child.parentSpanContext?.spanId).toBe(parent.spanContext().spanId);
-      expect(child.attributes[ATTR_HTTP_REQUEST_METHOD]).toBeUndefined();
-      expect(child.attributes[ATTR_HTTP_ROUTE]).toBeUndefined();
-      child.end();
-      parent.end();
-    });
-
-    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,
-      });
-      expect(span.kind).toBe(SpanKind.SERVER);
-      expect(span.attributes[ATTR_HTTP_REQUEST_METHOD]).toBeUndefined();
-      expect(span.attributes[ATTR_HTTP_ROUTE]).toBeUndefined();
-      span.end();
-    });
-
-    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,
-      });
-      expect(child.kind).toBe(SpanKind.CLIENT);
-      expect(child.spanContext().traceId).toBe(parent.spanContext().traceId);
-      expect(child.parentSpanContext?.spanId).toBe(parent.spanContext().spanId);
-      child.end();
-      parent.end();
-    });
-  });
-
-  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);
-
-      expect(headers.traceparent).toMatch(/^00-/);
-      expect(headers.traceparent).toContain(span.spanContext().traceId);
-      span.end();
-    });
-
-    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);
-
-      expect(result).toBe(headers);
-      expect(headers["x-custom"]).toBe("value");
-      expect(headers["traceparent"]).toContain(span.spanContext().traceId);
-      span.end();
-    });
-  });
-
-  describe("exporter configuration", () => {
-    it("builds the trace exporter with URL and auth header and shuts it down", async () => {
-      const exportTracer = makeTracer({
-        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 = makeTracer({
-        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 = makeTracer(tracerConfig("plain-service"));
-      await expect(plainTracer.shutdown()).resolves.toBeUndefined();
-    });
-  });
-
-  describe("service identity validation", () => {
-    it("rejects an empty SERVICE_ID", () => {
-      expect(
-        () => new StandardTracer({ SERVICE_ID: "   ", VERSION: "1.0.0" }),
-      ).toThrow("[otel-utils] SERVICE_ID must be a non-empty string");
-    });
-
-    it("rejects an empty VERSION", () => {
-      expect(
-        () => new StandardTracer({ SERVICE_ID: "test-service", VERSION: "" }),
-      ).toThrow("[otel-utils] VERSION must be a non-empty string");
-    });
-  });
-
-  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,190 +0,0 @@
-import {
-  context,
-  defaultTextMapSetter,
-  ROOT_CONTEXT,
-  SpanKind,
-  trace,
-  Tracer,
-} from "@opentelemetry/api";
-import type { Span as ApiSpan } from "@opentelemetry/api";
-import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
-import {
-  BatchSpanProcessor,
-  type Span,
-  TracerProvider,
-} from "@opentelemetry/sdk-trace";
-import {
-  ATTR_HTTP_REQUEST_METHOD,
-  ATTR_HTTP_ROUTE,
-} from "@opentelemetry/semantic-conventions";
-import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
-import { validateServiceIdentity } from "./utils/configValidation";
-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}.
- */
-export interface StandardTracerStartSpanOptions {
-  /**
-   * OpenTelemetry span kind (default `SpanKind.INTERNAL`).
-   *
-   * Providing options means the caller describes the span itself: the
-   * parentless default attributes (`http.request.method=BACKEND` and the
-   * synthetic `http.route`) are not added.
-   */
-  kind?: SpanKind;
-}
-
-export class StandardTracer {
-  private static readonly SPAN_NAME_SANITIZE_RE = /[^a-zA-Z0-9-_/]/g;
-  private static readonly PROPAGATOR = new W3CTraceContextPropagator();
-
-  private traceProvider: TracerProvider;
-  private tracer: Tracer;
-  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;
-    const spanProcessors = [];
-
-    if (config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES) {
-      const exporterHeaders: Record<string, string> = {};
-      if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
-        exporterHeaders["Authorization"] =
-          `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
-      }
-      const exporter = new OTLPTraceExporter({
-        url: config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES,
-        headers: exporterHeaders,
-      });
-      spanProcessors.push(new BatchSpanProcessor({ exporter }));
-    }
-    this.traceProvider = new TracerProvider({
-      idGenerator: new AWSXRayIdGenerator(),
-      resource: createOTelResource(this.serviceName, this.serviceVersion),
-      spanProcessors,
-    });
-    // 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 shutdown(): Promise<void> {
-    if (!this.shutdownPromise) {
-      this.shutdownPromise = this.doShutdown();
-    }
-    return this.shutdownPromise;
-  }
-
-  public startSpan(
-    name: string,
-    parentSpan?: Span,
-    options?: StandardTracerStartSpanOptions,
-  ): Span {
-    const sanitizedName = name.replace(
-      StandardTracer.SPAN_NAME_SANITIZE_RE,
-      "_",
-    );
-    if (parentSpan) {
-      return this.tracer.startSpan(
-        sanitizedName,
-        options,
-        trace.setSpan(context.active(), parentSpan),
-      ) as Span;
-    }
-    if (options) {
-      return this.tracer.startSpan(sanitizedName, options) as Span;
-    }
-    const span = this.tracer.startSpan(sanitizedName) as Span;
-    span.setAttribute(ATTR_HTTP_REQUEST_METHOD, `BACKEND`);
-    span.setAttribute(
-      ATTR_HTTP_ROUTE,
-      `${this.serviceName}-${this.serviceVersion}-${sanitizedName}`,
-    );
-    return span;
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  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
-      headers as any,
-      defaultTextMapSetter,
-    );
-    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.",
-    );
-  }
-}

package/src/createResource.spec.ts

@@ -1,20 +0,0 @@
-import { createOTelResource } from "./utils/createResource";
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, ATTR_NETWORK_LOCAL_ADDRESS } from "@opentelemetry/semantic-conventions";
-
-describe("createOTelResource", () => {
-  it("should create a resource with the provided service name and version", () => {
-    const resource = createOTelResource("test-service", "1.0.0");
-    const attrs = resource.attributes;
-
-    expect(attrs[ATTR_SERVICE_NAME]).toBe("test-service");
-    expect(attrs[ATTR_SERVICE_VERSION]).toBe("1.0.0");
-  });
-
-  it("should include the local hostname as network local address", () => {
-    const resource = createOTelResource("test-service", "1.0.0");
-    const attrs = resource.attributes;
-
-    expect(attrs[ATTR_NETWORK_LOCAL_ADDRESS]).toBeDefined();
-    expect(typeof attrs[ATTR_NETWORK_LOCAL_ADDRESS]).toBe("string");
-  });
-});

package/src/models/ConfigOTelInterface.ts

@@ -1,16 +0,0 @@
-export type ConsoleLogMode = "always" | "fallback" | "never";
-
-export interface ConfigOTelInterface {
-  SERVICE_ID: string;
-  VERSION: string;
-  OPENTELEMETRY_COLLECTOR_HTTP_TRACES?: string;
-  OPENTELEMETRY_COLLECTOR_HTTP_METRICS?: string;
-  OPENTELEMETRY_COLLECTOR_HTTP_LOGS?: string;
-  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS?: number;
-  OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS?: number;
-  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_QUEUE_SIZE?: number;
-  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_MAX_BATCH_SIZE?: number;
-  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_TIMEOUT_MILLIS?: number;
-  OPENTELEMETRY_CONSOLE_LOG_MODE?: ConsoleLogMode;
-  OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER?: string;
-}

package/src/models/StandardLoggerInterface.ts

@@ -1,5 +0,0 @@
-import type { Logger } from "@opentelemetry/api";
-
-export interface StandardLoggerInterface {
-  getLogger(): Logger | undefined;
-}