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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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
+
+* prepublishOnly hook ([#60](https://github.com/ogcio/o11y/issues/60)) ([9fbd3ad](https://github.com/ogcio/o11y/commit/9fbd3ad0b45a1604cf2eccc26b2f8855640417a1))
+
 ## [0.1.0-beta.3](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@0.1.0-beta.2...@ogcio/o11y-sdk-node@v0.1.0-beta.3) (2025-01-28)
 
 

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { NodeSDK } from "@opentelemetry/sdk-node";
+import type { NodeSDKConfig } from "./lib/index.js";
+import buildNodeInstrumentation from "./lib/instrumentation.node.js";
+export type * from "./lib/index.js";
+export type { NodeSDKConfig, NodeSDK };
+export { buildNodeInstrumentation as instrumentNode };
+export * from "./lib/metrics.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+import buildNodeInstrumentation from "./lib/instrumentation.node.js";
+export { buildNodeInstrumentation as instrumentNode };
+export * from "./lib/metrics.js";

package/dist/lib/console.d.ts

@@ -0,0 +1,3 @@
+import type { NodeSDKConfig } from "./index.js";
+import type { Exporters } from "./options.js";
+export default function buildConsoleExporters(_: NodeSDKConfig): Exporters;

package/dist/lib/console.js

@@ -0,0 +1,12 @@
+import { logs, metrics, tracing } from "@opentelemetry/sdk-node";
+export default function buildConsoleExporters(_) {
+    return {
+        traces: new tracing.ConsoleSpanExporter(),
+        metrics: new metrics.PeriodicExportingMetricReader({
+            exporter: new metrics.ConsoleMetricExporter(),
+        }),
+        logs: [
+            new logs.SimpleLogRecordProcessor(new logs.ConsoleLogRecordExporter()),
+        ],
+    };
+}

package/dist/lib/grpc.d.ts

@@ -0,0 +1,3 @@
+import type { NodeSDKConfig } from "./index.js";
+import type { Exporters } from "./options.js";
+export default function buildGrpcExporters(config: NodeSDKConfig): Exporters;

package/dist/lib/grpc.js

@@ -0,0 +1,26 @@
+import { LogRecordProcessorMap } from "./utils.js";
+import { metrics } from "@opentelemetry/sdk-node";
+import { CompressionAlgorithm } from "@opentelemetry/otlp-exporter-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-grpc";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-grpc";
+export default function buildGrpcExporters(config) {
+    return {
+        traces: new OTLPTraceExporter({
+            url: `${config.collectorUrl}`,
+            compression: CompressionAlgorithm.GZIP,
+        }),
+        metrics: new metrics.PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({
+                url: `${config.collectorUrl}`,
+                compression: CompressionAlgorithm.GZIP,
+            }),
+        }),
+        logs: [
+            new LogRecordProcessorMap[config.collectorMode ?? "batch"](new OTLPLogExporter({
+                url: `${config.collectorUrl}`,
+                compression: CompressionAlgorithm.GZIP,
+            })),
+        ],
+    };
+}

package/dist/lib/http.d.ts

@@ -0,0 +1,3 @@
+import type { NodeSDKConfig } from "./index.js";
+import type { Exporters } from "./options.js";
+export default function buildHttpExporters(config: NodeSDKConfig): Exporters;

package/dist/lib/http.js

