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

package/lib/metrics.ts

@@ -0,0 +1,75 @@
+import {
+  Counter,
+  createNoopMeter,
+  Gauge,
+  Histogram,
+  Meter,
+  MetricOptions,
+  metrics,
+  ObservableCounter,
+  ObservableGauge,
+  ObservableUpDownCounter,
+  UpDownCounter,
+  Attributes,
+} from "@opentelemetry/api";
+
+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>;
+};
+
+export type MetricType = keyof MetricTypeMap<Attributes>;
+
+const MetricsFactoryMap: Record<
+  MetricType,
+  (
+    meter: Meter,
+  ) => (
+    name: string,
+    options?: MetricOptions,
+  ) => MetricTypeMap<Attributes>[MetricType]
+> = {
+  gauge: (meter: Meter) => meter.createGauge,
+  histogram: (meter: Meter) => meter.createHistogram,
+  counter: (meter: Meter) => meter.createCounter,
+  updowncounter: (meter: Meter) => meter.createUpDownCounter,
+  "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;
+  options?: MetricOptions;
+}
+
+function getMeter({ meterName }: MetricsParams) {
+  if (!meterName) {
+    console.error("Invalid metric name!");
+    return createNoopMeter();
+  }
+
+  return metrics.getMeter(`custom_metric.${meterName}`);
+}
+
+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.metricName,
+    p.options,
+  ) as MetricTypeMap<TAttributes>[T];
+}

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

@@ -0,0 +1,34 @@
+import { LogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { Context } from "@opentelemetry/api";
+import { SignalAttributeValue } from "../index.js";
+
+export class EnrichLogProcessor implements LogRecordProcessor {
+  private _spanAttributes?:
+    | Record<string, SignalAttributeValue | (() => SignalAttributeValue)>
+    | undefined = undefined;
+
+  constructor(
+    spanAttributes?: Record<
+      string,
+      SignalAttributeValue | (() => SignalAttributeValue)
+    >,
+  ) {
+    this._spanAttributes = spanAttributes;
+  }
+  forceFlush(): Promise<void> {
+    return Promise.resolve();
+  }
+  onEmit(logRecord: LogRecord, _context?: Context): void {
+    if (this._spanAttributes) {
+      for (const [key, value] of Object.entries(this._spanAttributes)) {
+        logRecord.setAttribute(
+          key,
+          typeof value === "function" ? value() : value,
+        );
+      }
+    }
+  }
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+}

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/resource.ts

@@ -0,0 +1,30 @@
+import {
+  ResourceDetector,
+  DetectedResource,
+  DetectedResourceAttributes,
+} from "@opentelemetry/resources";
+import { SignalAttributeValue } from "./index.js";
+import packageJson from "../package.json" with { type: "json" };
+
+export class ObservabilityResourceDetector implements ResourceDetector {
+  private _resourceAttributes: Record<string, SignalAttributeValue> | undefined;
+
+  constructor(resourceAttributes?: Record<string, SignalAttributeValue>) {
+    this._resourceAttributes = resourceAttributes;
+  }
+
+  detect(): DetectedResource {
+    let attributes: DetectedResourceAttributes = {};
+
+    if (this._resourceAttributes) {
+      attributes = {
+        ...this._resourceAttributes,
+      };
+    }
+
+    attributes["o11y.sdk.name"] = packageJson.name;
+    attributes["o11y.sdk.version"] = packageJson.version;
+
+    return { attributes };
+  }
+}

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,13 +1,9 @@
 {
   "name": "@ogcio/o11y-sdk-node",
-  "version": "0.1.0-beta.1",
+  "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"
-  },
   "exports": {
     ".": "./dist/index.js",
     "./*": "./dist/*.js"
@@ -23,27 +19,39 @@
   "author": "team:ogcio/observability",
   "license": "ISC",
   "dependencies": {
+    "@grpc/grpc-js": "^1.13.4",
     "@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"
+    "@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/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"
+    "@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"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "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/index.test.ts

@@ -1,29 +1,39 @@
-import { describe, test, expect, vi } from "vitest";
+import { describe, test, expect, vi, beforeEach } from "vitest";
 import { NodeSDKConfig } from "../index";
 import { instrumentNode } from "../index";
-
-vi.mock("../lib/instrumentation.node", () => ({
-  default: vi.fn(),
-}));
+import * as buildNodeInstrumentationModule from "../lib/instrumentation.node";
 
 describe("instrumentNode", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test("should call buildNodeInstrumentation with the provided config", async () => {
+    const instrumentationMock = vi
+      .spyOn(buildNodeInstrumentationModule, "default")
+      .mockImplementation(vi.fn());
+
     const config: NodeSDKConfig = {
       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(
-      "../lib/instrumentation.node"
-    );
-
-    instrumentNode(config);
+    await instrumentNode(config);
 
-    expect(buildNodeInstrumentation.default).toHaveBeenCalledWith(config);
+    expect(instrumentationMock).toHaveBeenCalledWith(config);
   });
 
   test("should not throw when called without arguments", () => {
-    expect(() => instrumentNode()).not.toThrow();
+    expect(instrumentNode()).resolves.not.toThrow();
   });
 });

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
+- persist 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);
+  });
+});

