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

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

@@ -1,18 +1,24 @@
-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-grpc";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-grpc";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-grpc";
+import { NodeSDKConfig } from "../index.js";
+import { Exporters } from "../options.js";
+import { LogRecordProcessorMap, SpanProcessorMap } from "../utils.js";
+import { EnrichSpanProcessor } from "../processor/enrich-span-processor.js";
 
 export default function buildGrpcExporters(config: NodeSDKConfig): Exporters {
   return {
-    traces: new OTLPTraceExporter({
-      url: `${config.collectorUrl}`,
-      compression: CompressionAlgorithm.GZIP,
-    }),
+    spans: [
+      new SpanProcessorMap[config.collectorMode ?? "batch"](
+        new OTLPTraceExporter({
+          url: `${config.collectorUrl}`,
+          compression: CompressionAlgorithm.GZIP,
+        }),
+      ),
+      new EnrichSpanProcessor(config.spanAttributes),
+    ],
     metrics: new metrics.PeriodicExportingMetricReader({
       exporter: new OTLPMetricExporter({
         url: `${config.collectorUrl}`,

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.
@@ -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;
+                }
+              }
+            },
+          },
         }),
       ],
     });
@@ -87,8 +126,7 @@ function isUrl(url: string): boolean {
   try {
     new URL(url);
     return true;
-  } catch (err) {
-    console.error(err);
+  } catch (_) {
     return false;
   }
 }

package/lib/metrics.ts

@@ -10,26 +10,30 @@ import {
   ObservableGauge,
   ObservableUpDownCounter,
   UpDownCounter,
+  Attributes,
 } from "@opentelemetry/api";
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-declare const MetricsMap: {
-  gauge: Gauge;
-  histogram: Histogram;
-  counter: Counter;
-  updowncounter: UpDownCounter;
-  "async-counter": ObservableCounter;
-  "async-updowncounter": ObservableUpDownCounter;
-  "async-gauge": ObservableGauge;
+type MetricTypeMap<TAttributes extends Attributes> = {
+  counter: Counter<TAttributes>;
+  histogram: Histogram<TAttributes>;
+  gauge: Gauge<TAttributes>;
+  updowncounter: UpDownCounter<TAttributes>;
+  "async-counter": ObservableCounter<TAttributes>;
+  "async-updowncounter": ObservableUpDownCounter<TAttributes>;
+  "async-gauge": ObservableGauge<TAttributes>;
 };
 
-type MetricType = keyof typeof MetricsMap;
+export type MetricType = keyof MetricTypeMap<Attributes>;
 
-const MetricsFactoryMap: {
-  [K in MetricType]: (
+const MetricsFactoryMap: Record<
+  MetricType,
+  (
     meter: Meter,
-  ) => (name: string, options?: MetricOptions) => (typeof MetricsMap)[K];
-} = {
+  ) => (
+    name: string,
+    options?: MetricOptions,
+  ) => MetricTypeMap<Attributes>[MetricType]
+> = {
   gauge: (meter: Meter) => meter.createGauge,
   histogram: (meter: Meter) => meter.createHistogram,
   counter: (meter: Meter) => meter.createCounter,
@@ -37,34 +41,35 @@ const MetricsFactoryMap: {
   "async-counter": (meter: Meter) => meter.createObservableCounter,
   "async-updowncounter": (meter: Meter) => meter.createObservableUpDownCounter,
   "async-gauge": (meter: Meter) => meter.createObservableGauge,
-};
+} as const;
 
 export interface MetricsParams {
+  meterName: string;
   metricName: string;
-  attributeName: string;
   options?: MetricOptions;
 }
 
-function getMeter({ metricName, attributeName }: MetricsParams) {
-  let meter: Meter;
-  if (!metricName || !attributeName) {
-    console.error("Invaid metric configuration!");
-    meter = createNoopMeter();
-  } else {
-    meter = metrics.getMeter(`custom_metric.${metricName}`);
+function getMeter({ meterName }: MetricsParams) {
+  if (!meterName) {
+    console.error("Invalid metric name!");
+    return createNoopMeter();
   }
-  return meter;
+
+  return metrics.getMeter(`custom_metric.${meterName}`);
 }
 
-export function getMetric<T extends MetricType>(
-  type: T,
-  p: MetricsParams,
-): (typeof MetricsMap)[T] {
+export function getMetric<
+  T extends MetricType,
+  TAttributes extends Attributes = Attributes,
+>(type: T, p: MetricsParams): MetricTypeMap<TAttributes>[T] {
   const meter = getMeter(p);
 
   if (!MetricsFactoryMap[type]) {
     throw new Error(`Unsupported metric type: ${type}`);
   }
 
-  return MetricsFactoryMap[type](meter).bind(meter)(p.attributeName, p.options);
+  return MetricsFactoryMap[type](meter).bind(meter)(
+    p.metricName,
+    p.options,
+  ) as MetricTypeMap<TAttributes>[T];
 }

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.8",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
@@ -20,29 +20,33 @@
   "license": "ISC",
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.56.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.56.1",
     "@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",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.4"
+    "@types/node": "^22.13.9",
+    "@vitest/coverage-v8": "^3.0.8",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
   },
   "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") {