@ogcio/o11y-sdk-react 0.4.2 → 0.6.1

package/lib/instrumentation.faro.ts

@@ -1,102 +0,0 @@
-import {
-  ErrorsInstrumentation,
-  getWebInstrumentations,
-  initializeFaro,
-  WebVitalsInstrumentation,
-  type Faro,
-} from "@grafana/faro-react";
-import { TracingInstrumentation } from "@grafana/faro-web-tracing";
-import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
-import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
-import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
-import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
-import type { FaroSDKConfig } from "./index.js";
-import { _beforeSend } from "./internals/hooks.js";
-import {
-  RedactorKeys,
-  redactors,
-} from "./internals/redaction/redactors/index.js";
-
-export default function buildFaroInstrumentation(
-  config?: FaroSDKConfig,
-): Faro | undefined {
-  if (!config) {
-    console.warn(
-      "observability config not set. Skipping Faro OpenTelemetry instrumentation.",
-    );
-    return;
-  }
-
-  if (!config.collectorUrl) {
-    console.warn(
-      "collectorUrl not set. Skipping Faro OpenTelemetry instrumentation.",
-    );
-    return;
-  }
-
-  if (!isUrl(config.collectorUrl)) {
-    console.error(
-      "collectorUrl does not use a valid format. Skipping Faro OpenTelemetry instrumentation.",
-    );
-    return;
-  }
-
-  const redactorsChain = Object.entries(redactors)
-    .filter(([key]) => {
-      return config.detection?.[key as RedactorKeys] !== false;
-    })
-    .map(([_, value]) => value);
-  try {
-    diag.setLogger(
-      new DiagConsoleLogger(),
-      config.diagLogLevel
-        ? DiagLogLevel[config.diagLogLevel]
-        : DiagLogLevel.INFO,
-    );
-
-    const faro = initializeFaro({
-      url: config.collectorUrl,
-      app: {
-        name: config.serviceName,
-      },
-      batching: {
-        enabled: !(config.collectorMode === "single"),
-      },
-      beforeSend: _beforeSend(redactorsChain),
-      instrumentations: [
-        ...getWebInstrumentations({
-          captureConsole: true,
-        }),
-        new ErrorsInstrumentation(),
-        new WebVitalsInstrumentation(),
-        new TracingInstrumentation({
-          propagator: new W3CTraceContextPropagator(),
-          instrumentations: [
-            new DocumentLoadInstrumentation(),
-            new FetchInstrumentation({
-              ignoreUrls: [config.collectorUrl], // ignore collector to avoid fetch loop
-              propagateTraceHeaderCorsUrls: config.corsTraceHeaders
-                ? config.corsTraceHeaders.split(",").map((s) => new RegExp(s))
-                : undefined,
-            }),
-            new UserInteractionInstrumentation(),
-          ],
-        }),
-      ],
-    });
-    console.log("Faro OpenTelemetry instrumentation started successfully.");
-    return faro;
-  } catch (error) {
-    console.error("Error starting Faro OpenTelemetry instrumentation:", error);
-  }
-}
-
-function isUrl(url: string): boolean {
-  try {
-    new URL(url);
-    return true;
-  } catch (_) {
-    return false;
-  }
-}

package/lib/internals/hooks.ts

@@ -1,55 +0,0 @@
-import {
-  APIEvent,
-  TransportItem,
-  TransportItemType,
-} from "@grafana/faro-web-sdk";
-import { _cleanStringPII } from "./redaction/pii-detection.js";
-import { Redactor } from "./redaction/redactors/index.js";
-
-function _cleanObjectPII<
-  T extends string | Record<string, unknown> | unknown[] | unknown,
->(data: T, type: TransportItemType, redactors: Redactor[]): void {
-  if (!data) {
-    return;
-  }
-
-  if (Array.isArray(data)) {
-    data.forEach((item, index) => {
-      if (typeof item === "string") {
-        data[index] = _cleanStringPII(data[index], type, redactors);
-        return;
-      }
-
-      if (typeof item === "object") {
-        _cleanObjectPII<T>(item, type, redactors);
-      }
-    });
-  }
-
-  if (typeof data === "object") {
-    for (const key in data) {
-      if (typeof data[key] === "string") {
-        data[key] = _cleanStringPII(
-          data[key],
-          type,
-          redactors,
-        ) as (typeof data)[typeof key];
-      }
-
-      if (typeof data[key] === "object") {
-        _cleanObjectPII(data[key], type, redactors);
-      }
-    }
-  }
-}
-
-export const _beforeSend =
-  (redactors: Redactor[]) =>
-  (item: TransportItem<APIEvent>): TransportItem<APIEvent> | null => {
-    if (redactors.length === 0) {
-      return item;
-    }
-
-    _cleanObjectPII(item, item.type, redactors);
-    return item;
-  };

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

