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

package/lib/{http.ts → exporter/http.ts}

@@ -1,11 +1,12 @@
-import type { NodeSDKConfig } from "./index.js";
-import type { Exporters } from "./options.js";
-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";
+import { LogRecordProcessorMap, SpanProcessorMap } from "../utils.js";
+import { EnrichSpanProcessor } from "../processor/enrich-span-processor.js";
+import { Exporters } from "../options.js";
+import { NodeSDKConfig } from "../index.js";
 
 export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
   if (config.collectorUrl.endsWith("/")) {
@@ -13,10 +14,15 @@ export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
   }
 
   return {
-    traces: new OTLPTraceExporter({
-      url: `${config.collectorUrl}/v1/traces`,
-      compression: CompressionAlgorithm.GZIP,
-    }),
+    spans: [
+      new SpanProcessorMap[config.collectorMode ?? "batch"](
+        new OTLPTraceExporter({
+          url: `${config.collectorUrl}/v1/traces`,
+          compression: CompressionAlgorithm.GZIP,
+        }),
+      ),
+      new EnrichSpanProcessor(config.spanAttributes),
+    ],
     metrics: new metrics.PeriodicExportingMetricReader({
       exporter: new OTLPMetricExporter({
         url: `${config.collectorUrl}/v1/metrics`,

package/lib/index.ts

@@ -1,4 +1,4 @@
-interface SDKConfig {
+export interface NodeSDKConfig {
   /**
    * The opentelemetry collector entrypoint GRPC url.
    * If the collectoUrl is null or undefined, the instrumentation will not be activated.
@@ -25,9 +25,34 @@ interface SDKConfig {
    * @default batch
    */
   collectorMode?: SDKCollectorMode;
-}
+  /**
+   * Array of not traced urls.
+   *
+   * @type {SamplerCondition}
+   * @default []
+   */
+  ignoreUrls?: SamplerCondition[];
+
+  /**
+   * Object containing static properties or functions used to evaluate custom attributes for every logs and traces.
+   */
+  spanAttributes?: Record<
+    string,
+    SignalAttributeValue | (() => SignalAttributeValue)
+  >;
+
+  /**
+   * Object containing static properties used as resources attributes for the Node SDK initialization.
+   */
+  resourceAttributes?: Record<string, SignalAttributeValue>;
+
+  /**
+   * Faction value from 0 to 1, used by TraceIdRatioBasedSampler which it deterministically samples a percentage of traces that you pass in as a parameter.
+   *
+   * @default 1
+   */
+  traceRatio?: number;
 
-export interface NodeSDKConfig extends SDKConfig {
   /**
    * Flag to enable or disable the tracing for node:fs module
    *
@@ -36,13 +61,20 @@ export interface NodeSDKConfig extends SDKConfig {
   enableFS?: boolean;
 
   /**
-   * protocol used to send signals.
+   * Protocol used to send signals.
    *
    * @default grpc
    */
   protocol?: SDKProtocol;
 }
 
+export interface SamplerCondition {
+  type: "endsWith" | "includes" | "equals";
+  url: string;
+}
+
+export type SignalAttributeValue = string | number | boolean;
+
 export type SDKCollectorMode = "single" | "batch";
 
 export type SDKProtocol = "grpc" | "http" | "console";

package/lib/instrumentation.node.ts

@@ -1,14 +1,24 @@
-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";
-import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import {
+  diag,
+  DiagConsoleLogger,
+  DiagLogLevel,
+  Span,
+} from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { NodeSDK, resources } from "@opentelemetry/sdk-node";
+import {
+  AlwaysOffSampler,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} from "@opentelemetry/sdk-trace-base";
 import packageJson from "../package.json" with { type: "json" };
+import buildConsoleExporters from "./exporter/console.js";
+import buildGrpcExporters from "./exporter/grpc.js";
+import buildHttpExporters from "./exporter/http.js";
+import type { NodeSDKConfig } from "./index.js";
+import type { Exporters } from "./options.js";
+import { UrlSampler } from "./url-sampler.js";
 
 export default function buildNodeInstrumentation(
   config?: NodeSDKConfig,
@@ -44,6 +54,19 @@ export default function buildNodeInstrumentation(
     exporter = buildGrpcExporters(config);
   }
 
+  const urlSampler = new UrlSampler(
+    config.ignoreUrls,
+    new TraceIdRatioBasedSampler(config.traceRatio ?? 1),
+  );
+
+  const mainSampler = new ParentBasedSampler({
+    root: urlSampler,
+    remoteParentSampled: urlSampler,
+    remoteParentNotSampled: new AlwaysOffSampler(),
+    localParentSampled: urlSampler,
+    localParentNotSampled: new AlwaysOffSampler(),
+  });
+
   try {
     diag.setLogger(
       new DiagConsoleLogger(),
@@ -56,17 +79,34 @@ export default function buildNodeInstrumentation(
       resource: new resources.Resource({
         "o11y.sdk.name": packageJson.name,
         "o11y.sdk.version": packageJson.version,
+        ...config.resourceAttributes,
       }),
+      spanProcessors: exporter.spans,
       serviceName: config.serviceName,
-      traceExporter: exporter.traces,
       metricReader: exporter.metrics,
       logRecordProcessors: exporter.logs,
+      sampler: mainSampler,
       textMapPropagator: new W3CTraceContextPropagator(),
       instrumentations: [
         getNodeAutoInstrumentations({
           "@opentelemetry/instrumentation-fs": {
             enabled: config.enableFS ?? false,
           },
+          "@opentelemetry/instrumentation-pino": {
+            logHook: (
+              _span: Span,
+              record: Record<string, unknown>,
+              _level?: number,
+            ) => {
+              if (config.spanAttributes != undefined) {
+                for (const [key, value] of Object.entries(
+                  config.spanAttributes,
+                )) {
+                  record[key] = typeof value === "function" ? value() : value;
+                }
+              }
+            },
+          },
         }),
       ],
     });
@@ -81,3 +121,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/options.ts

@@ -1,7 +1,9 @@
-import type { logs, tracing, metrics } from "@opentelemetry/sdk-node";
+import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import type { metrics } from "@opentelemetry/sdk-node";
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
 
 export type Exporters = {
-  traces: tracing.SpanExporter;
+  spans: SpanProcessor[];
   metrics: metrics.MetricReader;
-  logs: logs.LogRecordProcessor[];
+  logs: LogRecordProcessor[];
 };

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

@@ -0,0 +1,39 @@
+import { Context } from "@opentelemetry/api";
+import {
+  ReadableSpan,
+  Span,
+  SpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { SignalAttributeValue } from "../index.js";
+
+export class EnrichSpanProcessor implements SpanProcessor {
+  private _spanAttributes:
+    | Record<string, SignalAttributeValue | (() => SignalAttributeValue)>
+    | undefined;
+
+  constructor(
+    spanAttributes?: Record<
+      string,
+      SignalAttributeValue | (() => SignalAttributeValue)
+    >,
+  ) {
+    this._spanAttributes = spanAttributes;
+  }
+
+  forceFlush(): Promise<void> {
+    return Promise.resolve();
+  }
+  onStart(span: Span, _context: Context): void {
+    if (this._spanAttributes != undefined) {
+      for (const [key, value] of Object.entries(this._spanAttributes)) {
+        span.setAttribute(key, typeof value === "function" ? value() : value);
+      }
+    }
+  }
+  onEnd(_span: ReadableSpan): void {
+    return;
+  }
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+}

package/lib/traces.ts

@@ -0,0 +1,5 @@
+import { trace } from "@opentelemetry/api";
+
+export function getActiveSpan() {
+  return trace.getActiveSpan();
+}

package/lib/url-sampler.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogcio/o11y-sdk-node",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.7",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
@@ -20,30 +20,33 @@
   "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",
-    "@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/exporter-logs-otlp-grpc": "^0.57.2",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.57.2",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.57.2",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.57.2",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.2",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.2",
+    "@opentelemetry/instrumentation": "^0.57.2",
+    "@opentelemetry/otlp-exporter-base": "^0.57.2",
+    "@opentelemetry/sdk-logs": "^0.57.2",
     "@opentelemetry/sdk-metrics": "^1.30.1",
-    "@opentelemetry/sdk-node": "^0.57.1",
-    "is-url": "^1.2.4"
+    "@opentelemetry/sdk-node": "^0.57.2",
+    "@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",
+    "@types/node": "^22.13.4",
+    "@vitest/coverage-v8": "^3.0.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
-    "vitest": "^3.0.4"
+    "vitest": "^3.0.5"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
-    "test": "vitest"
+    "test": "vitest",
+    "test:unit": "vitest --project unit",
+    "test:integration": "pnpm --filter @ogcio/o11y run prepare:integration && vitest --project integration",
+    "test:integration:dryrun": "vitest --project integration"
   }
 }

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

@@ -0,0 +1,105 @@
+import {
+  AttributeValue,
+  Context,
+  Exception,
+  Link,
+  Span,
+  SpanAttributes,
+  SpanAttributeValue,
+  SpanContext,
+  SpanStatus,
+  TimeInput,
+} 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.");
+  }
+}
+
+describe("EnrichSpanProcessor", () => {
+  it("should set static attributes on span", () => {
+    const spanAttributes = {
+      key1: "value1",
+      key2: 123,
+    };
+    const processor = new EnrichSpanProcessor(spanAttributes);
+    const mockSpan = new MockSpan();
+    const mockContext = {} as Context;
+
+    processor.onStart(mockSpan, mockContext);
+
+    expect(mockSpan.attributes["key1"]).toBe("value1");
+    expect(mockSpan.attributes["key2"]).toBe(123);
+  });
+
+  it("should set dynamic attributes on span", () => {
+    const spanAttributes = {
+      dynamicKey: () => "dynamicValue",
+    };
+    const processor = new EnrichSpanProcessor(spanAttributes);
+    const mockSpan = new MockSpan();
+    const mockContext = {} as Context;
+
+    processor.onStart(mockSpan, mockContext);
+
+    expect(mockSpan.attributes["dynamicKey"]).toBe("dynamicValue");
+  });
+
+  it("should not set attributes if none are provided", () => {
+    const processor = new EnrichSpanProcessor();
+    const mockSpan = new MockSpan();
+    const mockContext = {} as Context;
+
+    processor.onStart(mockSpan, mockContext);
+
+    expect(mockSpan.attributes["key1"]).toBeUndefined();
+  });
+
+  it("default method, should maintain default behaviour", async () => {
+    const processor = new EnrichSpanProcessor();
+
+    expect(processor.onEnd(null!)).toBeUndefined();
+    expect(await processor.shutdown()).toBeUndefined();
+    expect(await processor.forceFlush()).toBeUndefined();
+  });
+});

package/test/index.test.ts

@@ -12,6 +12,15 @@ describe("instrumentNode", () => {
       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 buildNodeInstrumentation = await import(

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,58 @@
+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++;
+
+          // 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);
+  });
+});