package/test/integration/run.sh

@@ -0,0 +1,88 @@
+BUILD_ID=$1
+ROOT_PATH=$2
+
+NETWORK_NAME="${BUILD_ID}_testnetwork"
+ALLOY_CONTAINER_NAME="integrationalloy"
+NODE_CONTAINER_NAME="${BUILD_ID}_fastify_app"
+ERROR_CODE=0
+
+docker build -t ${NODE_CONTAINER_NAME}:${BUILD_ID} -f $ROOT_PATH/examples/fastify/Dockerfile $ROOT_PATH/
+
+docker network create $NETWORK_NAME
+
+docker run -d \
+    -v "$ROOT_PATH/alloy/integration-test.alloy:/etc/alloy/config.alloy:ro" \
+    --network $NETWORK_NAME \
+    --name $ALLOY_CONTAINER_NAME \
+    -p 4317:4317 \
+    -p 4318:4318 \
+    grafana/alloy \
+    run --server.http.listen-addr=0.0.0.0:12345 --stability.level=experimental /etc/alloy/config.alloy
+
+MAX_RETRIES=10
+COUNTER=0
+echo "$ALLOY_CONTAINER_NAME container status"
+until [ "$(docker inspect -f {{.State.Running}} $ALLOY_CONTAINER_NAME)" = true ]; do
+    sleep 2
+    docker inspect -f {{.State.Running}} $ALLOY_CONTAINER_NAME
+    COUNTER=$((COUNTER + 1))
+    if [ $COUNTER -ge $MAX_RETRIES ]; then
+        echo "Exceeded maximum retries. Exiting."
+        ERROR_CODE=1
+        break
+    fi
+done
+
+if [[ $ERROR_CODE -eq 0 ]]; then
+    docker run --detach \
+        --network $NETWORK_NAME \
+        --name $NODE_CONTAINER_NAME \
+        -e DB_DISABLED="true" \
+        -e SERVER_HOST="0.0.0.0" \
+        -e OTEL_COLLECTOR_URL="http://integrationalloy:4317" \
+        --health-cmd="curl -f http://${NODE_CONTAINER_NAME}:9091/api/health > /dev/null || exit 1" \
+        --health-start-period=1s \
+        --health-retries=10 \
+        --health-interval=1s \
+        -p 9091:9091 \
+        ${NODE_CONTAINER_NAME}:${BUILD_ID}
+
+    COUNTER=0
+    echo "$NODE_CONTAINER_NAME container status"
+    until [ "$(docker inspect -f {{.State.Health.Status}} $NODE_CONTAINER_NAME)" = "healthy" ]; do
+        sleep 1
+        docker inspect -f {{.State.Health.Status}} $NODE_CONTAINER_NAME
+        COUNTER=$((COUNTER + 1))
+        if [ $COUNTER -ge $MAX_RETRIES ]; then
+            echo "Exceeded maximum retries. Exiting."
+            ERROR_CODE=1
+            break
+        fi
+    done
+fi
+
+if [[ $ERROR_CODE -eq 0 ]]; then
+    sleep 2
+    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 -H 'Content-Type: application/json'
+fi
+
+# sleep N seconds to await instrumentation flow send and receiving signals
+sleep 10
+
+# Copy logs from container to file
+docker container logs $ALLOY_CONTAINER_NAME >&$ROOT_PATH/packages/sdk-node/test/integration/logs.txt
+echo "log file at $ROOT_PATH/packages/sdk-node/test/integration/logs.txt"
+
+docker container stop $ALLOY_CONTAINER_NAME
+docker container stop $NODE_CONTAINER_NAME
+
+docker container rm -f $ALLOY_CONTAINER_NAME
+docker container rm -f $NODE_CONTAINER_NAME
+
+docker image rm ${NODE_CONTAINER_NAME}:${BUILD_ID}
+
+docker network rm $NETWORK_NAME
+
+exit $ERROR_CODE