@devopsplaybook.io/otel-utils 1.3.0-beta.28.b481842 → 1.3.0-beta.30.5138047

package/README.md

@@ -48,10 +48,8 @@ span.end();
 
 **Methods:**
 
-- `startSpan(name, parentSpan?)` — Creates a span. When no `parentSpan` is provided, adds `http.request_method=BACKEND` and `http.route` attributes. Span names are sanitized to `[a-zA-Z0-9-_/]`.
+- `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.
-- `forceFlush()` — Flushes pending spans to the exporter.
-- `shutdown()` — Shuts down the tracer provider and flushes pending spans (call once, on process exit).
 
 ### StandardLogger
 
@@ -72,8 +70,6 @@ moduleLog.info("Hello world");
 - `initOTel(config)` — Initializes the logger provider and optional OTLP exporter.
 - `getLogger()` — Returns the underlying OTel `Logger` or `undefined`.
 - `createModuleLogger(moduleName)` — Creates a `ModuleLogger` scoped to a module name.
-- `forceFlush()` — Flushes pending log records to the exporter (no-op when the provider was never initialized).
-- `shutdown()` — Shuts down the logger provider and flushes pending log records; no-op when the provider was never initialized (call once, on process exit).
 
 ### ModuleLogger
 
@@ -126,8 +122,6 @@ 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.
-- `forceFlush()` — Flushes pending metric data points to the exporter.
-- `shutdown()` — Shuts down the meter provider and flushes pending metric data points (call once, on process exit).
 
 ## Internal Utilities
 

package/dist/src/StandardLogger.d.ts

@@ -4,12 +4,9 @@ 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;
-    forceFlush(): Promise<void>;
-    shutdown(): Promise<void>;
     getLogger(): OTelLogger | undefined;
     createModuleLogger(moduleName: string): ModuleLogger;
 }

package/dist/src/StandardLogger.js

@@ -30,20 +30,9 @@ class StandardLogger {
                 ],
                 resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             });
-            this.loggerProvider = loggerProvider;
             this.logger = loggerProvider.getLogger(`${this.serviceName}:${this.serviceVersion}`);
         }
     }
-    forceFlush() {
-        return this.loggerProvider
-            ? this.loggerProvider.forceFlush()
-            : Promise.resolve();
-    }
-    shutdown() {
-        return this.loggerProvider
-            ? this.loggerProvider.shutdown()
-            : Promise.resolve();
-    }
     getLogger() {
         return this.logger;
     }

package/dist/src/StandardMeter.d.ts

@@ -2,12 +2,9 @@ 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);
-    forceFlush(): Promise<void>;
-    shutdown(): Promise<void>;
     createCounter(key: string): Counter;
     createUpDownCounter(key: string): UpDownCounter;
     createHistogram(key: string): Histogram;

package/dist/src/StandardMeter.js

@@ -36,15 +36,8 @@ class StandardMeter {
                 resource: (0, createResource_1.createOTelResource)(this.serviceName, this.serviceVersion),
             });
         }
-        this.meterProvider = meterProvider;
         this.meter = meterProvider.getMeter(`${this.serviceName}:${this.serviceVersion}`);
     }
-    forceFlush() {
-        return this.meterProvider.forceFlush();
-    }
-    shutdown() {
-        return this.meterProvider.shutdown();
-    }
     createCounter(key) {
         return this.meter.createCounter(`${this.serviceName}.${key}`);
     }

package/dist/src/StandardTracer.d.ts

@@ -1,15 +1,26 @@
+import { SpanKind } from "@opentelemetry/api";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
+/**
+ * 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 declare class StandardTracer {
     private static readonly SPAN_NAME_SANITIZE_RE;
     private static readonly PROPAGATOR;
     private tracer;
-    private traceProvider;
     private serviceVersion;
     private serviceName;
     constructor(config: ConfigOTelInterface);
-    forceFlush(): Promise<void>;
-    shutdown(): Promise<void>;
-    startSpan(name: string, parentSpan?: Span): Span;
+    startSpan(name: string, parentSpan?: Span, options?: StandardTracerStartSpanOptions): Span;
     static updateHttpHeader(context: Span, headers?: {}): any;
 }

package/dist/src/StandardTracer.js

@@ -66,22 +66,18 @@ class StandardTracer {
             spanProcessors,
         });
         traceProvider.register();
-        this.traceProvider = traceProvider;
         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}`);
     }
