@ogcio/o11y-sdk-node 0.4.1 → 0.6.0

package/lib/resource.ts

@@ -1,30 +0,0 @@
-import {
-  ResourceDetector,
-  DetectedResource,
-  DetectedResourceAttributes,
-} from "@opentelemetry/resources";
-import { SignalAttributeValue } from "./index.js";
-import packageJson from "../package.json" with { type: "json" };
-
-export class ObservabilityResourceDetector implements ResourceDetector {
-  private _resourceAttributes: Record<string, SignalAttributeValue> | undefined;
-
-  constructor(resourceAttributes?: Record<string, SignalAttributeValue>) {
-    this._resourceAttributes = resourceAttributes;
-  }
-
-  detect(): DetectedResource {
-    let attributes: DetectedResourceAttributes = {};
-
-    if (this._resourceAttributes) {
-      attributes = {
-        ...this._resourceAttributes,
-      };
-    }
-
-    attributes["o11y.sdk.name"] = packageJson.name;
-    attributes["o11y.sdk.version"] = packageJson.version;
-
-    return { attributes };
-  }
-}

package/lib/traces.ts

@@ -1,78 +0,0 @@
-import { Span, SpanOptions, SpanStatusCode, trace } from "@opentelemetry/api";
-import { getNodeSdkConfig } from "./config-manager.js";
-
-export type WithSpanParams<T> = {
-  /**
-   * The name of the trace the span should belong to.
-   * NOTE: If you want the new span to belong to an already existing trace, you should provide the same tracer name
-   */
-  traceName?: string;
-  spanName: string;
-  spanOptions?: SpanOptions;
-  /** A function defining the task you want to be wrapped by this span */
-  fn: (span: Span) => T | Promise<T>;
-};
-
-/**
- * Generates a function wrapping a given Callable `fn` into an error handling block.
- * Setting Span status and recording any caught exception before bubbling it up.
- *
- * Marks the span as ended once the provided callable has ended or an error has been caught.
- *
- * @returns {Promise<T>} where T is the type returned by the Callable.
- * @throws any error thrown by the original Callable `fn` provided.
- */
-function selfContainedSpanHandlerGenerator<T>(
-  fn: (span: Span) => T | Promise<T>,
-): (span: Span) => Promise<T> {
-  return async (span: Span) => {
-    try {
-      const fnResult = await fn(span);
-      span.setStatus({ code: SpanStatusCode.OK });
-      return fnResult;
-    } catch (err) {
-      if (err instanceof Error) {
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-        throw err;
-      }
-
-      span.recordException({ message: JSON.stringify(err) });
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: JSON.stringify(err),
-      });
-      throw err;
-    } finally {
-      span.end();
-    }
-  };
-}
-
-/**
- * Gets the currently active OpenTelemetry span.
- *
- * @returns {Span | undefined} The active span with redaction logic applied,
- * or `undefined` if there is no active span in context.
- */
-export function getActiveSpan() {
-  return trace.getActiveSpan();
-}
-
-export function withSpan<T>({
-  traceName,
-  spanName,
-  spanOptions = {},
-  fn,
-}: WithSpanParams<T>) {
-  const sdkConfig = getNodeSdkConfig();
-  const tracer = trace.getTracer(
-    traceName ?? sdkConfig.serviceName ?? "o11y-sdk",
-    sdkConfig.serviceVersion,
-  );
-  return tracer.startActiveSpan(
-    spanName,
-    spanOptions,
-    selfContainedSpanHandlerGenerator<T>(fn),
-  );
-}

package/lib/url-sampler.ts

@@ -1,52 +0,0 @@
-import { Attributes, Context, Link, SpanKind } from "@opentelemetry/api";
-import {
-  Sampler,
-  SamplingDecision,
-  SamplingResult,
-} from "@opentelemetry/sdk-trace-base";
-import { SamplerCondition } from "./index.js";
-
-export class UrlSampler implements Sampler {
-  private _samplerCondition: SamplerCondition[];
-  private _nextSampler: Sampler;
-
-  constructor(samplerCondition: SamplerCondition[] = [], nextSampler: Sampler) {
-    this._samplerCondition = samplerCondition;
-    this._nextSampler = nextSampler;
-  }
-
-  shouldSample(
-    _context: Context,
-    traceId: string,
-    _spanName: string,
-    _spanKind: SpanKind,
-    attributes: Attributes,
-    _links: Link[],
-  ): SamplingResult {
-    const url: string | undefined = attributes["http.target"]?.toString();
-
-    if (url) {
-      for (const condition of this._samplerCondition) {
-        if (
-          (condition.type === "equals" && url === condition.url) ||
-          (condition.type === "endsWith" && url.endsWith(condition.url)) ||
-          (condition.type === "includes" && url.includes(condition.url))
-        ) {
-          return { decision: SamplingDecision.NOT_RECORD };
-        }
-      }
-    }
-
-    return this._nextSampler.shouldSample(
-      _context,
-      traceId,
-      _spanName,
-      _spanKind,
-      attributes,
-      _links,
-    );
-  }
-  toString(): string {
-    return "UrlSampler";
-  }
-}

