@ogcio/o11y-sdk-node 0.4.2 → 0.6.1

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("does not throw if getConfig is called before initialization", () => {
-    expect(() => getNodeSdkConfig()).not.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,74 +0,0 @@
-# Integration Test Runner
-
-This script is a **Bash-based test runner** that discovers and executes integration test scripts for the Node SDK (`./packages/sdk-node/test/integration`).  
-It ensures tests run inside an isolated Docker network and provides a summary of results.
-
----
-
-## Usage
-
-```bash
-./run-tests.sh <build-id> <root-path> <is-ci?>
-```
-
-**Arguments**
-
-<build-id>
-A unique identifier for the test run. Used to name the Docker network (<build-id>_testnetwork).
-
-<root-path>
-The root path for the project or build environment.
-
-[ci-flag] (optional)
-Defaults to false.
-If set to true, the script will remove all Docker images after the tests complete (intended for CI pipelines to save disk space).
-
-## How It Works
-
-- Ensures at least two arguments are provided. Exits with usage instructions otherwise.
-- Creates a temporary Docker network named <build-id>\_testnetwork.
-- Finds all integration test scripts under: ./packages/sdk-node/test/integration/test\*/run.sh
-- Runs each test script.
-- Captures exit codes and tracks failures.
-- Prints results per test.
-- Removes the Docker network after all tests finish.
-- If running in CI mode (ci-flag = true), removes all Docker images.
-- Reports whether all tests passed or how many failed.
-  Exits with:
-  - 0 if all tests succeeded
-  - 1 if one or more tests failed
-
-**Example**
-
-```
-# Run tests locally
-./run-tests.sh my-build-id /path/to/project
-
-# Run tests in CI mode (cleanup Docker images after)
-./run-tests.sh my-build-id /path/to/project true
-```
-
-## Tests
-
-### test_fastify-o11y-pii-enabled
-
-The `run.sh` script performs the following steps:
-
-- build a docker image of a fastify app `/examples/fastify`
-- 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/`
-- verify pii data are removed and metrics are increased
-- docker turn down process (containers/network/image)
-
-### test_without-o11y
-
-The `run.sh` script performs the following steps:
-
-- build a docker image of a fastify app `/examples/fastify`
-- verify service execution with o11y sdk disabled (otel collector empty)
-- execute http requests for dummy route with otel trace customization function calls
-- assert 200 http status without any error

package/test/integration/docker-utils.sh

@@ -1,214 +0,0 @@
-#!/bin/bash
-
-: '
-Build a new docker image of a given Dockerfile, if already exists skip build.
-
-@param container_name docker container name
-
-@return int error code
-0. success
-1. validation error
-'
-build_image() {
-    if [ "$#" -lt 3 ] || [ "$#" -gt 4 ]; then
-        echo "Error: build_image expected 3 or 4 parameters, got $#." >&2
-        echo "Usage: build_image <image_name> <dockerfile_path> <context_path> [max_age_minutes]" >&2
-        return 1
-    fi
-    
-    
-    local image_name="$1"
-    local dockerfile_path="$2"
-    local context_path="$3"
-    local max_age_minutes="${4:-30}"  # default threshold = 30 minutes
-    
-    if docker image inspect "$image_name" > /dev/null 2>&1; then
-        echo "Image $image_name already exists. Checking age..."
-        
-        # Extract the Created timestamp from docker inspect (ISO 8601 format)
-        local created_at
-        created_at=$(docker image inspect --format '{{.Created}}' "$image_name")
-        if [ -z "$created_at" ]; then
-            echo "Warning: Could not determine creation date. Proceeding without rebuild check." >&2
-            return 0
-        fi
-        
-        # Convert created_at to epoch seconds
-        local created_epoch
-        created_epoch=$(date -d "$created_at" +%s 2>/dev/null)
-        
-        # Current time in epoch seconds
-        local now_epoch
-        now_epoch=$(date +%s)
-        
-        # Calculate age in minutes
-        local age_minutes=$(( (now_epoch - created_epoch) / 60 ))
-        
-        echo "Image $image_name is $age_minutes minutes old (threshold: $max_age_minutes minutes)."
-        
-        if [ "$age_minutes" -ge "$max_age_minutes" ]; then
-            echo "Image is too old. Rebuilding..."
-            docker build -t $image_name -f $dockerfile_path $context_path
-            return $?
-        else
-            echo "Image is recent. Skipping rebuild."
-            return 0
-        fi
-    else
-        echo "Image $image_name not found. Building..."
-        docker build -t "$image_name" -f "$dockerfile_path" "$context_path"
-        return $?
-    fi
-}
-
-: '
-Stop and remove a docker container for the given input container name.
-
-@param container_name docker container name
-
-@return int error code
-0. success
-1. validation error
-'
-container_stop_and_rm() {
-    local container_name="$1"
-    
-    if [[ -z "$container_name" ]]; then
-        echo "Error: container_name must have a value."
-        return 1
-    fi
-    
-    docker container stop $container_name
-    docker container rm -f $container_name
-    
-    return $?
-}
-
-: '
-Run a new alloy container and check if the status is running.
-
-@param root_path volume root path for alloy file config
-@param network_name docker network name
-@param container_name docker container name
-
-@optional max_retries
-@default 10
-
-@return int error code
-0. success
-1. validation error
-2. execution failed
-'
-run_and_check_alloy() {
-    
-    if [ "$#" -lt 3 ]; then
-        echo "Error: run_and_check_alloy expected 3 parameters, got $#." >&2
-        return 1
-    fi
-    
-    local root_path="$1"
-    local network_name="$2"
-    local container_name="$3"
-    local max_retries="${4:-10}"
-    local counter_retries=0
-    
-    if [[ -z "$root_path" || -z "$network_name" || -z "$container_name" ]]; then
-        echo "Error: root_path, network_name, and container_name must all have values."
-        return 1
-    fi
-    
-    if ! [[ "$max_retries" =~ ^[0-9]+$ ]]; then
-        echo "Error: max_retries parameter must be a number." >&2
-        return 1
-    fi
-    
-    docker run -d \
-    -v "$root_path/alloy/integration-test.alloy:/etc/alloy/config.alloy:ro" \
-    --network $network_name \
-    --name $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
-    
-    echo "$container_name container status"
-    until [ "$(docker inspect -f {{.State.Running}} $container_name)" = true ]; do
-        sleep 2
-        docker inspect -f {{.State.Running}} $container_name
-        counter_retries=$((counter_retries + 1))
-        if [ $counter_retries -ge $max_retries ]; then
-            echo "Exceeded maximum retries. Exiting."
-            return 2
-        fi
-    done
-    
-    return 0
-}
-
-: '
-Run a new fastify microservice container and check if the status is running.
-
-@param network_name docker network name
-@param collector_url otel collector grpc endpoint
-@param container_name docker container name
-@param build_id current pipeline build id
-
-@optional max_retries
-@default 10
-
-@return int error code
-0. success
-1. validation error
-2. execution failed
-'
-run_and_check_fastify() {
-    
-    if [ "$#" -lt 4 ]; then
-        echo "Error: run_and_check_alloy expected 3 parameters, got $#." >&2
-        return 1
-    fi
-    
-    local network_name="$1"
-    local collector_url="$2"
-    local container_name="$3"
-    local build_id="$4"
-    local max_retries="${5:-10}"
-    local counter_retries=0
-    
-    if [[ -z "$build_id" || -z "$network_name" || -z "$container_name" ]]; then
-        echo "Error: build_id, network_name, and container_name must all have values."
-        return 1
-    fi
-    
-    if ! [[ "$max_retries" =~ ^[0-9]+$ ]]; then
-        echo "Error: max_retries parameter must be a number." >&2
-        return 1
-    fi
-    
-    docker run --detach \
-    --network $network_name \
-    --name $container_name \
-    -e DB_DISABLED="true" \
-    -e SERVER_HOST="0.0.0.0" \
-    -e OTEL_COLLECTOR_URL=$collector_url \
-    --health-cmd="curl -f http://${container_name}:9091/api/health > /dev/null || exit 1" \
-    --health-start-period=1s \
-    --health-retries=10 \
-    --health-interval=1s \
-    -p 9091:9091 \
-    $container_name:$build_id
-    
-    counter_retries=0
-    echo "$container_name container status"
-    until [ "$(docker inspect -f {{.State.Health.Status}} $container_name)" = "healthy" ]; do
-        sleep 1
-        docker inspect -f {{.State.Health.Status}} $container_name
-        counter_retries=$((counter_retries + 1))
-        if [ $counter_retries -ge $max_retries ]; then
-            echo "Exceeded maximum retries. Exiting."
-            return 2
-        fi
-    done
-    
-    return 0
-}