-    forceFlush() {
-        return this.traceProvider.forceFlush();
-    }
-    shutdown() {
-        return this.traceProvider.shutdown();
-    }
-    startSpan(name, parentSpan) {
+    startSpan(name, parentSpan, options) {
         const sanitizedName = String(name).replace(StandardTracer.SPAN_NAME_SANITIZE_RE, "_");
         if (parentSpan) {
-            return this.tracer.startSpan(sanitizedName, undefined, api_1.default.trace.setSpan(api_1.default.context.active(), parentSpan));
+            return this.tracer.startSpan(sanitizedName, options, api_1.default.trace.setSpan(api_1.default.context.active(), parentSpan));
+        }
+        if (options) {
+            return this.tracer.startSpan(sanitizedName, options);
         }
         const span = this.tracer.startSpan(sanitizedName);
         span.setAttribute(semantic_conventions_1.ATTR_HTTP_REQUEST_METHOD, `BACKEND`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils",
-  "version": "1.3.0-beta.28.b481842",
+  "version": "1.3.0-beta.30.5138047",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",
@@ -46,7 +46,7 @@
     "@types/node": "^26.6.2",
     "@types/sqlite3": "^5.1.0",
     "jest": "^30.5.2",
-    "oxlint": "^1.83.0",
+    "oxlint": "^1.85.0",
     "typescript": "^7.0.2"
   },
   "publishConfig": {

package/src/StandardLogger.ts

@@ -12,7 +12,6 @@ import type { StandardLoggerInterface } from "./models/StandardLoggerInterface";
 
 export class StandardLogger implements StandardLoggerInterface {
   private logger?: OTelLogger;
-  private loggerProvider?: LoggerProvider;
   private serviceVersion?: string;
   private serviceName?: string;
 
@@ -44,25 +43,12 @@ export class StandardLogger implements StandardLoggerInterface {
         resource: createOTelResource(this.serviceName, this.serviceVersion),
       });
 
-      this.loggerProvider = loggerProvider;
       this.logger = loggerProvider.getLogger(
         `${this.serviceName}:${this.serviceVersion}`,
       );
     }
   }
 
-  public forceFlush(): Promise<void> {
-    return this.loggerProvider
-      ? this.loggerProvider.forceFlush()
-      : Promise.resolve();
-  }
-
-  public shutdown(): Promise<void> {
-    return this.loggerProvider
-      ? this.loggerProvider.shutdown()
-      : Promise.resolve();
-  }
-
   public getLogger(): OTelLogger | undefined {
     return this.logger;
   }

package/src/StandardMeter.ts

@@ -15,7 +15,6 @@ import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 
 export class StandardMeter {
   private meter: Meter;
-  private meterProvider: MeterProvider;
   private serviceVersion: string;
   private serviceName: string;
 
@@ -50,20 +49,11 @@ export class StandardMeter {
         resource: createOTelResource(this.serviceName, this.serviceVersion),
       });
     }
-    this.meterProvider = meterProvider;
     this.meter = meterProvider.getMeter(
       `${this.serviceName}:${this.serviceVersion}`,
     );
   }
 
-  public forceFlush(): Promise<void> {
-    return this.meterProvider.forceFlush();
-  }
-
-  public shutdown(): Promise<void> {
-    return this.meterProvider.shutdown();
-  }
-
   public createCounter(key: string): Counter {
     return this.meter.createCounter(`${this.serviceName}.${key}`);
   }

package/src/StandardTracer.spec.ts

