@ogcio/o11y-sdk-node 0.3.0 → 0.4.0

package/lib/exporter/pii-exporter-decorator.ts

@@ -1,17 +1,22 @@
 import { ExportResult } from "@opentelemetry/core";
 import { OTLPExporterBase } from "@opentelemetry/otlp-exporter-base";
 import { ReadableLogRecord } from "@opentelemetry/sdk-logs";
+import {
+  PushMetricExporter,
+  ResourceMetrics,
+} from "@opentelemetry/sdk-metrics";
 import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
 import { NodeSDKConfig } from "../index.js";
 import {
   _cleanLogBodyPII,
   _cleanObjectPII,
   _cleanStringPII,
-} from "../internals/pii-detection.js";
+} from "../internals/redaction/pii-detection.js";
 import {
-  PushMetricExporter,
-  ResourceMetrics,
-} from "@opentelemetry/sdk-metrics";
+  Redactor,
+  RedactorKeys,
+  redactors,
+} from "../internals/redaction/redactors/index.js";
 
 export class PIIExporterDecorator
   extends OTLPExporterBase<
@@ -21,6 +26,7 @@ export class PIIExporterDecorator
 {
   private readonly _exporter;
   private readonly _config;
+  private readonly _redactors;
 
   constructor(
     exporter: OTLPExporterBase<
@@ -31,6 +37,7 @@ export class PIIExporterDecorator
     super(exporter["_delegate"]);
     this._exporter = exporter;
     this._config = config;
+    this._redactors = this._buildRedactors(config.detection);
   }
 
   forceFlush(): Promise<void> {
@@ -45,7 +52,7 @@ export class PIIExporterDecorator
     items: (ReadableSpan | ReadableLogRecord)[] | ResourceMetrics,
     resultCallback: (result: ExportResult) => void,
   ): void {
-    if (!this._config.detection?.email) {
+    if (this._redactors.length === 0) {
       this._exporter.export(items, resultCallback);
       return;
     }
@@ -55,7 +62,7 @@ export class PIIExporterDecorator
         if (this._isReadableSpan(item)) {
           this._redactSpan(item);
         } else if (this._isReadableLogRecord(item)) {
-          this._redactLogRecord(item);
+          item = this._redactLogRecord(item);
         }
         return item;
       });
@@ -102,51 +109,76 @@ export class PIIExporterDecorator
     );
   }
 
