@ogcio/o11y-sdk-node 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.4.0](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.3.1...@ogcio/o11y-sdk-node@v0.4.0) (2025-09-02)
+
+
+### Features
+
+* o11y react-sdk IP pii redaction AB[#30758](https://github.com/ogcio/o11y/issues/30758) ([#196](https://github.com/ogcio/o11y/issues/196)) ([d6bb83f](https://github.com/ogcio/o11y/commit/d6bb83fa425ffdf3fb023ec62caeef070995d07a))
+* pii redaction refactor and ip redaction support AB[#30042](https://github.com/ogcio/o11y/issues/30042) AB[#30043](https://github.com/ogcio/o11y/issues/30043) ([#195](https://github.com/ogcio/o11y/issues/195)) ([3074693](https://github.com/ogcio/o11y/commit/307469399a7b03f3b647d85a2249e3c86dce933f))
+
+
+### Miscellaneous Chores
+
+* **deps:** bump the root-deps group across 1 directory with 16 updates ([#193](https://github.com/ogcio/o11y/issues/193)) ([c523565](https://github.com/ogcio/o11y/commit/c523565a6ba7f327473e8d93afc7d532ac220457))
+* **deps:** bump the root-deps group across 3 directories with 34 updates ([#188](https://github.com/ogcio/o11y/issues/188)) ([c0059f3](https://github.com/ogcio/o11y/commit/c0059f33cbb5c39cf6df0f4640604796dbbd3f57))
+
+## [0.3.1](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.3.0...@ogcio/o11y-sdk-node@v0.3.1) (2025-07-31)
+
+
+### Bug Fixes
+
+* **sdk-node:** replace Object.assign with spread operator on log redaction ([#186](https://github.com/ogcio/o11y/issues/186)) ([432f8d6](https://github.com/ogcio/o11y/commit/432f8d6aa493fd01d093f7ecdd0a9faccd0726e9))
+
 ## [0.3.0](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-node@v0.2.0...@ogcio/o11y-sdk-node@v0.3.0) (2025-07-28)
 
 

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

@@ -1,12 +1,13 @@
 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 { PushMetricExporter, ResourceMetrics } from "@opentelemetry/sdk-metrics";
 export declare class PIIExporterDecorator extends OTLPExporterBase<(ReadableSpan | ReadableLogRecord)[] | ResourceMetrics> implements SpanExporter, PushMetricExporter {
     private readonly _exporter;
     private readonly _config;
+    private readonly _redactors;
     constructor(exporter: OTLPExporterBase<(ReadableSpan | ReadableLogRecord)[] | ResourceMetrics>, config: NodeSDKConfig);
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
@@ -17,4 +18,5 @@ export declare class PIIExporterDecorator extends OTLPExporterBase<(ReadableSpan
     private _redactSpan;
     private _redactLogRecord;
     private _redactResourceMetrics;
+    private _buildRedactors;
 }

package/dist/lib/exporter/pii-exporter-decorator.js

@@ -1,12 +1,15 @@
 import { OTLPExporterBase } from "@opentelemetry/otlp-exporter-base";
-import { _cleanLogBodyPII, _cleanObjectPII, _cleanStringPII, } from "../internals/pii-detection.js";
+import { _cleanLogBodyPII, _cleanObjectPII, _cleanStringPII, } from "../internals/redaction/pii-detection.js";
+import { redactors, } from "../internals/redaction/redactors/index.js";
 export class PIIExporterDecorator extends OTLPExporterBase {
     _exporter;
     _config;
+    _redactors;
     constructor(exporter, config) {
         super(exporter["_delegate"]);
         this._exporter = exporter;
         this._config = config;
+        this._redactors = this._buildRedactors(config.detection);
     }
     forceFlush() {
         return this._exporter.forceFlush();
@@ -15,7 +18,7 @@ export class PIIExporterDecorator extends OTLPExporterBase {
         return this._exporter.shutdown();
     }
     export(items, resultCallback) {
-        if (!this._config.detection?.email) {
+        if (this._redactors.length === 0) {
             this._exporter.export(items, resultCallback);
             return;
         }
@@ -25,7 +28,7 @@ export class PIIExporterDecorator extends OTLPExporterBase {
                     this._redactSpan(item);
                 }
                 else if (this._isReadableLogRecord(item)) {
-                    this._redactLogRecord(item);
+                    item = this._redactLogRecord(item);
                 }
                 return item;
             });
@@ -62,42 +65,55 @@ export class PIIExporterDecorator extends OTLPExporterBase {
     }
     _redactSpan(span) {
         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"),
+                    attributes: link?.attributes &&
+                        _cleanObjectPII(link.attributes, "trace", this._redactors),
                 });
             }),
             events: span?.events?.map((event) => {
                 Object.assign(event, {
-                    name: _cleanStringPII(event.name, "trace"),
-                    attributes: event?.attributes && _cleanObjectPII(event.attributes, "trace"),
+                    name: _cleanStringPII(event.name, "trace", this._redactors),
+                    attributes: event?.attributes &&
+                        _cleanObjectPII(event.attributes, "trace", this._redactors),
                 });
                 return event;
             }),
         });
     }
     _redactLogRecord(log) {
-        Object.assign(log, {
-            body: _cleanLogBodyPII(log.body),
-            attributes: log.attributes && _cleanObjectPII(log.attributes, "log"),
-            resource: {
-                attributes: log?.resource?.attributes &&
-                    _cleanObjectPII(log.resource.attributes, "log"),
+        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),
             },
-        });
+        };
     }
     _redactResourceMetrics(metric) {
         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
+    _buildRedactors(redactorsConfig = {}) {
+        return Object.entries(redactors)
+            .filter(([key]) => {
+            return redactorsConfig[key] !== false;
+        })
+            .map(([_, value]) => value);
+    }
 }

package/dist/lib/index.d.ts

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

package/dist/lib/instrumentation.node.js

@@ -23,14 +23,6 @@ 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));

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

@@ -0,0 +1,23 @@
+import type { AnyValue } from "@opentelemetry/api-logs";
+import { Redactor } from "./redactors/index.js";
+import { AttributeValue } from "@opentelemetry/api";
+export type PIISource = "trace" | "log" | "metric";
+/**
+ * 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 declare function _cleanStringPII<T extends AnyValue>(value: T, source: PIISource, redactors: Redactor[]): T;
+export declare function _cleanObjectPII(entry: object, source: PIISource, redactors: Redactor[]): Record<string, AttributeValue>;
+export declare function _cleanLogBodyPII<T extends AnyValue>(value: T, redactors: Redactor[]): T;

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

@@ -0,0 +1,87 @@
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/**
+ * 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 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(value, source, redactors) {
+    if (Array.isArray(value)) {
+        return value.map((v) => _cleanStringPII(v, source, redactors));
+    }
+    if (typeof value !== "string") {
+        return value;
+    }
+    let kind = "string";
+    let decodedValue = value;
+    if (_containsEncodedComponents(value)) {
+        decodedValue = decodeURIComponent(value);
+        kind = "url";
+    }
+    return redactors.reduce((redactedValue, currentRedactor) => currentRedactor(redactedValue, source, kind), decodedValue);
+}
+export function _cleanObjectPII(entry, source, redactors) {
+    if (!entry) {
+        return entry;
+    }
+    return Object.fromEntries(Object.entries(entry).map(([k, v]) => [
+        k,
+        _cleanStringPII(v, source, redactors),
+    ]));
+}
+export function _cleanLogBodyPII(value, redactors) {
+    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);
+        }
+        catch {
+            return value;
+        }
+    }
+    if (Array.isArray(value)) {
+        return value.map((value) => _cleanLogBodyPII(value, redactors));
+    }
+    if (typeof value === "object") {
+        const sanitized = {};
+        for (const [key, val] of Object.entries(value)) {
+            sanitized[key] = _cleanLogBodyPII(val, redactors);
+        }
+        return sanitized;
+    }
+    return value;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const emailRedactor: (value: string, source: string, kind: string) => string;

package/dist/lib/internals/redaction/redactors/email.js

@@ -0,0 +1,48 @@
+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) {
+    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 };
+}
+/**
+ * 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, source, kind) => {
+    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/dist/lib/internals/redaction/redactors/index.d.ts

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

package/dist/lib/internals/redaction/redactors/index.js

@@ -0,0 +1,6 @@
+import { emailRedactor } from "./email.js";
+import { ipRedactor } from "./ip.js";
+export const redactors = {
+    email: emailRedactor,
+    ip: ipRedactor,
+};

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

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const ipRedactor: (value: string, source: string, kind: string) => string;

package/dist/lib/internals/redaction/redactors/ip.js

@@ -0,0 +1,54 @@
+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) {
+    const counters = {};
+    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, source, kind) => {
+    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/dist/lib/processor/enrich-logger-processor.d.ts

@@ -1,10 +1,10 @@
-import { LogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { SdkLogRecord, 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;
+    onEmit(logRecord: SdkLogRecord, _context?: Context): void;
     shutdown(): Promise<void>;
 }

package/dist/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",
@@ -30,26 +30,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"
     },

package/dist/vitest.config.js

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