@@ -1,64 +0,0 @@
-import { TransportItemType } from "@grafana/faro-web-sdk";
-import { Redactor } from "./redactors/index.js";
-
-/**
- * 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.
- */
-export function _containsEncodedComponents(value: string): boolean {
-  try {
-    const decodedURIComponent = decodeURIComponent(value);
-    if (decodeURI(value) !== decodedURIComponent) {
-      return true;
-    }
-
-    if (value !== decodedURIComponent) {
-      return (
-        encodeURIComponent(decodedURIComponent) === value ||
-        encodeURI(decodedURIComponent) === value
-      );
-    }
-  } catch {
-    return false;
-  }
-
-  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 {string} 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: string,
-  source: TransportItemType,
-  redactors: Redactor[],
-): string {
-  let kind: "string" | "url" = "string";
-  let decodedValue = value;
-
-  if (_containsEncodedComponents(value)) {
-    decodedValue = decodeURIComponent(value);
-    kind = "url";
-  }
-
-  return redactors.reduce(
-    (redactedValue: string, currentRedactor): string =>
-      currentRedactor(redactedValue, source, kind),
-    decodedValue,
-  );
-}

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

@@ -1,68 +0,0 @@
-import { faro } from "@grafana/faro-web-sdk";
-
-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)) {
-      faro.api.pushMeasurement(
-        {
-          type: "faro_o11y_pii_redaction",
-          values: {
-            redacted: domainCount,
-          },
-        },
-        {
-          context: {
-            pii_type: "email",
-            redaction_source: source,
-            pii_email_domain: domain,
-            pii_format: kind,
-          },
-        },
-      );
-    }
-  }
-  return redacted;
-};

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

@@ -1,12 +0,0 @@
-import { type FaroSDKConfig } 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<FaroSDKConfig["detection"]>;
-
-export const redactors: Record<RedactorKeys, Redactor> = {
-  email: emailRedactor,
-  ip: ipRedactor,
-};

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

@@ -1,78 +0,0 @@
-import { faro } from "@grafana/faro-web-sdk";
-
-// 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) {
-      faro.api.pushMeasurement(
-        {
-          type: "faro_o11y_pii_redaction",
-          values: {
-            redacted: counter,
-          },
-        },
-        {
-          context: {
-            pii_type: type,
-            redaction_source: source,
-            pii_format: kind,
-          },
-        },
-      );
-    }
-  });
-
-  return redacted;
-};

package/test/config.test.ts

