@ogcio/o11y-sdk-node 0.2.0 → 0.3.0

package/test/exporter/pii-exporter-decorator.test.ts

@@ -0,0 +1,139 @@
+import type { ReadableLogRecord } from "@opentelemetry/sdk-logs";
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { NodeSDKConfig } from "../../index.js";
+import { PIIExporterDecorator } from "../../lib/exporter/pii-exporter-decorator.js";
+import * as pii from "../../lib/internals/pii-detection.js";
+
+const mockExporter = {
+  export: vi.fn(),
+  forceFlush: vi.fn().mockResolvedValue(undefined),
+  shutdown: vi.fn().mockResolvedValue(undefined),
+  _delegate: {}, // required by OTLPExporterBase
+};
+
+const mockCallback = vi.fn();
+
+const baseSpan = (): ReadableSpan =>
+  ({
+    name: "john.doe@example.com",
+    kind: 1,
+    spanContext: () => ({ traceId: "abc", spanId: "def" }),
+    attributes: { email: "john.doe@example.com" },
+    resource: {
+      attributes: { team: "dev@example.com" },
+      otherProp: "shouldBeLost",
+    },
+    links: [{ attributes: { collaborator: "co@example.com" } }],
+    events: [{ name: "event@email.com", attributes: { code: "123" } }],
+  }) as any;
+
+const baseLog = (): ReadableLogRecord =>
+  ({
+    body: "user: john.doe@example.com",
+    attributes: { email: "john.doe@example.com" },
+    resource: {
+      attributes: { service: "log@example.com" },
+      otherProp: "shouldBeLost",
+    },
+    severityText: "INFO",
+    severityNumber: 1,
+  }) as any;
+
+vi.mock("../../lib/internals/pii-detection.js", async () => {
+  return {
+    _cleanStringPII: vi.fn((v: string) => `[REDACTED(${v})]`),
+    _cleanObjectPII: vi.fn((obj: any) =>
+      Object.fromEntries(
+        Object.entries(obj || {}).map(([k, v]) => [k, `[REDACTED(${v})]`]),
+      ),
+    ),
+    _cleanLogBodyPII: vi.fn((v: any) => `[REDACTED_BODY(${v})]`),
+  };
+});
+
+describe("PIIExporterDecorator", () => {
+  let decorator: PIIExporterDecorator;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("delegates forceFlush and shutdown", async () => {
+    const config: NodeSDKConfig = {};
+    decorator = new PIIExporterDecorator(mockExporter as any, config);
+
+    await decorator.forceFlush();
+    await decorator.shutdown();
+
+    expect(mockExporter.forceFlush).toHaveBeenCalled();
+    expect(mockExporter.shutdown).toHaveBeenCalled();
+  });
+
+  it("skips redaction if detection.email is false", () => {
+    const config: NodeSDKConfig = { detection: { email: false } };
+    decorator = new PIIExporterDecorator(mockExporter as any, config);
+
+    const spans = [baseSpan()];
+    decorator.export(spans, mockCallback);
+
+    expect(mockExporter.export).toHaveBeenCalledWith(spans, mockCallback);
+    expect(pii._cleanStringPII).not.toHaveBeenCalled();
+    expect(pii._cleanObjectPII).not.toHaveBeenCalled();
+  });
+
+  it("redacts span data if detection.email is true", () => {
+    const config: NodeSDKConfig = { detection: { email: true } };
+    decorator = new PIIExporterDecorator(mockExporter as any, config);
+
+    const span = baseSpan();
+    decorator.export([span], mockCallback);
+
+    expect(pii._cleanStringPII).toHaveBeenCalled();
+    expect(pii._cleanObjectPII).toHaveBeenCalled();
+    expect(mockExporter.export).toHaveBeenCalledWith([span], mockCallback);
+
+    // verify name and nested structure were touched
+    expect(span.name).toMatch(/^\[REDACTED\(/);
+    expect(span.attributes.email).toMatch(/^\[REDACTED\(/);
+
+    // Resource is replaced with only attributes, old props lost
+    expect(span.resource).toEqual({
+      attributes: { team: "[REDACTED(dev@example.com)]" },
+    });
+
+    expect(span.events[0].name).toMatch(/^\[REDACTED\(/);
+  });
+
+  it("redacts log record data if detection.email is true", () => {
+    const config: NodeSDKConfig = { detection: { email: true } };
+    decorator = new PIIExporterDecorator(mockExporter as any, config);
+
+    const log = baseLog();
+    decorator.export([log], mockCallback);
+
+    expect(pii._cleanLogBodyPII).toHaveBeenCalled();
+    expect(pii._cleanObjectPII).toHaveBeenCalled();
+
+    expect(log.body).toMatch(/^\[REDACTED_BODY\(/);
+    expect(log.attributes.email).toMatch(/^\[REDACTED\(/);
+
+    // Resource replaced with only attributes, other props lost
+    expect(log.resource).toEqual({
+      attributes: { service: "[REDACTED(log@example.com)]" },
+    });
+  });
+
+  it("handles a mix of spans and logs", () => {
+    const config: NodeSDKConfig = { detection: { email: true } };
+    decorator = new PIIExporterDecorator(mockExporter as any, config);
+
+    const items = [baseSpan(), baseLog()];
+    decorator.export(items, mockCallback);
+
+    expect(mockExporter.export).toHaveBeenCalledWith(items, mockCallback);
+    expect(pii._cleanLogBodyPII).toHaveBeenCalled();
+    expect(pii._cleanStringPII).toHaveBeenCalled();
+    expect(pii._cleanObjectPII).toHaveBeenCalled();
+  });
+});

package/test/integration/{integration.test.ts → http-tracing.integration.test.ts}

@@ -10,8 +10,6 @@ describe("instrumentation integration test", () => {
     let health_traces_counter = 0;
     let dummy_traces_counter = 0;
 
-    console.log(data.split(/\nts=/).length);
-
     for (const line of data.split(/\nts=/)) {
       const parsedLine: Record<string, object | string | number> =
         parseLog(line);

package/test/integration/pii.integration.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, assert } from "vitest";
+import { parseLog } from "../utils/alloy-log-parser";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("pii integration test", () => {
+  test("should check redacted attributes and detect zero emails in logs", async () => {
+    const data = await readFile(join(__dirname, "logs.txt"), "utf-8");
+
+    let health_traces_counter = 0;
+    let dummy_traces_counter = 0;
+    let email_not_redacted = 0;
+
+    for (const line of data.split(/\nts=/)) {
+      const parsedLine: Record<string, object | string | number> =
+        parseLog(line);
+
+      if (
+        parsedLine["attributes"] &&
+        parsedLine["attributes"]["span_kind"] &&
+        parsedLine["attributes"]["span_kind"] === "log"
+      ) {
+        const matches = (parsedLine["log_body"] as string).match(
+          /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+        );
+        if (matches) {
+          email_not_redacted++;
+        }
+      }
+
+      if (
+        parsedLine["attributes"] &&
+        parsedLine["attributes"]["span_kind"] &&
+        parsedLine["attributes"]["span_kind"] === "trace"
+      ) {
+        if (parsedLine["attributes"]["http.target"] === "/api/dummy") {
+          dummy_traces_counter++;
+
+          // verify global sdk span resource
+          assert.equal(
+            parsedLine["resource_attributes"]["email"],
+            "[REDACTED EMAIL]",
+          );
+
+          // verify global sdk span attributes
+          assert.equal(parsedLine["attributes"]["email"], "[REDACTED EMAIL]");
+          // verify custom runtime span attributes
+          assert.equal(
+            parsedLine["attributes"]["multiple.email"],
+            "[REDACTED EMAIL]",
+          );
+
+          // verify global sdk span attributes
+          assert.equal(parsedLine["events"]["email"], "[REDACTED EMAIL]");
+
+          continue;
+        }
+        if (parsedLine["attributes"]["http.target"] === "/api/health") {
+          health_traces_counter++;
+        }
+      }
+    }
+
+    assert.equal(email_not_redacted, 0);
+    assert.equal(health_traces_counter, 0);
+    assert.equal(dummy_traces_counter, 2);
+  });
+});

package/test/integration/run.sh

@@ -16,7 +16,7 @@ docker run -d \
     --name $ALLOY_CONTAINER_NAME \
     -p 4317:4317 \
     -p 4318:4318 \
-    grafana/alloy \
+    grafana/alloy:v1.9.2 \
     run --server.http.listen-addr=0.0.0.0:12345 --stability.level=experimental /etc/alloy/config.alloy
 
 MAX_RETRIES=10
@@ -69,7 +69,7 @@ if [[ $ERROR_CODE -eq 0 ]]; then
 fi
 
 # sleep N seconds to await instrumentation flow send and receiving signals
-sleep 10
+sleep 1
 
 # Copy logs from container to file
 docker container logs $ALLOY_CONTAINER_NAME >&$ROOT_PATH/packages/sdk-node/test/integration/logs.txt

package/test/internals/hooks.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi } from "vitest";
+import { _shutdownHook } from "../../lib/internals/hooks";
+
+describe("shutdown hook", () => {
+  it("should call sdk.shutdown and log success on SIGTERM", async () => {
+    const shutdownMock = vi.fn().mockResolvedValue(undefined);
+    const consoleLogMock = vi
+      .spyOn(console, "log")
+      .mockImplementation(() => {});
+
+    _shutdownHook({ shutdown: shutdownMock });
+
+    process.emit("SIGTERM");
+    // Wait for async logic
+    await Promise.resolve();
+
+    expect(shutdownMock).toHaveBeenCalled();
+    expect(consoleLogMock).toHaveBeenCalledWith(
+      "NodeJS OpenTelemetry instrumentation shutdown successfully",
+    );
+
+    consoleLogMock.mockRestore();
+  });
+
+  it("should catch and log errors on shutdown failure", async () => {
+    const error = new Error("Shutdown failed");
+    const shutdownMock = vi.fn().mockRejectedValue(error);
+    const consoleErrorMock = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    _shutdownHook({ shutdown: shutdownMock });
+
+    process.emit("SIGTERM");
+    // Wait for async logic
+    await Promise.resolve();
+
+    expect(consoleErrorMock).toHaveBeenCalledWith(
+      "Error shutting down NodeJS OpenTelemetry instrumentation:",
+      error,
+    );
+
+    consoleErrorMock.mockRestore();
+  });
+});

package/test/internals/pii-detection.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  _cleanStringPII,
+  _cleanLogBodyPII,
+} from "../../lib/internals/pii-detection.js";
+import * as sharedMetrics from "../../lib/internals/shared-metrics.js";
+
+describe("PII Detection Utils", () => {
+  const mockMetricAdd = vi.fn();
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(sharedMetrics, "_getPIICounterRedactionMetric").mockReturnValue({
+      add: mockMetricAdd,
+    });
+  });
+
+  describe("_cleanStringPII", () => {
+    it("redacts plain email", () => {
+      const input = "admin@example.com";
+      const output = _cleanStringPII(input, "log");
+
+      expect(output).toBe("[REDACTED EMAIL]");
+      expect(mockMetricAdd).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({
+          pii_email_domain: "example.com",
+          pii_type: "email",
+          redaction_source: "log",
+        }),
+      );
+    });
+
+    it("redacts email in URL-encoded string", () => {
+      const input = "user%40gmail.com";
+      const output = _cleanStringPII(input, "log");
+
+      expect(output).toBe("[REDACTED EMAIL]");
+      expect(mockMetricAdd).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({
+          pii_format: "url",
+          pii_email_domain: "gmail.com",
+        }),
+      );
+    });
+
+    it("handles strings without email unchanged", () => {
+      const input = "hello world";
+      const output = _cleanStringPII(input, "log");
+
+      expect(output).toBe("hello world");
+      expect(mockMetricAdd).not.toHaveBeenCalled();
+    });
+
+    it("handles array of strings", () => {
+      const input = ["one@gmail.com", "two@example.com"];
+      const output = _cleanStringPII(input, "log");
+
+      expect(output).toEqual(["[REDACTED EMAIL]", "[REDACTED EMAIL]"]);
+      expect(mockMetricAdd).toHaveBeenCalledTimes(2);
+    });
+
+    it("ignores non-string input", () => {
+      expect(_cleanStringPII(1234, "trace")).toBe(1234);
+      expect(_cleanStringPII(true, "trace")).toBe(true);
+      expect(_cleanStringPII(undefined, "trace")).toBeUndefined();
+      expect(mockMetricAdd).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("_cleanLogBodyPII", () => {
+    it("cleans string email", () => {
+      const result = _cleanLogBodyPII("demo@abc.com");
+      expect(result).toBe("[REDACTED EMAIL]");
+    });
+
+    it("cleans deeply nested object", () => {
+      const input = {
+        user: {
+          email: "test@gmail.com",
+          profile: {
+            contact: "foo@example.com",
+          },
+        },
+        status: "active",
+      };
+
+      const result = _cleanLogBodyPII(input);
+
+      expect(result).toEqual({
+        user: {
+          email: "[REDACTED EMAIL]",
+          profile: {
+            contact: "[REDACTED EMAIL]",
+          },
+        },
+        status: "active",
+      });
+    });
+
+    it("cleans Uint8Array input", () => {
+      const str = "admin@gmail.com";
+      const buffer = new TextEncoder().encode(str);
+      const result = _cleanLogBodyPII(buffer);
+      const decoded = new TextDecoder().decode(result as Uint8Array);
+
+      expect(decoded).toBe("[REDACTED EMAIL]");
+    });
+
+    it("skips malformed Uint8Array decode", () => {
+      const corrupted = new Uint8Array([0xff, 0xfe, 0xfd]);
+      const result = _cleanLogBodyPII(corrupted);
+
+      // Should return a Uint8Array, but unmodified/redaction should not happen
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result).not.toEqual(expect.arrayContaining([91, 82, 69]));
+    });
+
+    it("cleans arrays of values", () => {
+      const result = _cleanLogBodyPII([
+        "bob@abc.com",
+        123,
+        { nested: "jane@example.com" },
+      ]);
+
+      expect(result).toEqual([
+        "[REDACTED EMAIL]",
+        123,
+        { nested: "[REDACTED EMAIL]" },
+      ]);
+    });
+
+    it("passes null and boolean through", () => {
+      expect(_cleanLogBodyPII(null)).toBeNull();
+      expect(_cleanLogBodyPII(undefined)).toBeUndefined();
+      expect(_cleanLogBodyPII(true)).toBe(true);
+      expect(_cleanLogBodyPII(false)).toBe(false);
+    });
+  });
+});

package/test/internals/shared-metrics.test.ts

@@ -0,0 +1,34 @@
+vi.mock("../../lib/metrics", () => {
+  return {
+    getMetric: vi.fn(),
+  };
+});
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { _getPIICounterRedactionMetric } from "../../lib/internals/shared-metrics.js";
+import { getMetric } from "../../lib/metrics"; // Get the mocked function
+
+describe("shared metrics", () => {
+  const mockMetric = { add: vi.fn() };
+
+  beforeEach(() => {
+    vi.resetModules(); // Clear module-level cache
+    vi.restoreAllMocks();
+    (getMetric as vi.Mock).mockClear(); // clear call history
+    (getMetric as vi.Mock).mockReturnValue(mockMetric);
+  });
+
+  it("calls getMetric with correct arguments and caches result", () => {
+    const metric1 = _getPIICounterRedactionMetric();
+    const metric2 = _getPIICounterRedactionMetric();
+
+    expect(getMetric).toHaveBeenCalledOnce();
+    expect(getMetric).toHaveBeenCalledWith("counter", {
+      meterName: "o11y",
+      metricName: "o11y_pii_redaction",
+    });
+
+    expect(metric1).toBe(mockMetric);
+    expect(metric2).toBe(mockMetric); // should be cached
+  });
+});

package/test/node-config.test.ts

@@ -1,18 +1,20 @@
-import { test, describe, assert, expect } from "vitest";
-import buildNodeInstrumentation from "../lib/instrumentation.node.js";
 import { NodeSDK, metrics } from "@opentelemetry/sdk-node";
+import { afterAll, assert, describe, expect, test } from "vitest";
+import buildNodeInstrumentation from "../lib/instrumentation.node.js";
 
-import { NodeSDKConfig } from "../lib/index.js";
-import buildHttpExporters from "../lib/exporter/http.js";
-import {
-  BatchSpanProcessor,
-  SimpleSpanProcessor,
-} from "@opentelemetry/sdk-trace-base";
 import {
   BatchLogRecordProcessor,
   SimpleLogRecordProcessor,
 } from "@opentelemetry/sdk-logs";
+import {
+  BatchSpanProcessor,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import buildHttpExporters from "../lib/exporter/http.js";
+import { NodeSDKConfig } from "../lib/index.js";
+import { EnrichLogProcessor } from "../lib/processor/enrich-logger-processor.js";
 import { EnrichSpanProcessor } from "../lib/processor/enrich-span-processor.js";
+import { PIIExporterDecorator } from "../lib/exporter/pii-exporter-decorator.js";
 
 describe("verify config settings", () => {
   const commonConfig = {
@@ -37,14 +39,13 @@ describe("verify config settings", () => {
 
     const logs = _configuration.logRecordProcessors;
 
-    assert.equal(logs.length, 2);
-    assert.ok(logs[1] instanceof BatchLogRecordProcessor);
+    assert.equal(logs.length, 1);
+    assert.ok(logs[logs.length - 1] instanceof BatchLogRecordProcessor);
 
     const spans = _configuration.spanProcessors;
 
-    assert.equal(spans.length, 2);
+    assert.equal(spans.length, 1);
     assert.ok(spans[0] instanceof BatchSpanProcessor);
-    assert.ok(spans[1] instanceof EnrichSpanProcessor);
 
     assert.ok(
       _configuration.metricReader instanceof
@@ -57,6 +58,9 @@ describe("verify config settings", () => {
       ...commonConfig,
       protocol: "http",
       diagLogLevel: "NONE",
+      spanAttributes: {
+        name: "custom-value",
+      },
     };
 
     const sdk: NodeSDK | undefined = await buildNodeInstrumentation(config);
@@ -68,6 +72,7 @@ describe("verify config settings", () => {
     const logs = _configuration.logRecordProcessors;
 
     assert.equal(logs.length, 2);
+    assert.ok(logs[0] instanceof EnrichLogProcessor);
     assert.ok(logs[1] instanceof BatchLogRecordProcessor);
 
     const spans = _configuration.spanProcessors;
@@ -87,6 +92,9 @@ describe("verify config settings", () => {
       ...commonConfig,
       protocol: "console",
       diagLogLevel: "NONE",
+      spanAttributes: {
+        name: "custom-name",
+      },
     };
 
     const sdk: NodeSDK = await buildNodeInstrumentation(config)!;
@@ -99,6 +107,7 @@ describe("verify config settings", () => {
 
     // verify simple log processor for instant console logging
     assert.equal(logs.length, 2);
+    assert.ok(logs[0] instanceof EnrichLogProcessor);
     assert.ok(logs[1] instanceof SimpleLogRecordProcessor);
 
     const spans = _configuration.spanProcessors;
@@ -129,8 +138,39 @@ describe("verify config settings", () => {
     const _configuration = sdk["_configuration"];
 
     const logRecordProcessors = _configuration.logRecordProcessors;
-    assert.equal(logRecordProcessors.length, 2);
-    assert.ok(logRecordProcessors[1] instanceof SimpleLogRecordProcessor);
+    assert.equal(logRecordProcessors.length, 1);
+    assert.ok(
+      logRecordProcessors[logRecordProcessors.length - 1] instanceof
+        SimpleLogRecordProcessor,
+    );
+  });
+
+  test("pii exporter decorator injected by default", async () => {
+    const config: NodeSDKConfig = {
+      ...commonConfig,
+      protocol: "grpc",
+      diagLogLevel: "NONE",
+      collectorMode: "single",
+      detection: {},
+    };
+
+    const sdk: NodeSDK | undefined = await buildNodeInstrumentation(config);
+
+    assert.ok(sdk);
+
+    const _configuration = sdk["_configuration"];
+
+    const logRecordProcessors = _configuration.logRecordProcessors;
+    assert.equal(logRecordProcessors.length, 1);
+    assert.ok(
+      logRecordProcessors[logRecordProcessors.length - 1] instanceof
+        SimpleLogRecordProcessor,
+    );
+    assert.ok(
+      logRecordProcessors[logRecordProcessors.length - 1][
+        "_exporter"
+      ] instanceof PIIExporterDecorator,
+    );
   });
 
   test("check if clear base endpoint final slash", () => {
@@ -142,4 +182,9 @@ describe("verify config settings", () => {
 
     expect(config.collectorUrl).toBe("http://example.com");
   });
+
+  afterAll(() => {
+    // shutdown every instrumentation
+    process.emit("SIGTERM");
+  });
 });

package/test/processor/enrich-span-processor.test.ts

@@ -1,59 +1,7 @@
-import {
-  AttributeValue,
-  Context,
-  Exception,
-  Link,
-  Span,
-  SpanAttributes,
-  SpanContext,
-  SpanStatus,
-  TimeInput,
-} from "@opentelemetry/api";
+import { Context } from "@opentelemetry/api";
 import { describe, expect, it } from "vitest";
 import { EnrichSpanProcessor } from "../../lib/processor/enrich-span-processor.js";
-
-class MockSpan implements Span {
-  public attributes: Record<string, AttributeValue> = {};
-
-  spanContext(): SpanContext {
-    throw new Error("Method not implemented.");
-  }
-  setAttribute(key: string, value: AttributeValue): this {
-    this.attributes[key] = value;
-    return this;
-  }
-  setAttributes(attributes: SpanAttributes): this {
-    throw new Error("Method not implemented.");
-  }
-  addEvent(
-    name: string,
-    attributesOrStartTime?: SpanAttributes | TimeInput,
-    startTime?: TimeInput,
-  ): this {
-    throw new Error("Method not implemented.");
-  }
-  addLink(link: Link): this {
-    throw new Error("Method not implemented.");
-  }
-  addLinks(links: Link[]): this {
-    throw new Error("Method not implemented.");
-  }
-  setStatus(status: SpanStatus): this {
-    throw new Error("Method not implemented.");
-  }
-  updateName(name: string): this {
-    throw new Error("Method not implemented.");
-  }
-  end(endTime?: TimeInput): void {
-    throw new Error("Method not implemented.");
-  }
-  isRecording(): boolean {
-    throw new Error("Method not implemented.");
-  }
-  recordException(exception: Exception, time?: TimeInput): void {
-    throw new Error("Method not implemented.");
-  }
-}
+import { MockSpan } from "../utils/mock-signals.js";
 
 describe("EnrichSpanProcessor", () => {
   it("should set static attributes on span", () => {

package/test/traces/active-span.test.ts

@@ -0,0 +1,28 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import * as piiDetection from "../../lib/internals/pii-detection.js";
+import { getActiveSpan } from "../../lib/traces.js";
+import { MockSpan } from "../utils/mock-signals.js";
+import { setNodeSdkConfig } from "../../lib/config-manager.js";
+
+describe("getActiveSpan", () => {
+  it("returns undefined if no active span", async () => {
+    setNodeSdkConfig({
+      serviceName: "unit-test",
+      collectorUrl: "http://collector",
+      detection: {
+        email: false,
+      },
+    });
+
+    // Temporarily override
+    const opentelemetry = await import("@opentelemetry/api");
+
+    vi.spyOn(opentelemetry.trace, "getActiveSpan").mockImplementationOnce(
+      () => undefined,
+    );
+
+    const span = getActiveSpan();
+
+    expect(span).toBeUndefined();
+  });
+});