@ogcio/o11y-sdk-node 0.2.0 → 0.3.0

package/dist/lib/instrumentation.node.js

@@ -1,12 +1,13 @@
-import process from "process";
 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 { setNodeSdkConfig } from "./config-manager.js";
 import buildConsoleExporters from "./exporter/console.js";
 import buildGrpcExporters from "./exporter/grpc.js";
 import buildHttpExporters from "./exporter/http.js";
+import { _shutdownHook } from "./internals/hooks.js";
 import { ObservabilityResourceDetector } from "./resource.js";
 import { UrlSampler } from "./url-sampler.js";
 export default async function buildNodeInstrumentation(config) {
@@ -22,6 +23,16 @@ export default async function buildNodeInstrumentation(config) {
         console.error("collectorUrl does not use a valid format. Skipping NodeJS OpenTelemetry instrumentation.");
         return;
     }
+    if (!config.detection) {
+        config.detection = {
+            email: true,
+        };
+    }
+    if (config.detection.email === undefined) {
+        config.detection.email = true;
+    }
+    // Init configManager to make it available to all o11y utils.
+    setNodeSdkConfig(config);
     const urlSampler = new UrlSampler(config.ignoreUrls, new TraceIdRatioBasedSampler(config.traceRatio ?? 1));
     const mainSampler = new ParentBasedSampler({
         root: urlSampler,
@@ -61,16 +72,7 @@ export default async function buildNodeInstrumentation(config) {
         });
         sdk.start();
         console.log("NodeJS OpenTelemetry instrumentation started successfully.");
-        process.on("SIGTERM", async () => {
-            try {
-                // Flushing before shutdown is implemented on a per-exporter basis.
-                await sdk.shutdown();
-                console.log("NodeJS OpenTelemetry instrumentation shutdown successfully");
-            }
-            catch (error) {
-                console.error("Error shutting down NodeJS OpenTelemetry instrumentation:", error);
-            }
-        });
+        _shutdownHook(sdk);
         return sdk;
     }
     catch (error) {

package/dist/lib/internals/hooks.d.ts

@@ -0,0 +1,3 @@
+export declare function _shutdownHook(sdk: {
+    shutdown: () => Promise<void>;
+}): void;

package/dist/lib/internals/hooks.js

@@ -0,0 +1,12 @@
+export function _shutdownHook(sdk) {
+    process.on("SIGTERM", async () => {
+        try {
+            // Flushing before shutdown is implemented on a per-exporter basis.
+            await sdk.shutdown();
+            console.log("NodeJS OpenTelemetry instrumentation shutdown successfully");
+        }
+        catch (error) {
+            console.error("Error shutting down NodeJS OpenTelemetry instrumentation:", error);
+        }
+    });
+}

package/dist/lib/internals/pii-detection.d.ts

@@ -0,0 +1,17 @@
+import type { AnyValue } from "@opentelemetry/api-logs";
+export type PIISource = "trace" | "log" | "metric";
+/**
+ * Cleans a string by redacting email addresses and emitting metrics for PII.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ * Metrics are emitted for each domain found in redacted email addresses.
+ *
+ * @param {string} value - The input string to sanitize.
+ * @param {"trace" | "log"} source - The source context of the input, used in metrics.
+ * @returns {string} The cleaned string with any email addresses replaced by `[REDACTED EMAIL]`.
+ */
+export declare function _cleanStringPII(value: AnyValue, source: PIISource): AnyValue;
+export declare function _cleanObjectPII(entry: object, source: PIISource): {
+    [k: string]: AnyValue;
+};
+export declare function _cleanLogBodyPII(value: AnyValue): AnyValue;

package/dist/lib/internals/pii-detection.js

@@ -0,0 +1,116 @@
+import { _getPIICounterRedactionMetric } from "./shared-metrics.js";
+const EMAIL_REGEX = /[a-zA-Z0-9._%+-]+@([a-zA-Z0-9.-]+\.[a-z]{2,})/gi;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/**
+ * Redacts all email addresses in the input string and collects metadata.
+ *
+ * @param {string} value The input string potentially containing email addresses.
+ * @returns {{
+ *   redacted: string,
+ *   count: number,
+ *   domains: Record<string, number>
+ * }}
+ *
+ * An object containing:
+ *   - `redacted`: the string with email addresses replaced by `[REDACTED EMAIL]`
+ *   - `count`: total number of email addresses redacted
+ *   - `domains`: a map of domain names to the number of times they were redacted
+ */
+function _redactEmails(value) {
+    let count = 0;
+    const domains = {};
+    const redacted = value.replace(EMAIL_REGEX, (_, domain) => {
+        count++;
+        domains[domain] = (domains[domain] || 0) + 1;
+        return "[REDACTED EMAIL]";
+    });
+    return { redacted, count, domains };
+}
+/**
+ * Checks whether a string contains URI-encoded components.
+ *
+ * @param {string} value - The string to inspect.
+ * @returns {boolean} `true` if the string is encoded, `false` otherwise.
+ */
+function _containsEncodedComponents(value) {
+    try {
+        return decodeURI(value) !== decodeURIComponent(value);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cleans a string by redacting email addresses and emitting metrics for PII.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ * Metrics are emitted for each domain found in redacted email addresses.
+ *
+ * @param {string} value - The input string to sanitize.
+ * @param {"trace" | "log"} source - The source context of the input, used in metrics.
+ * @returns {string} The cleaned string with any email addresses replaced by `[REDACTED EMAIL]`.
+ */
+export function _cleanStringPII(value, source) {
+    if (Array.isArray(value)) {
+        return value.map((v) => _cleanStringPII(v, source));
+    }
+    if (typeof value !== "string") {
+        return value;
+    }
+    let kind = "string";
+    let decodedValue = value;
+    if (_containsEncodedComponents(value)) {
+        decodedValue = decodeURIComponent(value);
+        kind = "url";
+    }
+    const { redacted, count, domains } = _redactEmails(decodedValue);
+    if (count > 0) {
+        for (const [domain, domainCount] of Object.entries(domains)) {
+            _getPIICounterRedactionMetric().add(domainCount, {
+                pii_type: "email",
+                redaction_source: source,
+                pii_email_domain: domain,
+                pii_format: kind,
+            });
+        }
+    }
+    return redacted;
+}
+export function _cleanObjectPII(entry, source) {
+    if (!entry) {
+        return entry;
+    }
+    return Object.fromEntries(Object.entries(entry).map(([k, v]) => [k, _cleanStringPII(v, source)]));
+}
+export function _cleanLogBodyPII(value) {
+    if (typeof value === "string") {
+        return _cleanStringPII(value, "log");
+    }
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        value == null) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        try {
+            const decoded = decoder.decode(value);
+            const sanitized = _cleanStringPII(decoded, "log");
+            return encoder.encode(sanitized);
+        }
+        catch {
+            return value;
+        }
+    }
+    if (Array.isArray(value)) {
+        return value.map(_cleanLogBodyPII);
+    }
+    if (typeof value === "object") {
+        const sanitized = {};
+        for (const [key, val] of Object.entries(value)) {
+            sanitized[key] = _cleanLogBodyPII(val);
+        }
+        return sanitized;
+    }
+    return value;
+}

package/dist/lib/internals/shared-metrics.d.ts

@@ -0,0 +1,7 @@
+import { Attributes, Counter } from "@opentelemetry/api";
+/**
+ * Returns a singleton OpenTelemetry counter metric used to record occurrences of PII redactions.
+ *
+ * @returns {Counter} The singleton OpenTelemetry counter metric for PII redactions.
+ */
+export declare function _getPIICounterRedactionMetric(): Counter<Attributes>;

package/dist/lib/internals/shared-metrics.js

@@ -0,0 +1,18 @@
+import { getMetric } from "../metrics.js";
+// Cached singleton instance of the redaction counter metric
+let _redactedCounter;
+/**
+ * Returns a singleton OpenTelemetry counter metric used to record occurrences of PII redactions.
+ *
+ * @returns {Counter} The singleton OpenTelemetry counter metric for PII redactions.
+ */
+export function _getPIICounterRedactionMetric() {
+    if (_redactedCounter) {
+        return _redactedCounter;
+    }
+    _redactedCounter = getMetric("counter", {
+        meterName: "o11y",
+        metricName: "o11y_pii_redaction",
+    });
+    return _redactedCounter;
+}

package/dist/lib/traces.d.ts

@@ -1 +1,20 @@
-export declare function getActiveSpan(): import("@opentelemetry/api").Span | undefined;
+import { Span, SpanOptions } from "@opentelemetry/api";
+export type WithSpanParams<T> = {
+    /**
+     * The name of the trace the span should belong to.
+     * NOTE: If you want the new span to belong to an already existing trace, you should provide the same tracer name
+     */
+    traceName?: string;
+    spanName: string;
+    spanOptions?: SpanOptions;
+    /** A function defining the task you want to be wrapped by this span */
+    fn: (span: Span) => T | Promise<T>;
+};
+/**
+ * Gets the currently active OpenTelemetry span.
+ *
+ * @returns {Span | undefined} The active span with redaction logic applied,
+ * or `undefined` if there is no active span in context.
+ */
+export declare function getActiveSpan(): Span | undefined;
+export declare function withSpan<T>({ traceName, spanName, spanOptions, fn, }: WithSpanParams<T>): Promise<T>;

package/dist/lib/traces.js

@@ -1,4 +1,50 @@
-import { trace } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { getNodeSdkConfig } from "./config-manager.js";
+/**
+ * Generates a function wrapping a given Callable `fn` into an error handling block.
+ * Setting Span status and recording any caught exception before bubbling it up.
+ *
+ * Marks the span as ended once the provided callable has ended or an error has been caught.
+ *
+ * @returns {Promise<T>} where T is the type returned by the Callable.
+ * @throws any error thrown by the original Callable `fn` provided.
+ */
+function selfContainedSpanHandlerGenerator(fn) {
+    return async (span) => {
+        try {
+            const fnResult = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return fnResult;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                throw err;
+            }
+            span.recordException({ message: JSON.stringify(err) });
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: JSON.stringify(err),
+            });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    };
+}
+/**
+ * Gets the currently active OpenTelemetry span.
+ *
+ * @returns {Span | undefined} The active span with redaction logic applied,
+ * or `undefined` if there is no active span in context.
+ */
 export function getActiveSpan() {
     return trace.getActiveSpan();
 }
