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

package/README.md

@@ -48,7 +48,7 @@ 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.
 
 ### StandardLogger

package/dist/src/StandardTracer.d.ts

@@ -1,5 +1,19 @@
+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;
@@ -7,6 +21,6 @@ export declare class StandardTracer {
     private serviceVersion;
     private serviceName;
     constructor(config: ConfigOTelInterface);
-    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

@@ -71,10 +71,13 @@ class StandardTracer {
         api_1.default.context.setGlobalContextManager(contextManager);
         this.tracer = api_1.default.trace.getTracer(`${this.serviceName}:${this.serviceVersion}`);
     }
-    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.2.1",
+  "version": "1.3.0-beta.30.5138047",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",

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,6 +18,20 @@ 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();
@@ -56,7 +71,11 @@ export class StandardTracer {
     );
   }
 
-  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,
       "_",
@@ -64,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(