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

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.
@@ -32,9 +32,27 @@ interface SDKConfig {
    * @default []
    */
   ignoreUrls?: SamplerCondition[];
-}
 
-export interface NodeSDKConfig extends SDKConfig {
+  /**
+   * 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;
+
   /**
    * Flag to enable or disable the tracing for node:fs module
    *
@@ -43,7 +61,7 @@ export interface NodeSDKConfig extends SDKConfig {
   enableFS?: boolean;
 
   /**
-   * protocol used to send signals.
+   * Protocol used to send signals.
    *
    * @default grpc
    */
@@ -55,6 +73,8 @@ export interface SamplerCondition {
   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,13 +1,23 @@
-import { NodeSDK, resources } from "@opentelemetry/sdk-node";
-import type { NodeSDKConfig } from "./index.js";
-import type { Exporters } from "./options.js";
-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(
@@ -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,18 +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: new UrlSampler(config.ignoreUrls),
+      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;
+                }
+              }
+            },
+          },
         }),
       ],
     });

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

@@ -1,10 +1,4 @@
-import {
-  Context,
-  SpanKind,
-  Link,
-  Attributes,
-  isValidTraceId,
-} from "@opentelemetry/api";
+import { Attributes, Context, Link, SpanKind } from "@opentelemetry/api";
 import {
   Sampler,
   SamplingDecision,
@@ -14,9 +8,11 @@ import { SamplerCondition } from "./index.js";
 
 export class UrlSampler implements Sampler {
   private _samplerCondition: SamplerCondition[];
+  private _nextSampler: Sampler;
 
-  constructor(samplerCondition: SamplerCondition[] = []) {
+  constructor(samplerCondition: SamplerCondition[] = [], nextSampler: Sampler) {
     this._samplerCondition = samplerCondition;
+    this._nextSampler = nextSampler;
   }
 
   shouldSample(
@@ -41,13 +37,16 @@ export class UrlSampler implements Sampler {
       }
     }
 
-    return {
-      decision: isValidTraceId(traceId)
-        ? SamplingDecision.RECORD_AND_SAMPLED
-        : SamplingDecision.NOT_RECORD,
-    };
+    return this._nextSampler.shouldSample(
+      _context,
+      traceId,
+      _spanName,
+      _spanKind,
+      attributes,
+      _links,
+    );
   }
   toString(): string {
-    throw "UrlSampler";
+    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.6",
+  "version": "0.1.0-beta.7",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
@@ -22,27 +22,31 @@
     "@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/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",
+    "@opentelemetry/sdk-node": "^0.57.2",
     "@opentelemetry/sdk-trace-base": "^1.30.1"
   },
   "devDependencies": {
-    "@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/integration.test.ts

@@ -23,6 +23,27 @@ describe("instrumentation integration test", () => {
       ) {
         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") {

package/test/integration/run.sh

@@ -60,9 +60,9 @@ fi
 
 if [[ $ERROR_CODE -eq 0 ]]; then
     sleep 2
-    curl -X GET -f http://localhost:9091/api/dummy
+    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
+    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

package/test/node-config.test.ts

@@ -9,7 +9,17 @@ import { OTLPTraceExporter as HTTP_OTLPTraceExporter } from "@opentelemetry/expo
 import { OTLPMetricExporter as HTTP_OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { OTLPLogExporter as HTTP_OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 import { NodeSDKConfig } from "../lib/index.js";
-import buildHttpExporters from "../lib/http.js";
+import buildHttpExporters from "../lib/exporter/http.js";
+import {
+  BatchSpanProcessor,
+  ConsoleSpanExporter,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import {
+  BatchLogRecordProcessor,
+  SimpleLogRecordProcessor,
+} from "@opentelemetry/sdk-logs";
+import { EnrichSpanProcessor } from "../lib/processor/enrich-span-processor.js";
 
 describe("verify config settings", () => {
   const commonConfig = {
@@ -21,6 +31,7 @@ describe("verify config settings", () => {
     const config: NodeSDKConfig = {
       ...commonConfig,
       protocol: "grpc",
+      collectorMode: "batch",
       diagLogLevel: "NONE",
     };
 
@@ -31,20 +42,21 @@ describe("verify config settings", () => {
     const _configuration = sdk["_configuration"];
     assert.equal(_configuration.serviceName, commonConfig.serviceName);
 
-    const traceExporter = _configuration.traceExporter;
+    const logs = _configuration.logRecordProcessors;
 
-    assert.ok(traceExporter instanceof GRPC_OTLPTraceExporter);
+    assert.equal(logs.length, 1);
+    assert.ok(logs[0] instanceof BatchLogRecordProcessor);
+
+    const spans = _configuration.spanProcessors;
+
+    assert.equal(spans.length, 2);
+    assert.ok(spans[0] instanceof BatchSpanProcessor);
+    assert.ok(spans[1] instanceof EnrichSpanProcessor);
 
-    const logRecordProcessors = _configuration.logRecordProcessors;
-    assert.equal(logRecordProcessors.length, 1);
-    // assert default signals sending mode
-    assert.ok(logRecordProcessors[0] instanceof logs.BatchLogRecordProcessor);
     assert.ok(
-      logRecordProcessors[0]["_exporter"] instanceof GRPC_OTLPLogExporter,
+      _configuration.metricReader instanceof
+        metrics.PeriodicExportingMetricReader,
     );
-
-    const metricReader = _configuration.metricReader;
-    assert.ok(metricReader._exporter instanceof GRPC_OTLPMetricExporter);
   });
 
   test("http config", () => {
@@ -60,19 +72,21 @@ describe("verify config settings", () => {
     const _configuration = sdk["_configuration"];
     assert.equal(_configuration.serviceName, commonConfig.serviceName);
 
-    const traceExporter = _configuration.traceExporter;
-    assert.ok(traceExporter instanceof HTTP_OTLPTraceExporter);
+    const logs = _configuration.logRecordProcessors;
+
+    assert.equal(logs.length, 1);
+    assert.ok(logs[0] instanceof BatchLogRecordProcessor);
+
+    const spans = _configuration.spanProcessors;
+
+    assert.equal(spans.length, 2);
+    assert.ok(spans[0] instanceof BatchSpanProcessor);
+    assert.ok(spans[1] instanceof EnrichSpanProcessor);
 
-    const logRecordProcessors = _configuration.logRecordProcessors;
-    assert.equal(logRecordProcessors.length, 1);
-    // assert default signals sending mode
-    assert.ok(logRecordProcessors[0] instanceof logs.BatchLogRecordProcessor);
     assert.ok(
-      logRecordProcessors[0]["_exporter"] instanceof HTTP_OTLPLogExporter,
+      _configuration.metricReader instanceof
+        metrics.PeriodicExportingMetricReader,
     );
-
-    const metricReader = _configuration.metricReader;
-    assert.ok(metricReader._exporter instanceof HTTP_OTLPMetricExporter);
   });
 
   test("console - console config", () => {
@@ -82,30 +96,29 @@ describe("verify config settings", () => {
       diagLogLevel: "NONE",
     };
 
-    const sdk: NodeSDK | undefined = buildNodeInstrumentation(config);
+    const sdk: NodeSDK = buildNodeInstrumentation(config)!;
     assert.ok(sdk);
 
     const _configuration = sdk["_configuration"];
     assert.equal(_configuration.serviceName, commonConfig.serviceName);
 
-    const traceExporter = _configuration.traceExporter;
+    const logs = _configuration.logRecordProcessors;
 
-    assert.ok(traceExporter instanceof tracing.ConsoleSpanExporter);
-    assert.isUndefined(traceExporter._transport);
+    // verify simple log processor for instant console logging
+    assert.equal(logs.length, 1);
+    assert.ok(logs[0] instanceof SimpleLogRecordProcessor);
 
-    const logRecordProcessors = _configuration.logRecordProcessors;
-    assert.equal(logRecordProcessors.length, 1);
+    const spans = _configuration.spanProcessors;
+
+    assert.equal(spans.length, 2);
+    // verify simple span for instant console logging
+    assert.ok(spans[0] instanceof SimpleSpanProcessor);
+    assert.ok(spans[1] instanceof EnrichSpanProcessor);
 
-    assert.ok(logRecordProcessors[0] instanceof logs.SimpleLogRecordProcessor);
     assert.ok(
-      logRecordProcessors[0]["_exporter"] instanceof
-        logs.ConsoleLogRecordExporter,
+      _configuration.metricReader instanceof
+        metrics.PeriodicExportingMetricReader,
     );
-    assert.isUndefined(logRecordProcessors[0]["_exporter"]._transport);
-
-    const metricReader = _configuration.metricReader;
-    assert.ok(metricReader._exporter instanceof metrics.ConsoleMetricExporter);
-    assert.isUndefined(metricReader._exporter._transport);
   });
 
   test("single log sending config", () => {
@@ -124,7 +137,7 @@ describe("verify config settings", () => {
 
     const logRecordProcessors = _configuration.logRecordProcessors;
     assert.equal(logRecordProcessors.length, 1);
-    assert.ok(logRecordProcessors[0] instanceof logs.SimpleLogRecordProcessor);
+    assert.ok(logRecordProcessors[0] instanceof SimpleLogRecordProcessor);
   });
 
   test("check if clear base endpoint final slash", () => {