@@ -0,0 +1,29 @@
+import { LogRecordProcessorMap } from "./utils.js";
+import { metrics } from "@opentelemetry/sdk-node";
+import { CompressionAlgorithm } from "@opentelemetry/otlp-exporter-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+export default function buildHttpExporters(config) {
+    if (config.collectorUrl.endsWith("/")) {
+        config.collectorUrl = config.collectorUrl.slice(0, -1);
+    }
+    return {
+        traces: new OTLPTraceExporter({
+            url: `${config.collectorUrl}/v1/traces`,
+            compression: CompressionAlgorithm.GZIP,
+        }),
+        metrics: new metrics.PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({
+                url: `${config.collectorUrl}/v1/metrics`,
+                compression: CompressionAlgorithm.GZIP,
+            }),
+        }),
+        logs: [
+            new LogRecordProcessorMap[config.collectorMode ?? "batch"](new OTLPLogExporter({
+                url: `${config.collectorUrl}/v1/logs`,
+                compression: CompressionAlgorithm.GZIP,
+            })),
+        ],
+    };
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,57 @@
+interface SDKConfig {
+    /**
+     * The opentelemetry collector entrypoint GRPC url.
+     * If the collectoUrl is null or undefined, the instrumentation will not be activated.
+     * @example http://alloy:4317
+     */
+    collectorUrl: string;
+    /**
+     * Name of your application used for the collector to group logs
+     */
+    serviceName?: string;
+    /**
+     * Diagnostic log level for the internal runtime instrumentation
+     *
+     * @type string
+     * @default INFO
+     */
+    diagLogLevel?: SDKLogLevel;
+    /**
+     * Collector signals processing mode.
+     * signle: makes an http/grpc request for each signal and it is immediately processed inside grafana
+     * batch: sends multiple signals within a time window, optimized to reduce http/grpc calls in production
+     *
+     * @type string
+     * @default batch
+     */
+    collectorMode?: SDKCollectorMode;
+    /**
+     * Array of not traced urls.
+     *
+     * @type {SamplerCondition}
+     * @default []
+     */
+    ignoreUrls?: SamplerCondition[];
+}
+export interface NodeSDKConfig extends SDKConfig {
+    /**
+     * Flag to enable or disable the tracing for node:fs module
+     *
+     * @default false disabling `instrumentation-fs` because it bloating the traces
+     */
+    enableFS?: boolean;
+    /**
+     * protocol used to send signals.
+     *
+     * @default grpc
+     */
+    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";
+export {};

package/dist/lib/index.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/instrumentation.node.d.ts

@@ -0,0 +1,3 @@
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import type { NodeSDKConfig } from "./index.js";
+export default function buildNodeInstrumentation(config?: NodeSDKConfig): NodeSDK | undefined;

package/dist/lib/instrumentation.node.js

@@ -0,0 +1,73 @@
+import { NodeSDK, resources } from "@opentelemetry/sdk-node";
+import buildHttpExporters from "./http.js";
+import buildGrpcExporters from "./grpc.js";
+import buildConsoleExporters from "./console.js";
+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.");
+        return;
+    }
+    if (!config.collectorUrl) {
+        console.warn("collectorUrl not set. Skipping NodeJS OpenTelemetry instrumentation.");
+        return;
+    }
+    if (!isUrl(config.collectorUrl)) {
+        console.error("collectorUrl does not use a valid format. Skipping NodeJS OpenTelemetry instrumentation.");
+        return;
+    }
+    let exporter;
+    if (config.protocol === "http") {
+        exporter = buildHttpExporters(config);
+    }
+    else if (config.protocol === "console") {
+        exporter = buildConsoleExporters(config);
+    }
+    else {
+        exporter = buildGrpcExporters(config);
+    }
+    try {
+        diag.setLogger(new DiagConsoleLogger(), config.diagLogLevel
+            ? DiagLogLevel[config.diagLogLevel]
+            : DiagLogLevel.INFO);
+        const sdk = new NodeSDK({
+            resource: new resources.Resource({
+                "o11y.sdk.name": packageJson.name,
+                "o11y.sdk.version": packageJson.version,
+            }),
+            serviceName: config.serviceName,
+            traceExporter: exporter.traces,
+            metricReader: exporter.metrics,
+            logRecordProcessors: exporter.logs,
+            sampler: new UrlSampler(config.ignoreUrls),
+            textMapPropagator: new W3CTraceContextPropagator(),
+            instrumentations: [
+                getNodeAutoInstrumentations({
+                    "@opentelemetry/instrumentation-fs": {
+                        enabled: config.enableFS ?? false,
+                    },
+                }),
+            ],
+        });
+        sdk.start();
+        console.log("NodeJS OpenTelemetry instrumentation started successfully.");
+        return sdk;
+    }
+    catch (error) {
+        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/metrics.d.ts

@@ -0,0 +1,18 @@
+import { Counter, Gauge, Histogram, MetricOptions, ObservableCounter, ObservableGauge, ObservableUpDownCounter, UpDownCounter } from "@opentelemetry/api";
+declare const MetricsMap: {
+    gauge: Gauge;
+    histogram: Histogram;
+    counter: Counter;
+    updowncounter: UpDownCounter;
+    "async-counter": ObservableCounter;
+    "async-updowncounter": ObservableUpDownCounter;
+    "async-gauge": ObservableGauge;
+};
+type MetricType = keyof typeof MetricsMap;
+export interface MetricsParams {
+    metricName: string;
+    attributeName: string;
+    options?: MetricOptions;
+}
+export declare function getMetric<T extends MetricType>(type: T, p: MetricsParams): (typeof MetricsMap)[T];
+export {};

package/dist/lib/metrics.js

@@ -0,0 +1,28 @@
+import { createNoopMeter, metrics, } from "@opentelemetry/api";
+const MetricsFactoryMap = {
+    gauge: (meter) => meter.createGauge,
+    histogram: (meter) => meter.createHistogram,
+    counter: (meter) => meter.createCounter,
+    updowncounter: (meter) => meter.createUpDownCounter,
+    "async-counter": (meter) => meter.createObservableCounter,
+    "async-updowncounter": (meter) => meter.createObservableUpDownCounter,
+    "async-gauge": (meter) => meter.createObservableGauge,
+};
+function getMeter({ metricName, attributeName }) {
+    let meter;
+    if (!metricName || !attributeName) {
+        console.error("Invaid metric configuration!");
+        meter = createNoopMeter();
+    }
+    else {
+        meter = metrics.getMeter(`custom_metric.${metricName}`);
+    }
+    return meter;
+}
+export function getMetric(type, p) {
+    const meter = getMeter(p);
+    if (!MetricsFactoryMap[type]) {
+        throw new Error(`Unsupported metric type: ${type}`);
+    }
+    return MetricsFactoryMap[type](meter).bind(meter)(p.attributeName, p.options);
+}

package/dist/lib/options.d.ts

@@ -0,0 +1,6 @@
+import type { logs, tracing, metrics } from "@opentelemetry/sdk-node";
+export type Exporters = {
+    traces: tracing.SpanExporter;
+    metrics: metrics.MetricReader;
+    logs: logs.LogRecordProcessor[];
+};

package/dist/lib/options.js

@@ -0,0 +1 @@
+export {};

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/lib/utils.d.ts

@@ -0,0 +1,3 @@
+import { SDKCollectorMode } from "./index.js";
+import { logs } from "@opentelemetry/sdk-node";
+export declare const LogRecordProcessorMap: Record<SDKCollectorMode, typeof logs.SimpleLogRecordProcessor | typeof logs.BatchLogRecordProcessor>;

package/dist/lib/utils.js

@@ -0,0 +1,5 @@
+import { logs } from "@opentelemetry/sdk-node";
+export const LogRecordProcessorMap = {
+    single: logs.SimpleLogRecordProcessor,
+    batch: logs.BatchLogRecordProcessor,
+};

package/dist/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@ogcio/o11y-sdk-node",
+    "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"
+    },
+    "exports": {
+        ".": "./dist/index.js",
+        "./*": "./dist/*.js"
+    },
+    "keywords": [
+        "observability",
+        "o11y",
+        "opentelemetry",
+        "node",
+        "nodejs",
+        "ogcio"
+    ],
+    "author": "team:ogcio/observability",
+    "license": "ISC",
+    "dependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "@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",
+        "@opentelemetry/exporter-metrics-otlp-grpc": "^0.57.1",
+        "@opentelemetry/exporter-metrics-otlp-http": "^0.57.1",
+        "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.1",
+        "@opentelemetry/exporter-trace-otlp-http": "^0.57.1",
+        "@opentelemetry/instrumentation": "^0.57.1",
+        "@opentelemetry/otlp-exporter-base": "^0.57.1",
+        "@opentelemetry/sdk-metrics": "^1.30.1",
+        "@opentelemetry/sdk-node": "^0.57.1",
+        "@opentelemetry/sdk-trace-base": "^1.30.1"
+    },
+    "devDependencies": {
+        "@types/node": "^22.12.0",
+        "@vitest/coverage-v8": "^3.0.4",
+        "tsx": "^4.19.2",
+        "typescript": "^5.7.3",
+        "vitest": "^3.0.4"
+    }
+}

package/dist/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vitest.config.js

@@ -0,0 +1,25 @@
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+    test: {
+        globals: true,
+        watch: false,
+        include: ["**/test/*.test.ts", "**/test/integration/*.test.ts"],
+        exclude: ["**/fixtures/**", "**/dist/**"],
+        poolOptions: {
+            threads: {
+                maxThreads: 8,
+            },
+        },
+        clearMocks: true,
+        testTimeout: 30_000,
+        coverage: {
+            enabled: true,
+            provider: "v8",
+            reportsDirectory: "coverage",
+            reporter: ["lcov", "cobertura"],
+            clean: true,
+        },
+        reporters: ["default", ["junit", { outputFile: "test-report.xml" }]],
+        environment: "node",
+    },
+});

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.3",
+  "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: {