-  private _redactSpan(span: ReadableSpan) {
+  private _redactSpan(span: ReadableSpan): void {
     Object.assign(span, {
-      name: _cleanStringPII(span.name, "trace"),
-      attributes: span.attributes && _cleanObjectPII(span.attributes, "trace"),
+      name: _cleanStringPII(span.name, "trace", this._redactors),
+      attributes:
+        span.attributes &&
+        _cleanObjectPII(span.attributes, "trace", this._redactors),
       resource: {
         attributes:
           span?.resource?.attributes &&
-          _cleanObjectPII(span.resource.attributes, "trace"),
+          _cleanObjectPII(span.resource.attributes, "trace", this._redactors),
       },
       links: span?.links?.map((link) => {
         Object.assign(link, {
           attributes:
-            link?.attributes && _cleanObjectPII(link.attributes, "trace"),
+            link?.attributes &&
+            _cleanObjectPII(link.attributes, "trace", this._redactors),
         });
       }),
       events: span?.events?.map((event) => {
         Object.assign(event, {
-          name: _cleanStringPII(event.name, "trace"),
+          name: _cleanStringPII(event.name, "trace", this._redactors),
           attributes:
-            event?.attributes && _cleanObjectPII(event.attributes, "trace"),
+            event?.attributes &&
+            _cleanObjectPII(event.attributes, "trace", this._redactors),
         });
         return event;
       }),
     });
   }
 
-  private _redactLogRecord(log: ReadableLogRecord) {
-    Object.assign(log, {
-      body: _cleanLogBodyPII(log.body),
-      attributes: log.attributes && _cleanObjectPII(log.attributes, "log"),
-      resource: {
-        attributes:
-          log?.resource?.attributes &&
-          _cleanObjectPII(log.resource.attributes, "log"),
+  private _redactLogRecord(log: ReadableLogRecord): ReadableLogRecord {
+    return {
+      ...log,
+      body: _cleanLogBodyPII(log.body, this._redactors),
+      attributes:
+        log.attributes &&
+        _cleanObjectPII(log.attributes, "log", this._redactors),
+      resource: log.resource && {
+        ...log.resource,
+        attributes: _cleanObjectPII(
+          log.resource.attributes,
+          "log",
+          this._redactors,
+        ),
       },
-    });
+    };
   }
 
-  private _redactResourceMetrics(metric: ResourceMetrics) {
+  private _redactResourceMetrics(metric: ResourceMetrics): void {
     Object.assign(metric, {
       resource: {
         attributes:
           metric?.resource?.attributes &&
-          _cleanObjectPII(metric.resource.attributes, "metric"),
+          _cleanObjectPII(
+            metric.resource.attributes,
+            "metric",
+            this._redactors,
+          ),
       },
     });
   }
+
+  // Default opt-in every redactor available, excluding only those explicitly configured to false
+  private _buildRedactors(
+    redactorsConfig: NodeSDKConfig["detection"] = {},
+  ): Redactor[] {
+    return Object.entries(redactors)
+      .filter(([key]) => {
+        return redactorsConfig[key as RedactorKeys] !== false;
+      })
+      .map(([_, value]) => value);
+  }
 }

package/lib/index.ts

@@ -89,6 +89,11 @@ export interface NodeSDKConfig {
      * @default true
      */
     email?: boolean;
+    /**
+     * Redact IPv4/IPv6 addresses
+     * @default true
+     */
+    ip?: boolean;
   };
 }
 

package/lib/instrumentation.node.ts

@@ -41,16 +41,6 @@ export default async function buildNodeInstrumentation(
     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);
 

package/lib/internals/redaction/pii-detection.ts

@@ -0,0 +1,126 @@
+import type { AnyValue, AnyValueMap } from "@opentelemetry/api-logs";
+import { Redactor } from "./redactors/index.js";
+import { AttributeValue } from "@opentelemetry/api";
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+export type PIISource = "trace" | "log" | "metric";
+
+/**
+ * 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: string): boolean {
+  try {
+    return decodeURI(value) !== decodeURIComponent(value);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Cleans a string by redacting configured PIIs and emitting metrics for redacted values.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ * Metrics are emitted for:
+ * - each domain found in redacted email addresses.
+ * - IPv4|IPv6 addresses redacted.
+ *
+ * @template T
+ *
+ * @param {T} value - The input value to sanitize.
+ * @param {"trace" | "log"} source - The source context of the input, used in metrics.
+ * @param {Redactor[]} redactors - The string processors containing the redaction logic.
+ *
+ * @returns {T} The cleaned string with any configured PII replaced by `[REDACTED PII_TYPE]`.
+ */
+export function _cleanStringPII<T extends AnyValue>(
+  value: T,
+  source: PIISource,
+  redactors: Redactor[],
+): T {
+  if (Array.isArray(value)) {
+    return value.map((v) =>
+      _cleanStringPII<typeof v>(v, source, redactors),
+    ) as T;
+  }
+
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  let kind: "string" | "url" = "string";
+  let decodedValue: string = value;
+
+  if (_containsEncodedComponents(value)) {
+    decodedValue = decodeURIComponent(value);
+    kind = "url";
+  }
+
+  return redactors.reduce(
+    (redactedValue: string, currentRedactor): string =>
+      currentRedactor(redactedValue, source, kind),
+    decodedValue,
+  ) as T;
+}
+
+export function _cleanObjectPII(
+  entry: object,
+  source: PIISource,
+  redactors: Redactor[],
+): Record<string, AttributeValue> {
+  if (!entry) {
+    return entry;
+  }
+
+  return Object.fromEntries(
+    Object.entries(entry).map(([k, v]) => [
+      k,
+      _cleanStringPII(v, source, redactors),
+    ]),
+  );
+}
+
+export function _cleanLogBodyPII<T extends AnyValue>(
+  value: T,
+  redactors: Redactor[],
+): T {
+  if (typeof value === "string") {
+    return _cleanStringPII(value, "log", redactors);
+  }
+
+  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", redactors);
+      return encoder.encode(sanitized) as T;
+    } catch {
+      return value;
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((value) => _cleanLogBodyPII(value, redactors)) as T;
+  }
+
+  if (typeof value === "object") {
+    const sanitized: AnyValueMap = {};
+    for (const [key, val] of Object.entries(value)) {
+      sanitized[key] = _cleanLogBodyPII(val, redactors);
+    }
+    return sanitized as T;
+  }
+
+  return value;
+}

package/lib/internals/redaction/redactors/email.ts

@@ -0,0 +1,58 @@
+import { _getPIICounterRedactionMetric } from "../../shared-metrics.js";
+
+const EMAIL_REGEX = /[\p{L}\p{N}._%+-]+@((?:[\p{L}\p{N}-]+\.)+[\p{L}]{2,})/giu;
+
+/**
+ * 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: string): {
+  redacted: string;
+  count: number;
+  domains: Record<string, number>;
+} {
+  let count = 0;
+  const domains: Record<string, number> = {};
+
+  const redacted = value.replace(EMAIL_REGEX, (_, domain) => {
+    count++;
+    domains[domain] = (domains[domain] || 0) + 1;
+    return "[REDACTED EMAIL]";
+  });
+
+  return { redacted, count, domains };
+}
+
+/**
+ * Redacts provided input and collects metadata metrics about redacted email domains,
+ * data source and kind.
+ *
+ * @param {string} value The input string potentially containing email addresses.
+ * @returns {string} the redacted value
+ */
+export const emailRedactor = (value: string, source: string, kind: string) => {
+  const { redacted, count, domains } = _redactEmails(value);
+
+  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;
+};

package/lib/internals/redaction/redactors/index.ts

@@ -0,0 +1,12 @@
+import { NodeSDKConfig } from "../../../index.js";
+import { emailRedactor } from "./email.js";
+import { ipRedactor } from "./ip.js";
+
+export type Redactor = (value: string, source: string, kind: string) => string;
+
+export type RedactorKeys = keyof NonNullable<NodeSDKConfig["detection"]>;
+
+export const redactors: Record<RedactorKeys, Redactor> = {
+  email: emailRedactor,
+  ip: ipRedactor,
+};

package/lib/internals/redaction/redactors/ip.ts

@@ -0,0 +1,68 @@
+import { _getPIICounterRedactionMetric } from "../../shared-metrics.js";
+
+// Generous IP address matchers (might match some invalid addresses like 192.168.01.1)
+const IPV4_REGEX =
+  /(?<!\d)(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}(?!\d)/gi;
+const IPV6_REGEX =
+  /(?<![0-9a-f:])((?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|:(?::[0-9A-Fa-f]{1,4}){1,7}|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}|[0-9A-Fa-f]{1,4}:(?::[0-9A-Fa-f]{1,4}){1,6}|:(?::[0-9A-Fa-f]{1,4}){1,7}:?|(?:[0-9A-Fa-f]{1,4}:){1,4}:(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})){3})(?![0-9a-f:])/gi;
+
+/**
+ * Redacts all ip addresses in the input string and collects metadata.
+ *
+ * @param {string} value The input string potentially containing ip addresses.
+ * @returns {{
+ *   redacted: string,
+ *   count: number,
+ *   domains: Record<string, number>
+ * }}
+ *
+ * An object containing:
+ *   - `redacted`: the string with IP addresses replaced by `[REDACTED IPV*]`
+ *   - `counters`: total number of addresses redacted by IPv* type
+ *   - `domains`: a map of domain names to the number of times they were redacted
+ */
+function _redactIps(value: string): {
+  redacted: string;
+  counters: Record<string, number>;
+} {
+  const counters: Record<string, number> = {};
+  const redacted = value
+    .replace(IPV4_REGEX, () => {
+      counters["IPv4"] = (counters["IPv4"] || 0) + 1;
+      return "[REDACTED IPV4]";
+    })
+    .replace(IPV6_REGEX, () => {
+      counters["IPv4"] = (counters["IPv4"] || 0) + 1;
+      return "[REDACTED IPV6]";
+    });
+  return { redacted, counters };
+}
+
+/**
+ * Redacts provided input and collects metadata metrics about redacted IPs,
+ * data source and kind.
+ *
+ * @param {string} value The input string potentially containing IP addresses.
+ * @param {string} source The source of the attribute being redacted (log, span, metric).
+ * @param {string} kind The type of the data structure containing the PII
+ * @returns {string} the redacted value
+ */
+export const ipRedactor = (
+  value: string,
+  source: string,
+  kind: string,
+): string => {
+  const { redacted, counters } = _redactIps(value);
+
+  Object.entries(counters).forEach(([type, counter]) => {
+    if (counter > 0) {
+      _getPIICounterRedactionMetric().add(counter, {
+        pii_type: type,
+        redaction_source: source,
+        pii_format: kind,
+      });
+    }
+  });
+
+  return redacted;
+};

