@ogcio/o11y-sdk-node 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/lib/processor/enrich-logger-processor.d.ts

@@ -0,0 +1,10 @@
+import { LogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { Context } from "@opentelemetry/api";
+import { SignalAttributeValue } from "../index.js";
+export declare class EnrichLogProcessor implements LogRecordProcessor {
+    private _spanAttributes?;
+    constructor(spanAttributes?: Record<string, SignalAttributeValue | (() => SignalAttributeValue)>);
+    forceFlush(): Promise<void>;
+    onEmit(logRecord: LogRecord, _context?: Context): void;
+    shutdown(): Promise<void>;
+}

package/dist/lib/processor/enrich-logger-processor.js

@@ -0,0 +1,19 @@
+export class EnrichLogProcessor {
+    _spanAttributes = undefined;
+    constructor(spanAttributes) {
+        this._spanAttributes = spanAttributes;
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    onEmit(logRecord, _context) {
+        if (this._spanAttributes) {
+            for (const [key, value] of Object.entries(this._spanAttributes)) {
+                logRecord.setAttribute(key, typeof value === "function" ? value() : value);
+            }
+        }
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}

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

@@ -0,0 +1,11 @@
+import { Context } from "@opentelemetry/api";
+import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { SignalAttributeValue } from "../index.js";
+export declare class EnrichSpanProcessor implements SpanProcessor {
+    private _spanAttributes;
+    constructor(spanAttributes?: Record<string, SignalAttributeValue | (() => SignalAttributeValue)>);
+    forceFlush(): Promise<void>;
+    onStart(span: Span, _context: Context): void;
+    onEnd(_span: ReadableSpan): void;
+    shutdown(): Promise<void>;
+}

package/dist/lib/processor/enrich-span-processor.js

@@ -0,0 +1,22 @@
+export class EnrichSpanProcessor {
+    _spanAttributes;
+    constructor(spanAttributes) {
+        this._spanAttributes = spanAttributes;
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    onStart(span, _context) {
+        if (this._spanAttributes != undefined) {
+            for (const [key, value] of Object.entries(this._spanAttributes)) {
+                span.setAttribute(key, typeof value === "function" ? value() : value);
+            }
+        }
+    }
+    onEnd(_span) {
+        return;
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}

package/dist/lib/resource.d.ts

@@ -0,0 +1,7 @@
+import { ResourceDetector, DetectedResource } from "@opentelemetry/resources";
+import { SignalAttributeValue } from "./index.js";
+export declare class ObservabilityResourceDetector implements ResourceDetector {
+    private _resourceAttributes;
+    constructor(resourceAttributes?: Record<string, SignalAttributeValue>);
+    detect(): DetectedResource;
+}

package/dist/lib/resource.js

@@ -0,0 +1,18 @@
+import packageJson from "../package.json" with { type: "json" };
+export class ObservabilityResourceDetector {
+    _resourceAttributes;
+    constructor(resourceAttributes) {
+        this._resourceAttributes = resourceAttributes;
+    }
+    detect() {
+        let attributes = {};
+        if (this._resourceAttributes) {
+            attributes = {
+                ...this._resourceAttributes,
+            };
+        }
+        attributes["o11y.sdk.name"] = packageJson.name;
+        attributes["o11y.sdk.version"] = packageJson.version;
+        return { attributes };
+    }
+}

package/dist/lib/traces.d.ts

@@ -0,0 +1 @@
+export declare function getActiveSpan(): import("@opentelemetry/api").Span | undefined;

package/dist/lib/traces.js

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

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

@@ -0,0 +1,10 @@
+import { Attributes, Context, Link, SpanKind } from "@opentelemetry/api";
+import { Sampler, SamplingResult } from "@opentelemetry/sdk-trace-base";
+import { SamplerCondition } from "./index.js";
+export declare class UrlSampler implements Sampler {
+    private _samplerCondition;
+    private _nextSampler;
+    constructor(samplerCondition: SamplerCondition[] | undefined, nextSampler: Sampler);
+    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,25 @@
+import { SamplingDecision, } from "@opentelemetry/sdk-trace-base";
+export class UrlSampler {
+    _samplerCondition;
+    _nextSampler;
+    constructor(samplerCondition = [], nextSampler) {
+        this._samplerCondition = samplerCondition;
+        this._nextSampler = nextSampler;
+    }
+    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 this._nextSampler.shouldSample(_context, traceId, _spanName, _spanKind, attributes, _links);
+    }
+    toString() {
+        return "UrlSampler";
+    }
+}

package/dist/lib/utils.d.ts

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

package/dist/lib/utils.js

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

package/dist/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@ogcio/o11y-sdk-node",
+    "version": "0.1.0-beta.11",
+    "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",
+        "test:unit": "vitest --project unit",
+        "test:integration": "pnpm --filter @ogcio/o11y run prepare:integration && vitest --project integration",
+        "test:integration:dryrun": "vitest --project integration"
+    },
+    "exports": {
+        ".": "./dist/index.js",
+        "./*": "./dist/*.js"
+    },
+    "keywords": [
+        "observability",
+        "o11y",
+        "opentelemetry",
+        "node",
+        "nodejs",
+        "ogcio"
+    ],
+    "author": "team:ogcio/observability",
+    "license": "ISC",
+    "dependencies": {
+        "@grpc/grpc-js": "^1.13.4",
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/auto-instrumentations-node": "^0.60.0",
+        "@opentelemetry/core": "^2.0.1",
+        "@opentelemetry/exporter-logs-otlp-grpc": "^0.202.0",
+        "@opentelemetry/exporter-logs-otlp-http": "^0.202.0",
+        "@opentelemetry/exporter-metrics-otlp-grpc": "^0.202.0",
+        "@opentelemetry/exporter-metrics-otlp-http": "^0.202.0",
+        "@opentelemetry/exporter-trace-otlp-grpc": "^0.202.0",
+        "@opentelemetry/exporter-trace-otlp-http": "^0.202.0",
+        "@opentelemetry/instrumentation": "^0.202.0",
+        "@opentelemetry/otlp-exporter-base": "^0.202.0",
+        "@opentelemetry/resources": "^2.0.1",
+        "@opentelemetry/sdk-logs": "^0.202.0",
+        "@opentelemetry/sdk-metrics": "^2.0.1",
+        "@opentelemetry/sdk-node": "^0.202.0",
+        "@opentelemetry/sdk-trace-base": "^2.0.1"
+    },
+    "devDependencies": {
+        "@types/node": "^22.15.29",
+        "@vitest/coverage-v8": "^3.2.1",
+        "tsx": "^4.19.4",
+        "typescript": "^5.8.3",
+        "vitest": "^3.2.1"
+    },
+    "engines": {
+        "node": ">=20.6.0"
+    }
+}

package/dist/vitest.config.js

@@ -3,7 +3,6 @@ export default defineConfig({
     test: {
         globals: true,
         watch: false,
-        include: ["**/test/*.test.ts"],
         exclude: ["**/fixtures/**", "**/dist/**"],
         poolOptions: {
             threads: {
@@ -21,5 +20,20 @@ export default defineConfig({
         },
         reporters: ["default", ["junit", { outputFile: "test-report.xml" }]],
         environment: "node",
+        pool: "threads",
+        workspace: [
+            {
+                test: {
+                    include: ["**/test/*.test.ts", "**/test/processor/*.test.ts"],
+                    name: "unit",
+                },
+            },
+            {
+                test: {
+                    include: ["**/test/integration/*.test.ts"],
+                    name: "integration",
+                },
+            },
+        ],
     },
 });

package/index.ts

@@ -1,7 +1,9 @@
 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 type { NodeSDK };
 export { buildNodeInstrumentation as instrumentNode };
+
+export * from "./lib/metrics.js";
+export * from "./lib/traces.js";

package/lib/exporter/console.ts

@@ -0,0 +1,31 @@
+import {
+  ConsoleLogRecordExporter,
+  SimpleLogRecordProcessor,
+} from "@opentelemetry/sdk-logs";
+import { metrics } from "@opentelemetry/sdk-node";
+import {
+  ConsoleSpanExporter,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { NodeSDKConfig } from "../index.js";
+import { Exporters } from "./index.js";
+import { EnrichSpanProcessor } from "../processor/enrich-span-processor.js";
+import { EnrichLogProcessor } from "../processor/enrich-logger-processor.js";
+
+export default function buildConsoleExporters(
+  config: NodeSDKConfig,
+): Exporters {
+  return {
+    spans: [
+      new SimpleSpanProcessor(new ConsoleSpanExporter()),
+      new EnrichSpanProcessor(config.spanAttributes),
+    ],
+    metrics: new metrics.PeriodicExportingMetricReader({
+      exporter: new metrics.ConsoleMetricExporter(),
+    }),
+    logs: [
+      new EnrichLogProcessor(config.spanAttributes),
+      new SimpleLogRecordProcessor(new ConsoleLogRecordExporter()),
+    ],
+  };
+}

package/lib/exporter/grpc.ts

@@ -0,0 +1,52 @@
+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 "./index.js";
+import { LogRecordProcessorMap, SpanProcessorMap } from "../utils.js";
+import { EnrichSpanProcessor } from "../processor/enrich-span-processor.js";
+import { EnrichLogProcessor } from "../processor/enrich-logger-processor.js";
+
+async function defaultMetadata() {
+  const { Metadata } = await import("@grpc/grpc-js");
+
+  return new Metadata({
+    waitForReady: true,
+  });
+}
+
+export default async function buildGrpcExporters(
+  config: NodeSDKConfig,
+): Promise<Exporters> {
+  return {
+    spans: [
+      new SpanProcessorMap[config.collectorMode ?? "batch"](
+        new OTLPTraceExporter({
+          url: `${config.collectorUrl}`,
+          compression: CompressionAlgorithm.GZIP,
+          metadata: config.grpcMetadata ?? (await defaultMetadata()),
+        }),
+      ),
+      new EnrichSpanProcessor(config.spanAttributes),
+    ],
+    metrics: new metrics.PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: `${config.collectorUrl}`,
+        compression: CompressionAlgorithm.GZIP,
+        metadata: config.grpcMetadata ?? (await defaultMetadata()),
+      }),
+    }),
+    logs: [
+      new EnrichLogProcessor(config.spanAttributes),
+      new LogRecordProcessorMap[config.collectorMode ?? "batch"](
+        new OTLPLogExporter({
+          url: `${config.collectorUrl}`,
+          compression: CompressionAlgorithm.GZIP,
+          metadata: config.grpcMetadata ?? (await defaultMetadata()),
+        }),
+      ),
+    ],
+  };
+}

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

@@ -1,11 +1,13 @@
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-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 { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+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 "./index.js";
+import { NodeSDKConfig } from "../index.js";
+import { EnrichLogProcessor } from "../processor/enrich-logger-processor.js";
 
 export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
   if (config.collectorUrl.endsWith("/")) {
@@ -13,17 +15,23 @@ export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
   }
 
   return {
-    traces: new OTLPTraceExporter({
-      url: `${config.collectorUrl}/v1/traces`,
-      compression: CompressionAlgorithm.GZIP,
-    }),
-    metrics: new PeriodicExportingMetricReader({
+    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`,
         compression: CompressionAlgorithm.GZIP,
       }),
     }),
     logs: [
+      new EnrichLogProcessor(config.spanAttributes),
       new LogRecordProcessorMap[config.collectorMode ?? "batch"](
         new OTLPLogExporter({
           url: `${config.collectorUrl}/v1/logs`,

package/lib/exporter/index.ts

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

package/lib/index.ts

@@ -1,4 +1,6 @@
-interface SDKConfig {
+import type { Metadata } from "@grpc/grpc-js";
+
+export interface NodeSDKConfig {
   /**
    * The opentelemetry collector entrypoint GRPC url.
    * If the collectoUrl is null or undefined, the instrumentation will not be activated.
@@ -25,9 +27,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,16 +63,30 @@ export interface NodeSDKConfig extends SDKConfig {
   enableFS?: boolean;
 
   /**
-   * http based connection protocol used to send signals.
+   * Protocol used to send signals.
    *
    * @default grpc
    */
   protocol?: SDKProtocol;
+
+  /**
+   * Grpc Metadata for the grpc-js client.
+   *
+   * @default { waitForReady: true }
+   */
+  grpcMetadata?: Metadata;
 }
 
+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";
+export type SDKProtocol = "grpc" | "http" | "console";
 
 export type SDKLogLevel =
   | "NONE"

package/lib/instrumentation.node.ts

@@ -1,16 +1,23 @@
-import { NodeSDK } 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 { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import {
+  AlwaysOffSampler,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} from "@opentelemetry/sdk-trace-base";
+import buildConsoleExporters from "./exporter/console.js";
+import buildGrpcExporters from "./exporter/grpc.js";
+import buildHttpExporters from "./exporter/http.js";
+import type { Exporters } from "./exporter/index.js";
+import type { NodeSDKConfig } from "./index.js";
+import { ObservabilityResourceDetector } from "./resource.js";
+import { UrlSampler } from "./url-sampler.js";
 
-export default function buildNodeInstrumentation(
+export default async function buildNodeInstrumentation(
   config?: NodeSDKConfig,
-): NodeSDK | undefined {
+): Promise<NodeSDK | undefined> {
   if (!config) {
     console.warn(
       "observability config not set. Skipping NodeJS OpenTelemetry instrumentation.",
@@ -32,35 +39,52 @@ export default function buildNodeInstrumentation(
     return;
   }
 
-  let exporter: Exporters;
+  const urlSampler = new UrlSampler(
+    config.ignoreUrls,
+    new TraceIdRatioBasedSampler(config.traceRatio ?? 1),
+  );
 
-  if (config.protocol === "http") {
-    exporter = buildHttpExporters(config);
-  } else {
-    exporter = buildGrpcExporters(config);
-  }
+  const mainSampler = new ParentBasedSampler({
+    root: urlSampler,
+    remoteParentSampled: urlSampler,
+    remoteParentNotSampled: new AlwaysOffSampler(),
+    localParentSampled: urlSampler,
+    localParentNotSampled: new AlwaysOffSampler(),
+  });
+
+  diag.setLogger(
+    new DiagConsoleLogger(),
+    config.diagLogLevel ? DiagLogLevel[config.diagLogLevel] : DiagLogLevel.INFO,
+  );
 
   try {
-    diag.setLogger(
-      new DiagConsoleLogger(),
-      config.diagLogLevel
-        ? DiagLogLevel[config.diagLogLevel]
-        : DiagLogLevel.INFO,
-    );
+    const nodeSdkInstrumentation = getNodeAutoInstrumentations({
+      "@opentelemetry/instrumentation-fs": {
+        enabled: config.enableFS ?? false,
+      },
+    });
+
+    let exporter: Exporters;
+
+    if (config.protocol === "http") {
+      exporter = buildHttpExporters(config);
+    } else if (config.protocol === "console") {
+      exporter = buildConsoleExporters(config);
+    } else {
+      exporter = await buildGrpcExporters(config);
+    }
 
     const sdk = new NodeSDK({
+      resourceDetectors: [
+        new ObservabilityResourceDetector(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,
-          },
-        }),
-      ],
+      instrumentations: [nodeSdkInstrumentation],
     });
 
     sdk.start();
@@ -73,3 +97,12 @@ export default function buildNodeInstrumentation(
     );
   }
 }
+
+function isUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}