package/lib/utils.ts

@@ -1,22 +0,0 @@
-import {
-  BatchLogRecordProcessor,
-  SimpleLogRecordProcessor,
-} from "@opentelemetry/sdk-logs";
-import { SDKCollectorMode } from "./index.js";
-import { tracing } from "@opentelemetry/sdk-node";
-
-export const LogRecordProcessorMap: Record<
-  SDKCollectorMode,
-  typeof SimpleLogRecordProcessor | typeof BatchLogRecordProcessor
-> = {
-  single: SimpleLogRecordProcessor,
-  batch: BatchLogRecordProcessor,
-};
-
-export const SpanProcessorMap: Record<
-  SDKCollectorMode,
-  typeof tracing.SimpleSpanProcessor | typeof tracing.BatchSpanProcessor
-> = {
-  single: tracing.SimpleSpanProcessor,
-  batch: tracing.BatchSpanProcessor,
-};

package/test/config-manager.test.ts

@@ -1,34 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { getNodeSdkConfig, setNodeSdkConfig } from "../lib/config-manager";
-import { NodeSDKConfig } from "../lib";
-
-describe("Config Manager", () => {
-  it("throws if getConfig is called before initialization", () => {
-    expect(() => getNodeSdkConfig()).toThrow();
-  });
-
-  it("sdk defined config is not pollutable", () => {
-    const config: NodeSDKConfig = {
-      collectorUrl: "http://example.com",
-      serviceName: "MyService",
-      spanAttributes: {
-        "my.attribute": "value",
-      },
-    };
-
-    setNodeSdkConfig(config);
-
-    const cfg = getNodeSdkConfig();
-
-    // Top level
-    cfg.collectorUrl = "http://example.com/changed";
-    // Subfield
-    cfg.spanAttributes["my.attribute"] = "another-attribute";
-
-    // Ensure config values remain unchanged
-    expect(getNodeSdkConfig().collectorUrl).toStrictEqual(config.collectorUrl);
-    expect(getNodeSdkConfig().spanAttributes["my.attribute"]).toStrictEqual(
-      config.spanAttributes["my.attribute"],
-    );
-  });
-});

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

@@ -1,88 +0,0 @@
-import { ReadableLogRecord } from "@opentelemetry/sdk-logs";
-import { ResourceMetrics } from "@opentelemetry/sdk-metrics";
-import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { PIIExporterDecorator } from "../../lib/exporter/pii-exporter-decorator";
-
-describe("PIIExporterDecorator", () => {
-  let exporterMock: any;
-  let config: any;
-  let piiExporter: PIIExporterDecorator;
-
-  beforeEach(() => {
-    exporterMock = {
-      export: vi.fn(),
-      shutdown: vi.fn(() => Promise.resolve()),
-      forceFlush: vi.fn(() => Promise.resolve()),
-      _delegate: {},
-    };
-
-    config = { detection: { email: true } };
-    piiExporter = new PIIExporterDecorator(exporterMock, config);
-  });
-
-  it("should redact emails in span name and attributes", () => {
-    const items: ReadableSpan[] = [
-      {
-        name: "user@example.com",
-        kind: 0,
-        spanContext: () => ({}),
-        attributes: { email: "user@example.com" },
-        resource: { attributes: { owner: "user@example.com" } },
-        events: [
-          {
-            name: "Login from user@example.com",
-            attributes: { email: "user@example.com" },
-          },
-        ],
-      } as any,
-    ];
-
-    const callback = vi.fn();
-    piiExporter.export(items, callback);
-
-    const exportedSpan = exporterMock.export.mock.calls[0][0][0];
-    expect(exportedSpan.name).toBe("[REDACTED EMAIL]");
-    expect(exportedSpan.attributes.email).toBe("[REDACTED EMAIL]");
-    expect(exportedSpan.resource.attributes.owner).toBe("[REDACTED EMAIL]");
-    expect(exportedSpan.events[0].name).toBe("Login from [REDACTED EMAIL]");
-    expect(exportedSpan.events[0].attributes.email).toBe("[REDACTED EMAIL]");
-  });
-
-  it("should redact emails in log records", () => {
-    const items: ReadableLogRecord[] = [
-      {
-        body: "Error from user@example.com",
-        attributes: { email: "user@example.com" },
-        severityText: "INFO",
-        severityNumber: 1,
-        resource: { attributes: { owner: "user@example.com" } },
-      } as any,
-    ];
-
-    const callback = vi.fn();
-    piiExporter.export(items, callback);
-
-    const exportedLog = exporterMock.export.mock.calls[0][0][0];
-    expect(exportedLog.body).toBe("Error from [REDACTED EMAIL]");
-    expect(exportedLog.attributes.email).toBe("[REDACTED EMAIL]");
-    expect(exportedLog.resource.attributes.owner).toBe("[REDACTED EMAIL]");
-  });
-
-  it("should redact emails in resource metrics", () => {
-    const metrics: ResourceMetrics = {
-      resource: {
-        attributes: { maintainer: "user@example.com" },
-      },
-      scopeMetrics: [],
-    } as any;
-
-    const callback = vi.fn();
-    piiExporter.export(metrics, callback);
-
-    const exportedMetric = exporterMock.export.mock.calls[0][0];
-    expect(exportedMetric.resource.attributes.maintainer).toBe(
-      "[REDACTED EMAIL]",
-    );
-  });
-});