package/lib/internals/shared-metrics.ts

@@ -1,6 +1,6 @@
 import { Attributes, Counter } from "@opentelemetry/api";
 import { getMetric } from "../metrics.js";
-import { PIISource } from "./pii-detection.js";
+import { PIISource } from "./redaction/pii-detection.js";
 
 interface RedactionMetric extends Attributes {
   /** Type of PII redacted (e.g., "email", "phone"). */

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

@@ -1,4 +1,4 @@
-import { LogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { SdkLogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { Context } from "@opentelemetry/api";
 import { SignalAttributeValue } from "../index.js";
 
@@ -18,7 +18,7 @@ export class EnrichLogProcessor implements LogRecordProcessor {
   forceFlush(): Promise<void> {
     return Promise.resolve();
   }
-  onEmit(logRecord: LogRecord, _context?: Context): void {
+  onEmit(logRecord: SdkLogRecord, _context?: Context): void {
     if (this._spanAttributes) {
       for (const [key, value] of Object.entries(this._spanAttributes)) {
         logRecord.setAttribute(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogcio/o11y-sdk-node",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
@@ -22,26 +22,26 @@
     "@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/auto-instrumentations-node": "^0.62.1",
     "@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/exporter-logs-otlp-grpc": "^0.203.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.203.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/instrumentation": "^0.203.0",
+    "@opentelemetry/otlp-exporter-base": "^0.203.0",
     "@opentelemetry/resources": "^2.0.1",
-    "@opentelemetry/sdk-logs": "^0.202.0",
+    "@opentelemetry/sdk-logs": "^0.203.0",
     "@opentelemetry/sdk-metrics": "^2.0.1",
-    "@opentelemetry/sdk-node": "^0.202.0",
+    "@opentelemetry/sdk-node": "^0.203.0",
     "@opentelemetry/sdk-trace-base": "^2.0.1"
   },
   "devDependencies": {
-    "@types/node": "^24.0.10",
+    "@types/node": "^24.3.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "tsx": "^4.20.3",
+    "tsx": "^4.20.5",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },