@ogcio/o11y-sdk-node 0.1.0-beta.4 → 0.1.0-beta.6

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## [0.1.0-beta.4](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.1.0-beta.3...@ogcio/o11y-sdk-node@v0.1.0-beta.4) (2025-01-28)
+## [0.1.0-beta.6](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.1.0-beta.5...@ogcio/o11y-sdk-node@v0.1.0-beta.6) (2025-02-06)
+
+
+### Features
+
+* remove pnpm test on prepublishOnly script ([#68](https://github.com/ogcio/o11y/issues/68)) ([41f6f57](https://github.com/ogcio/o11y/commit/41f6f57fa415c4f7adc29f49f983539274ef7320))
+
+## [0.1.0-beta.5](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.1.0-beta.4...@ogcio/o11y-sdk-node@v0.1.0-beta.5) (2025-02-06)
+
+
+### Features
+
+* add opentelemetry sampler ([#65](https://github.com/ogcio/o11y/issues/65)) ([66793fd](https://github.com/ogcio/o11y/commit/66793fd36bf071e592e3b455f2e33ad9d5b2db37))
+
+## [0.1.0-beta.4](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.1.0-beta.3...@ogcio/o11y-sdk-node@v0.1.0-beta.4) (2025-01-29)
 
 
 ### Bug Fixes

package/dist/lib/index.d.ts

@@ -25,6 +25,13 @@ interface SDKConfig {
      * @default batch
      */
     collectorMode?: SDKCollectorMode;
+    /**
+     * Array of not traced urls.
+     *
+     * @type {SamplerCondition}
+     * @default []
+     */
+    ignoreUrls?: SamplerCondition[];
 }
 export interface NodeSDKConfig extends SDKConfig {
     /**
@@ -40,6 +47,10 @@ export interface NodeSDKConfig extends SDKConfig {
      */
     protocol?: SDKProtocol;
 }
+export interface SamplerCondition {
+    type: "endsWith" | "includes" | "equals";
+    url: string;
+}
 export type SDKCollectorMode = "single" | "batch";
 export type SDKProtocol = "grpc" | "http" | "console";
 export type SDKLogLevel = "NONE" | "ERROR" | "WARN" | "INFO" | "DEBUG" | "VERBOSE" | "ALL";

package/dist/lib/instrumentation.node.js

@@ -1,5 +1,4 @@
 import { NodeSDK, resources } from "@opentelemetry/sdk-node";
-import isUrl from "is-url";
 import buildHttpExporters from "./http.js";
 import buildGrpcExporters from "./grpc.js";
 import buildConsoleExporters from "./console.js";
@@ -7,6 +6,7 @@ import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import packageJson from "../package.json" with { type: "json" };
+import { UrlSampler } from "./url-sampler.js";
 export default function buildNodeInstrumentation(config) {
     if (!config) {
         console.warn("observability config not set. Skipping NodeJS OpenTelemetry instrumentation.");
@@ -43,6 +43,7 @@ export default function buildNodeInstrumentation(config) {
             traceExporter: exporter.traces,
             metricReader: exporter.metrics,
             logRecordProcessors: exporter.logs,
+            sampler: new UrlSampler(config.ignoreUrls),
             textMapPropagator: new W3CTraceContextPropagator(),
             instrumentations: [
                 getNodeAutoInstrumentations({
@@ -60,3 +61,13 @@ export default function buildNodeInstrumentation(config) {
         console.error("Error starting NodeJS OpenTelemetry instrumentation:", error);
     }
 }
+function isUrl(url) {
+    try {
+        new URL(url);
+        return true;
+    }
+    catch (err) {
+        console.error(err);
+        return false;
+    }
+}

package/dist/lib/url-sampler.d.ts

@@ -0,0 +1,9 @@
+import { Context, SpanKind, Link, Attributes } from "@opentelemetry/api";
+import { Sampler, SamplingResult } from "@opentelemetry/sdk-trace-base";
+import { SamplerCondition } from "./index.js";
+export declare class UrlSampler implements Sampler {
+    private _samplerCondition;
+    constructor(samplerCondition?: SamplerCondition[]);
+    shouldSample(_context: Context, traceId: string, _spanName: string, _spanKind: SpanKind, attributes: Attributes, _links: Link[]): SamplingResult;
+    toString(): string;
+}

package/dist/lib/url-sampler.js

@@ -0,0 +1,28 @@
+import { isValidTraceId, } from "@opentelemetry/api";
+import { SamplingDecision, } from "@opentelemetry/sdk-trace-base";
+export class UrlSampler {
+    _samplerCondition;
+    constructor(samplerCondition = []) {
+        this._samplerCondition = samplerCondition;
+    }
+    shouldSample(_context, traceId, _spanName, _spanKind, attributes, _links) {
+        const url = 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 {
+            decision: isValidTraceId(traceId)
+                ? SamplingDecision.RECORD_AND_SAMPLED
+                : SamplingDecision.NOT_RECORD,
+        };
+    }
+    toString() {
+        throw "UrlSampler";
+    }
+}

package/dist/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@ogcio/o11y-sdk-node",
-    "version": "0.1.0-beta.4",
+    "version": "0.1.0-beta.6",
     "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
     "main": "dist/index.js",
     "type": "module",
     "scripts": {
         "build": "rm -rf dist && tsc -p tsconfig.json",
         "test": "vitest",
-        "prepublishOnly": "pnpm i && pnpm build && pnpm test"
+        "prepublishOnly": "pnpm i && pnpm build"
     },
     "exports": {
         ".": "./dist/index.js",
@@ -25,7 +25,7 @@
     "license": "ISC",
     "dependencies": {
         "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/auto-instrumentations-node": "^0.55.3",
+        "@opentelemetry/auto-instrumentations-node": "^0.56.0",
         "@opentelemetry/core": "1.30.1",
         "@opentelemetry/exporter-logs-otlp-grpc": "^0.57.1",
         "@opentelemetry/exporter-logs-otlp-http": "^0.57.1",
@@ -37,10 +37,9 @@
         "@opentelemetry/otlp-exporter-base": "^0.57.1",
         "@opentelemetry/sdk-metrics": "^1.30.1",
         "@opentelemetry/sdk-node": "^0.57.1",
-        "is-url": "^1.2.4"
+        "@opentelemetry/sdk-trace-base": "^1.30.1"
     },
     "devDependencies": {
-        "@types/is-url": "^1.2.32",
         "@types/node": "^22.12.0",
         "@vitest/coverage-v8": "^3.0.4",
         "tsx": "^4.19.2",

package/dist/vitest.config.js

@@ -3,7 +3,7 @@ export default defineConfig({
     test: {
         globals: true,
         watch: false,
-        include: ["**/test/*.test.ts"],
+        include: ["**/test/*.test.ts", "**/test/integration/*.test.ts"],
         exclude: ["**/fixtures/**", "**/dist/**"],
         poolOptions: {
             threads: {

package/lib/index.ts

@@ -25,6 +25,13 @@ interface SDKConfig {
    * @default batch
    */
   collectorMode?: SDKCollectorMode;
+  /**
+   * Array of not traced urls.
+   *
+   * @type {SamplerCondition}
+   * @default []
+   */
+  ignoreUrls?: SamplerCondition[];
 }
 
 export interface NodeSDKConfig extends SDKConfig {
@@ -43,6 +50,11 @@ export interface NodeSDKConfig extends SDKConfig {
   protocol?: SDKProtocol;
 }
 
+export interface SamplerCondition {
+  type: "endsWith" | "includes" | "equals";
+  url: string;
+}
+
 export type SDKCollectorMode = "single" | "batch";
 
 export type SDKProtocol = "grpc" | "http" | "console";

package/lib/instrumentation.node.ts

@@ -1,7 +1,6 @@
 import { NodeSDK, resources } from "@opentelemetry/sdk-node";
 import type { NodeSDKConfig } from "./index.js";
 import type { Exporters } from "./options.js";
-import isUrl from "is-url";
 import buildHttpExporters from "./http.js";
 import buildGrpcExporters from "./grpc.js";
 import buildConsoleExporters from "./console.js";
@@ -9,6 +8,7 @@ import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import packageJson from "../package.json" with { type: "json" };
+import { UrlSampler } from "./url-sampler.js";
 
 export default function buildNodeInstrumentation(
   config?: NodeSDKConfig,
@@ -61,6 +61,7 @@ export default function buildNodeInstrumentation(
       traceExporter: exporter.traces,
       metricReader: exporter.metrics,
       logRecordProcessors: exporter.logs,
+      sampler: new UrlSampler(config.ignoreUrls),
       textMapPropagator: new W3CTraceContextPropagator(),
       instrumentations: [
         getNodeAutoInstrumentations({
@@ -81,3 +82,13 @@ export default function buildNodeInstrumentation(
     );
   }
 }
+
+function isUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch (err) {
+    console.error(err);
+    return false;
+  }
+}

package/lib/url-sampler.ts

@@ -0,0 +1,53 @@
+import {
+  Context,
+  SpanKind,
+  Link,
+  Attributes,
+  isValidTraceId,
+} 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[];
+
+  constructor(samplerCondition: SamplerCondition[] = []) {
+    this._samplerCondition = samplerCondition;
+  }
+
+  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 {
+      decision: isValidTraceId(traceId)
+        ? SamplingDecision.RECORD_AND_SAMPLED
+        : SamplingDecision.NOT_RECORD,
+    };
+  }
+  toString(): string {
+    throw "UrlSampler";
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogcio/o11y-sdk-node",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
@@ -20,7 +20,7 @@
   "license": "ISC",
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.55.3",
+    "@opentelemetry/auto-instrumentations-node": "^0.56.0",
     "@opentelemetry/core": "1.30.1",
     "@opentelemetry/exporter-logs-otlp-grpc": "^0.57.1",
     "@opentelemetry/exporter-logs-otlp-http": "^0.57.1",
@@ -32,10 +32,9 @@
     "@opentelemetry/otlp-exporter-base": "^0.57.1",
     "@opentelemetry/sdk-metrics": "^1.30.1",
     "@opentelemetry/sdk-node": "^0.57.1",
-    "is-url": "^1.2.4"
+    "@opentelemetry/sdk-trace-base": "^1.30.1"
   },
   "devDependencies": {
-    "@types/is-url": "^1.2.32",
     "@types/node": "^22.12.0",
     "@vitest/coverage-v8": "^3.0.4",
     "tsx": "^4.19.2",

package/test/integration/README.md

@@ -0,0 +1,26 @@
+# 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
+- persit 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/integration.test.ts

@@ -0,0 +1,37 @@
+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;
+
+    console.log(data.split(/\nts=/).length);
+
+    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++;
+          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/run.sh

@@ -0,0 +1,85 @@
+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 \
+    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 \
+        --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
+    sleep 2
+    curl -X GET -f http://localhost:9091/api/dummy
+fi
+
+# sleep N seconds to await instrumentation flow send and receiving signals
+sleep 10
+
+# 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/utils/alloy-log-parser.ts

@@ -0,0 +1,46 @@
+export function parseLog(
+  log: string,
+): Record<string, object | string | number> {
+  const logArray = log
+    .split("\\n")
+    .map((line) => line.trim())
+    .filter((line) => line);
+
+  const jsonObject: Record<string, object | string | number> = {};
+  let currentSection: Record<string, object | string | number> = jsonObject;
+  const sectionStack: Record<string, object | string | number>[] = [];
+
+  logArray.forEach((line) => {
+    line = line.trim();
+
+    if (line.startsWith("->")) {
+      const match = line.match(/->\s+([^:]+):\s+(Str|Int)\((.+)\)/);
+      if (match) {
+        const [, key, type, value] = match;
+        const parsedValue = type === "Int" ? parseInt(value, 10) : value;
+
+        if (typeof currentSection === "object") {
+          currentSection[key] = parsedValue;
+        }
+      }
+    } else if (line.endsWith(":")) {
+      // new section
+      const sectionName = line
+        .slice(0, -1)
+        .trim()
+        .toLowerCase()
+        .replace(" ", "_");
+      jsonObject[sectionName] = {};
+      currentSection = jsonObject[sectionName] as Record<
+        string,
+        object | string | number
+      >;
+      sectionStack.push(currentSection);
+    } else if (line.startsWith('"')) {
+      // Additional metadata at the end, store it separately
+      jsonObject["metadata"] = line;
+    }
+  });
+
+  return jsonObject;
+}

package/vitest.config.ts

@@ -4,7 +4,7 @@ export default defineConfig({
   test: {
     globals: true,
     watch: false,
-    include: ["**/test/*.test.ts"],
+    include: ["**/test/*.test.ts", "**/test/integration/*.test.ts"],
     exclude: ["**/fixtures/**", "**/dist/**"],
     poolOptions: {
       threads: {