@@ -1,215 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import buildFaroInstrumentation from "../lib/instrumentation.faro";
-import { initializeFaro } from "@grafana/faro-react";
-import { _beforeSend } from "../lib/internals/hooks";
-import { redactors } from "../lib/internals/redaction/redactors";
-import * as detectionTools from "../lib/internals/redaction/pii-detection";
-
-// Mock dependencies
-vi.mock("@grafana/faro-react", async () => {
-  const actual = await vi.importActual<any>("@grafana/faro-react");
-  return {
-    ...actual,
-    initializeFaro: vi.fn(() => ({ fakeFaro: true })),
-    getWebInstrumentations: vi.fn(() => ["webInstrumentation"]),
-    ErrorsInstrumentation: vi.fn(() => "errorsInstrumentation"),
-    WebVitalsInstrumentation: vi.fn(() => "webVitalsInstrumentation"),
-  };
-});
-
-vi.mock("@grafana/faro-web-tracing", () => ({
-  TracingInstrumentation: vi.fn(() => "tracingInstrumentation"),
-}));
-
-vi.mock("@opentelemetry/core", () => ({
-  W3CTraceContextPropagator: vi.fn(() => "tracePropagator"),
-}));
-
-vi.mock("@opentelemetry/instrumentation-document-load", () => ({
-  DocumentLoadInstrumentation: vi.fn(() => "docLoadInstrumentation"),
-}));
-
-vi.mock("@opentelemetry/instrumentation-fetch", () => ({
-  FetchInstrumentation: vi.fn((opts) => ({
-    ...opts,
-    name: "fetchInstrumentation",
-  })),
-}));
-
-vi.mock("@opentelemetry/instrumentation-user-interaction", () => ({
-  UserInteractionInstrumentation: vi.fn(() => "userInteractionInstrumentation"),
-}));
-
-vi.mock("./internals/hooks", () => ({
-  _beforeSend: vi.fn(() => "hooked"),
-}));
-
-describe("buildFaroInstrumentation", () => {
-  const validConfig = {
-    collectorUrl: "https://valid-url.com",
-    serviceName: "test-app",
-    detection: {
-      email: true,
-    },
-  };
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    console.warn = vi.fn();
-    console.error = vi.fn();
-    console.log = vi.fn();
-  });
-
-  it("returns undefined and warns if config is not provided", () => {
-    const result = buildFaroInstrumentation();
-    expect(console.warn).toHaveBeenCalledWith(
-      "observability config not set. Skipping Faro OpenTelemetry instrumentation.",
-    );
-    expect(result).toBeUndefined();
-  });
-
-  it("returns undefined and warns if collectorUrl is missing", () => {
-    const result = buildFaroInstrumentation({
-      ...validConfig,
-      collectorUrl: undefined!,
-    });
-    expect(console.warn).toHaveBeenCalledWith(
-      "collectorUrl not set. Skipping Faro OpenTelemetry instrumentation.",
-    );
-    expect(result).toBeUndefined();
-  });
-
-  it("returns undefined and errors if collectorUrl is invalid", () => {
-    const result = buildFaroInstrumentation({
-      ...validConfig,
-      collectorUrl: "not-a-url",
-    });
-    expect(console.error).toHaveBeenCalledWith(
-      "collectorUrl does not use a valid format. Skipping Faro OpenTelemetry instrumentation.",
-    );
-    expect(result).toBeUndefined();
-  });
-
-  it("defaults all detection to true if not provided", () => {
-    const config = {
-      ...validConfig,
-      detection: {},
-    };
-    buildFaroInstrumentation(config);
-    expect(initializeFaro).toHaveBeenCalledOnce();
-    expect(initializeFaro.mock.calls[0][0].beforeSend.toString()).toEqual(
-      _beforeSend(Object.values(redactors)).toString(),
-    );
-  });
-
-  it("sets beforeSend if detection.email is true", () => {
-    buildFaroInstrumentation({ ...validConfig, detection: { email: true } });
-    expect(initializeFaro).toHaveBeenCalledOnce();
-    expect(initializeFaro.mock.calls[0][0].beforeSend.toString()).toEqual(
-      _beforeSend(Object.values(redactors)).toString(),
-    );
-  });
-
-  it("does not set beforeSend if detection.email is false", () => {
-    buildFaroInstrumentation({ ...validConfig, detection: { email: false } });
-    expect(initializeFaro).toHaveBeenCalledOnce();
-    expect(initializeFaro.mock.calls[0][0].beforeSend.toString()).toEqual(
-      _beforeSend(
-        Object.entries(redactors)
-          .filter(([key]) => key !== "email")
-          .map(([, redactor]) => redactor),
-      ).toString(),
-    );
-  });
-
-  it("disables batching when collectorMode is 'single'", () => {
-    buildFaroInstrumentation({ ...validConfig, collectorMode: "single" });
-    expect(initializeFaro).toHaveBeenCalledWith(
-      expect.objectContaining({
-        batching: {
-          enabled: false,
-        },
-      }),
-    );
-  });
-
-  it("sets diagLogLevel if provided", async () => {
-    const { DiagLogLevel } = await import("@opentelemetry/api");
-    const setLoggerSpy = vi
-      .spyOn(await import("@opentelemetry/api"), "diag", "get")
-      .mockReturnValue({
-        setLogger: vi.fn(),
-      });
-
-    buildFaroInstrumentation({ ...validConfig, diagLogLevel: "DEBUG" });
-
-    expect(setLoggerSpy().setLogger).toHaveBeenCalledWith(
-      expect.anything(),
-      DiagLogLevel.DEBUG,
-    );
-  });
-
-  it("handles initialization failure and logs error", () => {
-    (initializeFaro as any).mockImplementationOnce(() => {
-      throw new Error("init failed");
-    });
-
-    const result = buildFaroInstrumentation(validConfig);
-    expect(console.error).toHaveBeenCalledWith(
-      "Error starting Faro OpenTelemetry instrumentation:",
-      expect.any(Error),
-    );
-    expect(result).toBeUndefined();
-  });
-
-  it("returns the faro object on successful initialization", () => {
-    const result = buildFaroInstrumentation(validConfig);
-    expect(console.log).toHaveBeenCalledWith(
-      "Faro OpenTelemetry instrumentation started successfully.",
-    );
-    expect(result).toEqual({ fakeFaro: true });
-  });
-
-  it("skips detection if all redactors are set to false", () => {
-    const config = {
-      ...validConfig,
-      detection: Object.fromEntries(
-        Object.keys(redactors).map((key) => [key, false]),
-      ),
-    };
-
-    buildFaroInstrumentation(config);
-
-    const cleanStringMock = vi.spyOn(detectionTools, "_cleanStringPII");
-
-    expect(initializeFaro).toHaveBeenCalledOnce();
-    expect(initializeFaro.mock.calls[0][0].beforeSend).toBeTruthy();
-
-    initializeFaro.mock.calls[0][0].beforeSend({
-      type: "log",
-      payload: { name: "eventName", timestamp: "a timestamp" },
-      meta: {},
-    });
-
-    expect(cleanStringMock).not.toHaveBeenCalled();
-  });
-
-  it("handles comma-separated corsTraceHeaders", async () => {
-    buildFaroInstrumentation({
-      ...validConfig,
-      corsTraceHeaders: "https://site1.com,https://site2.com",
-    });
-
-    const { FetchInstrumentation } = await import(
-      "@opentelemetry/instrumentation-fetch"
-    );
-    expect(FetchInstrumentation).toHaveBeenCalledWith(
-      expect.objectContaining({
-        propagateTraceHeaderCorsUrls: [
-          new RegExp("https://site1.com"),
-          new RegExp("https://site2.com"),
-        ],
-      }),
-    );
-  });
-});