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

package/lib/http.ts

@@ -0,0 +1,35 @@
+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 { CompressionAlgorithm } from "@opentelemetry/otlp-exporter-base";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+
+export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
+  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 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/lib/index.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;
+}
+
+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;
+
+  /**
+   * http based connection protocol used to send signals.
+   *
+   * @default grpc
+   */
+  protocol?: SDKProtocol;
+}
+
+export type SDKCollectorMode = "single" | "batch";
+
+export type SDKProtocol = "grpc" | "http";
+
+export type SDKLogLevel =
+  | "NONE"
+  | "ERROR"
+  | "WARN"
+  | "INFO"
+  | "DEBUG"
+  | "VERBOSE"
+  | "ALL";

package/lib/instrumentation.node.ts

@@ -0,0 +1,75 @@
+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";
+
+export default function buildNodeInstrumentation(
+  config?: NodeSDKConfig,
+): NodeSDK | undefined {
+  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: Exporters;
+
+  if (config.protocol === "http") {
+    exporter = buildHttpExporters(config);
+  } else {
+    exporter = buildGrpcExporters(config);
+  }
+
+  try {
+    diag.setLogger(
+      new DiagConsoleLogger(),
+      config.diagLogLevel
+        ? DiagLogLevel[config.diagLogLevel]
+        : DiagLogLevel.INFO,
+    );
+
+    const sdk = new NodeSDK({
+      serviceName: config.serviceName,
+      traceExporter: exporter.traces,
+      metricReader: exporter.metrics,
+      logRecordProcessors: exporter.logs,
+      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,
+    );
+  }
+}

package/lib/options.ts

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

package/lib/utils.ts

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ogcio/o11y-sdk-node",
+  "version": "0.1.0-beta.1",
+  "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"
+  },
+  "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.53.0",
+    "@opentelemetry/core": "1.28.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.55.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.55.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.55.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.55.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.55.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.55.0",
+    "@opentelemetry/instrumentation": "^0.55.0",
+    "@opentelemetry/otlp-exporter-base": "^0.55.0",
+    "@opentelemetry/sdk-metrics": "^1.28.0",
+    "@opentelemetry/sdk-node": "^0.55.0",
+    "is-url": "^1.2.4"
+  },
+  "devDependencies": {
+    "@types/is-url": "^1.2.32",
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^2.1.6",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.6"
+  }
+}

package/test/index.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect, vi } from "vitest";
+import { NodeSDKConfig } from "../index";
+import { instrumentNode } from "../index";
+
+vi.mock("../lib/instrumentation.node", () => ({
+  default: vi.fn(),
+}));
+
+describe("instrumentNode", () => {
+  test("should call buildNodeInstrumentation with the provided config", async () => {
+    const config: NodeSDKConfig = {
+      serviceName: "custom-service",
+      collectorUrl: "http://custom-collector.com",
+      protocol: "grpc",
+    };
+
+    const buildNodeInstrumentation = await import(
+      "../lib/instrumentation.node"
+    );
+
+    instrumentNode(config);
+
+    expect(buildNodeInstrumentation.default).toHaveBeenCalledWith(config);
+  });
+
+  test("should not throw when called without arguments", () => {
+    expect(() => instrumentNode()).not.toThrow();
+  });
+});

package/test/node-config.test.ts