package/test/index.test.ts

@@ -1,70 +0,0 @@
-import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { NodeSDKConfig } from "../index";
-import { instrumentNode } from "../index";
-import * as buildNodeInstrumentationModule from "../lib/instrumentation.node";
-import { metrics } from "@opentelemetry/sdk-node";
-
-describe("instrumentNode", () => {
-  beforeEach(() => {
-    // @ts-ignore Avoid actually running exporters at any time in tests (overriding private method)
-    vi.spyOn(
-      metrics.PeriodicExportingMetricReader.prototype,
-      "_doRun",
-    ).mockImplementation(vi.fn());
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  test("should call buildNodeInstrumentation with the provided config", async () => {
-    const instrumentationMock = vi
-      .spyOn(buildNodeInstrumentationModule, "default")
-      .mockImplementation(vi.fn());
-
-    const config: NodeSDKConfig = {
-      serviceName: "custom-service",
-      collectorUrl: "http://custom-collector.com",
-      protocol: "grpc",
-      resourceAttributes: {
-        "team.infra.cluster": "dev-01",
-        "team.infra.pod": "01",
-        "team.service.type": "fastify",
-      },
-      spanAttributes: {
-        "signal.namespace": "example",
-        "signal.number": () => "callback",
-      },
-    };
-
-    await instrumentNode(config);
-
-    expect(instrumentationMock).toHaveBeenCalledWith(config);
-  });
-
-  test("should not throw when called without arguments", async () => {
-    await expect(instrumentNode()).resolves.not.toThrow();
-  });
-
-  test("should invoke instrumentation shutdown on SIGTERM", async () => {
-    const config: NodeSDKConfig = {
-      serviceName: "custom-service",
-      collectorUrl: "http://custom-collector.com",
-      protocol: "grpc",
-      resourceAttributes: {
-        "team.infra.cluster": "dev-01",
-        "team.infra.pod": "01",
-        "team.service.type": "fastify",
-      },
-      spanAttributes: {
-        "signal.namespace": "example",
-        "signal.number": () => "callback",
-      },
-    };
-
-    const sdk = await instrumentNode(config);
-    const shutdownMock = vi.spyOn(sdk, "shutdown");
-    process.emit("SIGTERM");
-    expect(shutdownMock).toHaveBeenCalled();
-  });
-});

package/test/integration/README.md

@@ -1,26 +0,0 @@
-# Integration Test
-
-This folder contains a setup for integration test with o11y node sdk.
-
-## Workflow
-
-- Docker must be in running state
-- Run the sh script `sh ./packages/sdk-node/test/integration/run.sh 1 .` from project root with following params
-  1. pipeline build number, for local development, any number or string is fine
-  2. root folder for docker context
-- Change dir to `packages/sdk-node/`
-- Run full test suite with `pnpm test`
-
-## Script
-
-The `run.sh` script performs the following steps:
-
-- build a docker image of a fastify app `/examples/fastify`
-- setup an temporary test docker network
-- run grafana alloy inside a docker container with a test configuration `/alloy/integration-test.alloy`
-- ensure is running otherwise exit process
-- run fastify app in a docker container
-- ensure is running otherwise exit process
-- execute some curl to the fastify microservice
-- persist alloy log to a file and save to following path `/packages/sdk-node/test/integration/`
-- docker turn down process (containers/network/image)

package/test/integration/http-tracing.integration.test.ts

@@ -1,56 +0,0 @@
-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("instrumentation integration test", () => {
-  test("should exclude health url and process only dummy calls", async () => {
-    const data = await readFile(join(__dirname, "logs.txt"), "utf-8");
-
-    let health_traces_counter = 0;
-    let dummy_traces_counter = 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"] === "trace"
-      ) {
-        if (parsedLine["attributes"]["http.target"] === "/api/dummy") {
-          dummy_traces_counter++;
-
-          // verify global sdk span resource
-          assert.equal(
-            parsedLine["resource_attributes"]["team.infra.pod"],
-            "01",
-          );
-          assert.equal(
-            parsedLine["resource_attributes"]["team.service.type"],
-            "fastify",
-          );
-
-          // verify global sdk span attributes
-          assert.equal(parsedLine["attributes"]["signal.namespace"], "example");
-
-          // verify runtime custom span inside dev application
-          assert.equal(parsedLine["attributes"]["business.info"], "dummy");
-          assert.equal(
-            parsedLine["attributes"]["business.request_type"],
-            "application/json",
-          );
-
-          continue;
-        }
-        if (parsedLine["attributes"]["http.target"] === "/api/health") {
-          health_traces_counter++;
-        }
-      }
-    }
-
-    assert.equal(health_traces_counter, 0);
-    assert.equal(dummy_traces_counter, 2);
-  });
-});

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