+export function withSpan({ traceName, spanName, spanOptions = {}, fn, }) {
+    const sdkConfig = getNodeSdkConfig();
+    const tracer = trace.getTracer(traceName ?? sdkConfig.serviceName ?? "o11y-sdk", sdkConfig.serviceVersion);
+    return tracer.startActiveSpan(spanName, spanOptions, selfContainedSpanHandlerGenerator(fn));
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ogcio/o11y-sdk-node",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
     "main": "dist/index.js",
     "type": "module",
@@ -29,6 +29,7 @@
     "dependencies": {
         "@grpc/grpc-js": "^1.13.4",
         "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/api-logs": "^0.203.0",
         "@opentelemetry/auto-instrumentations-node": "^0.60.1",
         "@opentelemetry/core": "^2.0.1",
         "@opentelemetry/exporter-logs-otlp-grpc": "^0.202.0",
@@ -46,7 +47,7 @@
         "@opentelemetry/sdk-trace-base": "^2.0.1"
     },
     "devDependencies": {
-        "@types/node": "^24.0.3",
+        "@types/node": "^24.0.10",
         "@vitest/coverage-v8": "^3.2.4",
         "tsx": "^4.20.3",
         "typescript": "^5.8.3",

package/dist/vitest.config.js

@@ -24,7 +24,13 @@ export default defineConfig({
         projects: [
             {
                 test: {
-                    include: ["**/test/*.test.ts", "**/test/processor/*.test.ts"],
+                    include: [
+                        "**/test/*.test.ts",
+                        "**/test/processor/*.test.ts",
+                        "**/test/traces/*.test.ts",
+                        "**/test/internals/*.test.ts",
+                        "**/test/exporter/*.test.ts",
+                    ],
                     name: "unit",
                 },
             },

package/lib/config-manager.ts

@@ -0,0 +1,16 @@
+import { NodeSDKConfig } from "./index.js";
+
+let nodeSDKConfig: NodeSDKConfig;
+
+export const setNodeSdkConfig = (config: NodeSDKConfig) => {
+  nodeSDKConfig = config;
+};
+
+export const getNodeSdkConfig = (): NodeSDKConfig => {
+  if (!nodeSDKConfig) {
+    throw new Error("Node SDK Config was not initialized.");
+  }
+
+  // Ensure getters do not edit config.
+  return JSON.parse(JSON.stringify(nodeSDKConfig));
+};

package/lib/exporter/console.ts

@@ -8,9 +8,11 @@ import {
   SimpleSpanProcessor,
 } from "@opentelemetry/sdk-trace-base";
 import { NodeSDKConfig } from "../index.js";
+import {
+  _logsProcessorConfig,
+  _spansProcessorConfig,
+} from "./processor-config.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,
@@ -18,13 +20,13 @@ export default function buildConsoleExporters(
   return {
     spans: [
       new SimpleSpanProcessor(new ConsoleSpanExporter()),
-      new EnrichSpanProcessor(config.spanAttributes),
+      ..._spansProcessorConfig(config),
     ],
     metrics: new metrics.PeriodicExportingMetricReader({
       exporter: new metrics.ConsoleMetricExporter(),
     }),
     logs: [
-      new EnrichLogProcessor(config.spanAttributes),
+      ..._logsProcessorConfig(config),
       new SimpleLogRecordProcessor(new ConsoleLogRecordExporter()),
     ],
   };

package/lib/exporter/grpc.ts

@@ -1,13 +1,17 @@
-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 { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { CompressionAlgorithm } from "@opentelemetry/otlp-exporter-base";
+import { metrics } from "@opentelemetry/sdk-node";
 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";
+import {
+  _logsProcessorConfig,
+  _spansProcessorConfig,
+} from "./processor-config.js";
+import { Exporters } from "./index.js";
+import { getNodeSdkConfig } from "../config-manager.js";
+import { PIIExporterDecorator } from "./pii-exporter-decorator.js";
 
 async function defaultMetadata() {
   const { Metadata } = await import("@grpc/grpc-js");
@@ -23,29 +27,38 @@ export default async function buildGrpcExporters(
   return {
     spans: [
       new SpanProcessorMap[config.collectorMode ?? "batch"](
-        new OTLPTraceExporter({
+        new PIIExporterDecorator(
+          new OTLPTraceExporter({
+            url: `${config.collectorUrl}`,
+            compression: CompressionAlgorithm.GZIP,
+            metadata: config.grpcMetadata ?? (await defaultMetadata()),
+          }),
+          getNodeSdkConfig(),
+        ),
+      ),
+      ..._spansProcessorConfig(config),
+    ],
+    metrics: new metrics.PeriodicExportingMetricReader({
+      exporter: new PIIExporterDecorator(
+        new OTLPMetricExporter({
           url: `${config.collectorUrl}`,
           compression: CompressionAlgorithm.GZIP,
           metadata: config.grpcMetadata ?? (await defaultMetadata()),
         }),
+        getNodeSdkConfig(),
       ),
-      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),
+      ..._logsProcessorConfig(config),
       new LogRecordProcessorMap[config.collectorMode ?? "batch"](
-        new OTLPLogExporter({
-          url: `${config.collectorUrl}`,
-          compression: CompressionAlgorithm.GZIP,
-          metadata: config.grpcMetadata ?? (await defaultMetadata()),
-        }),
+        new PIIExporterDecorator(
+          new OTLPLogExporter({
+            url: `${config.collectorUrl}`,
+            compression: CompressionAlgorithm.GZIP,
+            metadata: config.grpcMetadata ?? (await defaultMetadata()),
+          }),
+          getNodeSdkConfig(),
+        ),
       ),
     ],
   };

package/lib/exporter/http.ts

@@ -1,13 +1,17 @@
-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 { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { CompressionAlgorithm } from "@opentelemetry/otlp-exporter-base";
+import { metrics } from "@opentelemetry/sdk-node";
+import { NodeSDKConfig } from "../index.js";
 import { LogRecordProcessorMap, SpanProcessorMap } from "../utils.js";
-import { EnrichSpanProcessor } from "../processor/enrich-span-processor.js";
+import {
+  _logsProcessorConfig,
+  _spansProcessorConfig,
+} from "./processor-config.js";
 import { Exporters } from "./index.js";
-import { NodeSDKConfig } from "../index.js";
-import { EnrichLogProcessor } from "../processor/enrich-logger-processor.js";
+import { getNodeSdkConfig } from "../config-manager.js";
+import { PIIExporterDecorator } from "./pii-exporter-decorator.js";
 
 export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
   if (config.collectorUrl.endsWith("/")) {
@@ -17,26 +21,35 @@ export default function buildHttpExporters(config: NodeSDKConfig): Exporters {
   return {
     spans: [
       new SpanProcessorMap[config.collectorMode ?? "batch"](
-        new OTLPTraceExporter({
-          url: `${config.collectorUrl}/v1/traces`,
-          compression: CompressionAlgorithm.GZIP,
-        }),
+        new PIIExporterDecorator(
+          new OTLPTraceExporter({
+            url: `${config.collectorUrl}/v1/traces`,
+            compression: CompressionAlgorithm.GZIP,
+          }),
+          getNodeSdkConfig(),
+        ),
       ),
-      new EnrichSpanProcessor(config.spanAttributes),
+      ..._spansProcessorConfig(config),
     ],
     metrics: new metrics.PeriodicExportingMetricReader({
-      exporter: new OTLPMetricExporter({
-        url: `${config.collectorUrl}/v1/metrics`,
-        compression: CompressionAlgorithm.GZIP,
-      }),
+      exporter: new PIIExporterDecorator(
+        new OTLPMetricExporter({
+          url: `${config.collectorUrl}/v1/metrics`,
+          compression: CompressionAlgorithm.GZIP,
+        }),
+        getNodeSdkConfig(),
+      ),
     }),
     logs: [
-      new EnrichLogProcessor(config.spanAttributes),
+      ..._logsProcessorConfig(config),
       new LogRecordProcessorMap[config.collectorMode ?? "batch"](
-        new OTLPLogExporter({
-          url: `${config.collectorUrl}/v1/logs`,
-          compression: CompressionAlgorithm.GZIP,
-        }),
+        new PIIExporterDecorator(
+          new OTLPLogExporter({
+            url: `${config.collectorUrl}/v1/logs`,
+            compression: CompressionAlgorithm.GZIP,
+          }),
+          getNodeSdkConfig(),
+        ),
       ),
     ],
   };