@@ -0,0 +1,68 @@
+import { SpanKind } from "@opentelemetry/api";
+import {
+  ATTR_HTTP_REQUEST_METHOD,
+  ATTR_HTTP_ROUTE,
+} from "@opentelemetry/semantic-conventions";
+import { StandardTracer } from "./StandardTracer";
+
+describe("StandardTracer", () => {
+  let tracer: StandardTracer;
+
+  beforeAll(() => {
+    tracer = new StandardTracer({
+      SERVICE_ID: "test-service",
+      VERSION: "1.0.0",
+    });
+  });
+
+  describe("startSpan", () => {
+    it("sanitizes span names", () => {
+      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 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 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 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 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();
+    });
+  });
+});

package/src/StandardTracer.ts

@@ -1,6 +1,7 @@
 import opentelemetry, {
   defaultTextMapSetter,
   ROOT_CONTEXT,
+  SpanKind,
   trace,
   Tracer,
 } from "@opentelemetry/api";
@@ -17,12 +18,25 @@ import {
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { createOTelResource } from "./utils/createResource";
 
+/**
+ * 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 tracer: Tracer;
-  private traceProvider: NodeTracerProvider;
   private serviceVersion: string;
   private serviceName: string;
 
@@ -49,7 +63,6 @@ export class StandardTracer {
       spanProcessors,
     });
     traceProvider.register();
-    this.traceProvider = traceProvider;
     const contextManager = new AsyncHooksContextManager();
     contextManager.enable();
     opentelemetry.context.setGlobalContextManager(contextManager);
@@ -58,15 +71,11 @@ export class StandardTracer {
     );
   }
 
-  public forceFlush(): Promise<void> {
-    return this.traceProvider.forceFlush();
-  }
-
-  public shutdown(): Promise<void> {
-    return this.traceProvider.shutdown();
-  }
-
-  public startSpan(name: string, parentSpan?: Span): Span {
+  public startSpan(
+    name: string,
+    parentSpan?: Span,
+    options?: StandardTracerStartSpanOptions,
+  ): Span {
     const sanitizedName = String(name).replace(
       StandardTracer.SPAN_NAME_SANITIZE_RE,
       "_",
@@ -74,10 +83,13 @@ export class StandardTracer {
     if (parentSpan) {
       return this.tracer.startSpan(
         sanitizedName,
-        undefined,
+        options,
         opentelemetry.trace.setSpan(opentelemetry.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(

package/src/Shutdown.spec.ts

@@ -1,43 +0,0 @@
-import { StandardLogger } from "./StandardLogger";
-import { StandardMeter } from "./StandardMeter";
-import { StandardTracer } from "./StandardTracer";
-import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
-
-const config: ConfigOTelInterface = {
-  SERVICE_ID: "test-service",
-  VERSION: "1.0.0",
-  OPENTELEMETRY_COLLECTOR_HTTP_TRACES: "",
-  OPENTELEMETRY_COLLECTOR_HTTP_METRICS: "",
-  OPENTELEMETRY_COLLECTOR_HTTP_LOGS: "",
-  OPENTELEMETRY_COLLECTOR_AWS: false,
-  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: 60,
-  OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: 60,
-  OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: "",
-};
-
-describe("OTel shutdown and forceFlush", () => {
-  it("StandardMeter exposes forceFlush and shutdown that resolve", async () => {
-    const meter = new StandardMeter(config);
-    await expect(meter.forceFlush()).resolves.toBeUndefined();
-    await expect(meter.shutdown()).resolves.toBeUndefined();
-  });
-
-  it("StandardLogger exposes forceFlush and shutdown that resolve without OTel endpoint", async () => {
-    const logger = new StandardLogger();
-    await expect(logger.forceFlush()).resolves.toBeUndefined();
-    await expect(logger.shutdown()).resolves.toBeUndefined();
-  });
-
-  it("StandardLogger flushes and shuts down the provider when initialized", async () => {
-    const logger = new StandardLogger();
-    logger.initOTel(config);
-    await expect(logger.forceFlush()).resolves.toBeUndefined();
-    await expect(logger.shutdown()).resolves.toBeUndefined();
-  });
-
-  it("StandardTracer exposes forceFlush and shutdown that resolve", async () => {
-    const tracer = new StandardTracer(config);
-    await expect(tracer.forceFlush()).resolves.toBeUndefined();
-    await expect(tracer.shutdown()).resolves.toBeUndefined();
-  });
-});