@@ -0,0 +1,113 @@
+import { test, describe, assert, expect } from "vitest";
+import buildNodeInstrumentation from "../lib/instrumentation.node.js";
+import { NodeSDK, logs } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter as GRPC_OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { OTLPMetricExporter as GRPC_OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-grpc";
+import { OTLPLogExporter as GRPC_OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-grpc";
+
+import { OTLPTraceExporter as HTTP_OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+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";
+
+describe("verify config settings", () => {
+  const commonConfig = {
+    collectorUrl: "https://testurl.com",
+    serviceName: "test",
+  };
+
+  test("grpc config", () => {
+    const config: NodeSDKConfig = {
+      ...commonConfig,
+      protocol: "grpc",
+      diagLogLevel: "NONE",
+    };
+
+    const sdk: NodeSDK | undefined = buildNodeInstrumentation(config);
+
+    assert.ok(sdk);
+
+    const _configuration = sdk["_configuration"];
+    assert.equal(_configuration.serviceName, commonConfig.serviceName);
+
+    const traceExporter = _configuration.traceExporter;
+    assert.equal(
+      traceExporter["_transport"]["_parameters"]["compression"],
+      "gzip",
+    );
+    assert.ok(traceExporter instanceof GRPC_OTLPTraceExporter);
+
+    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,
+    );
+
+    const metricReader = _configuration.metricReader;
+    assert.ok(metricReader._exporter instanceof GRPC_OTLPMetricExporter);
+  });
+
+  test("http config", () => {
+    const config: NodeSDKConfig = {
+      ...commonConfig,
+      protocol: "http",
+      diagLogLevel: "NONE",
+    };
+
+    const sdk: NodeSDK | undefined = buildNodeInstrumentation(config);
+    assert.ok(sdk);
+
+    const _configuration = sdk["_configuration"];
+    assert.equal(_configuration.serviceName, commonConfig.serviceName);
+
+    const traceExporter = _configuration.traceExporter;
+    assert.equal(
+      traceExporter._transport._transport._parameters.compression,
+      "gzip",
+    );
+    assert.ok(traceExporter instanceof HTTP_OTLPTraceExporter);
+
+    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,
+    );
+
+    const metricReader = _configuration.metricReader;
+    assert.ok(metricReader._exporter instanceof HTTP_OTLPMetricExporter);
+  });
+
+  test("single log sending config", () => {
+    const config: NodeSDKConfig = {
+      ...commonConfig,
+      protocol: "grpc",
+      diagLogLevel: "NONE",
+      collectorMode: "single",
+    };
+
+    const sdk: NodeSDK | undefined = buildNodeInstrumentation(config);
+
+    assert.ok(sdk);
+
+    const _configuration = sdk["_configuration"];
+
+    const logRecordProcessors = _configuration.logRecordProcessors;
+    assert.equal(logRecordProcessors.length, 1);
+    assert.ok(logRecordProcessors[0] instanceof logs.SimpleLogRecordProcessor);
+  });
+
+  test("check if clear base endpoint final slash", () => {
+    const config: NodeSDKConfig = {
+      collectorUrl: "http://example.com/",
+    };
+
+    buildHttpExporters(config);
+
+    expect(config.collectorUrl).toBe("http://example.com");
+  });
+});

package/test/validation.test.ts

@@ -0,0 +1,66 @@
+import type { NodeSDK } from "@opentelemetry/sdk-node";
+import { test, describe, assert, vi, expect } from "vitest";
+
+import buildNodeInstrumentation from "../lib/instrumentation.node.js";
+import { instrumentNode } from "../index.js";
+
+describe("validation config: should return without breaking the execution", () => {
+  test("should call buildNodeInstrumentation without config and skip instrumentation", async () => {
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(vi.fn());
+
+    instrumentNode();
+
+    expect(consoleWarnSpy).toHaveBeenCalled();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "observability config not set. Skipping NodeJS OpenTelemetry instrumentation.",
+    );
+  });
+
+  test("node instrumentation: url undefined", async () => {
+    let sdk: NodeSDK | undefined = undefined;
+
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(vi.fn());
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(vi.fn());
+
+    assert.doesNotThrow(() => {
+      sdk = buildNodeInstrumentation({
+        collectorUrl: undefined!,
+      });
+    });
+
+    assert.equal(sdk, undefined);
+
+    expect(consoleWarnSpy).toHaveBeenCalled();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "collectorUrl not set. Skipping NodeJS OpenTelemetry instrumentation.",
+    );
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+
+  test("node instrumentation: invalid url", () => {
+    let sdk: NodeSDK | undefined = undefined;
+
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(vi.fn());
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(vi.fn());
+
+    assert.doesNotThrow(() => {
+      sdk = buildNodeInstrumentation({
+        collectorUrl: "notavalidURL",
+      });
+    });
+
+    assert.equal(sdk, undefined);
+
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "collectorUrl does not use a valid format. Skipping NodeJS OpenTelemetry instrumentation.",
+    );
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+});

package/test-report.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<testsuites name="vitest tests" tests="9" failures="0" errors="0" time="0.781">
+    <testsuite name="test/index.test.ts" timestamp="2024-11-26T09:25:25.586Z" hostname="ABozzelli-ITMAC24" tests="2" failures="0" errors="0" skipped="0" time="0.002388">
+        <testcase classname="test/index.test.ts" name="instrumentNode &gt; should call buildNodeInstrumentation with the provided config" time="0.001363792">
+        </testcase>
+        <testcase classname="test/index.test.ts" name="instrumentNode &gt; should not throw when called without arguments" time="0.000454542">
+        </testcase>
+    </testsuite>
+    <testsuite name="test/node-config.test.ts" timestamp="2024-11-26T09:25:25.587Z" hostname="ABozzelli-ITMAC24" tests="4" failures="0" errors="0" skipped="0" time="0.042719333">
+        <testcase classname="test/node-config.test.ts" name="verify config settings &gt; grpc config" time="0.017177333">
+            <system-out>
+NodeJS OpenTelemetry instrumentation started successfully.
+
+            </system-out>
+        </testcase>
+        <testcase classname="test/node-config.test.ts" name="verify config settings &gt; http config" time="0.016206917">
+            <system-out>
+NodeJS OpenTelemetry instrumentation started successfully.
+
+            </system-out>
+        </testcase>
+        <testcase classname="test/node-config.test.ts" name="verify config settings &gt; single log sending config" time="0.008346875">
+            <system-out>
+NodeJS OpenTelemetry instrumentation started successfully.
+
+            </system-out>
+        </testcase>
+        <testcase classname="test/node-config.test.ts" name="verify config settings &gt; check if clear base endpoint final slash" time="0.000374">
+        </testcase>
+    </testsuite>
+    <testsuite name="test/validation.test.ts" timestamp="2024-11-26T09:25:25.587Z" hostname="ABozzelli-ITMAC24" tests="3" failures="0" errors="0" skipped="0" time="0.003302375">
+        <testcase classname="test/validation.test.ts" name="validation config: should return without breaking the execution &gt; should call buildNodeInstrumentation without config and skip instrumentation" time="0.00188275">
+        </testcase>
+        <testcase classname="test/validation.test.ts" name="validation config: should return without breaking the execution &gt; node instrumentation: url undefined" time="0.000551875">
+        </testcase>
+        <testcase classname="test/validation.test.ts" name="validation config: should return without breaking the execution &gt; node instrumentation: invalid url" time="0.000253958">
+        </testcase>
+    </testsuite>
+</testsuites>

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+    "module": "NodeNext" /* Specify what module code is generated. */,
+    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+    "strict": true /* Enable all strict type-checking options. */,
+    "skipLibCheck": true /* Skip type checking all .d.ts files. */,
+    "declaration": true
+  },
+  "exclude": ["**/test/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    watch: false,
+    include: ["**/test/*.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",
+  },
+});