@@ -1,68 +0,0 @@
-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

@@ -1,88 +0,0 @@
-BUILD_ID=$1
-ROOT_PATH=$2
-
-NETWORK_NAME="${BUILD_ID}_testnetwork"
-ALLOY_CONTAINER_NAME="integrationalloy"
-NODE_CONTAINER_NAME="${BUILD_ID}_fastify_app"
-ERROR_CODE=0
-
-docker build -t ${NODE_CONTAINER_NAME}:${BUILD_ID} -f $ROOT_PATH/examples/fastify/Dockerfile $ROOT_PATH/
-
-docker network create $NETWORK_NAME
-
-docker run -d \
-    -v "$ROOT_PATH/alloy/integration-test.alloy:/etc/alloy/config.alloy:ro" \
-    --network $NETWORK_NAME \
-    --name $ALLOY_CONTAINER_NAME \
-    -p 4317:4317 \
-    -p 4318:4318 \
-    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
-COUNTER=0
-echo "$ALLOY_CONTAINER_NAME container status"
-until [ "$(docker inspect -f {{.State.Running}} $ALLOY_CONTAINER_NAME)" = true ]; do
-    sleep 2
-    docker inspect -f {{.State.Running}} $ALLOY_CONTAINER_NAME
-    COUNTER=$((COUNTER + 1))
-    if [ $COUNTER -ge $MAX_RETRIES ]; then
-        echo "Exceeded maximum retries. Exiting."
-        ERROR_CODE=1
-        break
-    fi
-done
-
-if [[ $ERROR_CODE -eq 0 ]]; then
-    docker run --detach \
-        --network $NETWORK_NAME \
-        --name $NODE_CONTAINER_NAME \
-        -e DB_DISABLED="true" \
-        -e SERVER_HOST="0.0.0.0" \
-        -e OTEL_COLLECTOR_URL="http://integrationalloy:4317" \
-        --health-cmd="curl -f http://${NODE_CONTAINER_NAME}:9091/api/health > /dev/null || exit 1" \
-        --health-start-period=1s \
-        --health-retries=10 \
-        --health-interval=1s \
-        -p 9091:9091 \
-        ${NODE_CONTAINER_NAME}:${BUILD_ID}
-
-    COUNTER=0
-    echo "$NODE_CONTAINER_NAME container status"
-    until [ "$(docker inspect -f {{.State.Health.Status}} $NODE_CONTAINER_NAME)" = "healthy" ]; do
-        sleep 1
-        docker inspect -f {{.State.Health.Status}} $NODE_CONTAINER_NAME
-        COUNTER=$((COUNTER + 1))
-        if [ $COUNTER -ge $MAX_RETRIES ]; then
-            echo "Exceeded maximum retries. Exiting."
-            ERROR_CODE=1
-            break
-        fi
-    done
-fi
-
-if [[ $ERROR_CODE -eq 0 ]]; then
-    sleep 2
-    curl -X GET -f http://localhost:9091/api/dummy -H 'Content-Type: application/json'
-    sleep 2
-    curl -X GET -f http://localhost:9091/api/dummy -H 'Content-Type: application/json'
-fi
-
-# sleep N seconds to await instrumentation flow send and receiving signals
-sleep 1
-
-# Copy logs from container to file
-docker container logs $ALLOY_CONTAINER_NAME >&$ROOT_PATH/packages/sdk-node/test/integration/logs.txt
-echo "log file at $ROOT_PATH/packages/sdk-node/test/integration/logs.txt"
-
-docker container stop $ALLOY_CONTAINER_NAME
-docker container stop $NODE_CONTAINER_NAME
-
-docker container rm -f $ALLOY_CONTAINER_NAME
-docker container rm -f $NODE_CONTAINER_NAME
-
-docker image rm ${NODE_CONTAINER_NAME}:${BUILD_ID}
-
-docker network rm $NETWORK_NAME
-
-exit $ERROR_CODE

package/test/internals/hooks.test.ts

@@ -1,45 +0,0 @@
-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();
-  });
-});