@ogcio/o11y-sdk-node 0.4.2 → 0.6.0

package/lib/index.ts

@@ -1,118 +0,0 @@
-import type { Metadata } from "@grpc/grpc-js";
-
-export interface NodeSDKConfig {
-  /**
-   * The opentelemetry collector entrypoint GRPC url.
-   * If the collectorUrl is null or undefined, the instrumentation will not be activated.
-   * @example http://alloy:4317
-   */
-  collectorUrl: string;
-  /**
-   * Name of your application used for the collector to group logs and naming traces
-   */
-  serviceName?: string;
-  /**
-   * Version of your application used for the collector to group logs and naming traces
-   */
-  serviceVersion?: string;
-  /**
-   * Diagnostic log level for the internal runtime instrumentation
-   *
-   * @type string
-   * @default INFO
-   */
-  diagLogLevel?: SDKLogLevel;
-  /**
-   * Collector signals processing mode.
-   * single: makes an http/grpc request for each signal, and it is immediately processed inside grafana
-   * batch: sends multiple signals within a time window, optimized to reduce http/grpc calls in production
-   *
-   * @type string
-   * @default batch
-   */
-  collectorMode?: SDKCollectorMode;
-  /**
-   * Array of not traced urls.
-   *
-   * @type {SamplerCondition}
-   * @default []
-   */
-  ignoreUrls?: SamplerCondition[];
-
-  /**
-   * Object containing static properties or functions used to evaluate custom attributes for all logs and traces.
-   */
-  spanAttributes?: Record<
-    string,
-    SignalAttributeValue | (() => SignalAttributeValue)
-  >;
-
-  /**
-   * Object containing static properties used as resources attributes for the Node SDK initialization.
-   */
-  resourceAttributes?: Record<string, SignalAttributeValue>;
-
-  /**
-   * Faction value from 0 to 1, used by TraceIdRatioBasedSampler which it deterministically samples a percentage of traces that you pass in as a parameter.
-   *
-   * @default 1
-   */
-  traceRatio?: number;
-
-  /**
-   * Flag to enable or disable the tracing for node:fs module
-   *
-   * @default false disabling `instrumentation-fs` because it bloating the traces
-   */
-  enableFS?: boolean;
-
-  /**
-   * Protocol used to send signals.
-   *
-   * @default grpc
-   */
-  protocol?: SDKProtocol;
-
-  /**
-   * Grpc Metadata for the grpc-js client.
-   *
-   * @default { waitForReady: true }
-   */
-  grpcMetadata?: Metadata;
-
-  /**
-   * Enable/Disable PII detection for GDPR data
-   */
-  detection?: {
-    /**
-     * Redact email address
-     * @default true
-     */
-    email?: boolean;
-    /**
-     * Redact IPv4/IPv6 addresses
-     * @default true
-     */
-    ip?: boolean;
-  };
-}
-
-export interface SamplerCondition {
-  type: "endsWith" | "includes" | "equals";
-  url: string;
-}
-
-export type SignalAttributeValue = string | number | boolean;
-
-export type SDKCollectorMode = "single" | "batch";
-
-export type SDKProtocol = "grpc" | "http" | "console";
-
-export type SDKLogLevel =
-  | "NONE"
-  | "ERROR"
-  | "WARN"
-  | "INFO"
-  | "DEBUG"
-  | "VERBOSE"
-  | "ALL";

package/lib/instrumentation.node.ts

@@ -1,115 +0,0 @@
-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 type { Exporters } from "./exporter/index.js";
-import type { NodeSDKConfig } from "./index.js";
-import { _shutdownHook } from "./internals/hooks.js";
-import { ObservabilityResourceDetector } from "./resource.js";
-import { UrlSampler } from "./url-sampler.js";
-
-export default async function buildNodeInstrumentation(
-  config?: NodeSDKConfig,
-): Promise<NodeSDK | undefined> {
-  if (!config) {
-    console.warn(
-      "observability config not set. Skipping NodeJS OpenTelemetry instrumentation.",
-    );
-    return;
-  }
-
-  if (!config.collectorUrl) {
-    console.warn(
-      "collectorUrl not set. Skipping NodeJS OpenTelemetry instrumentation.",
-    );
-    return;
-  }
-
-  if (!isUrl(config.collectorUrl)) {
-    console.error(
-      "collectorUrl does not use a valid format. Skipping NodeJS OpenTelemetry instrumentation.",
-    );
-    return;
-  }
-
-  // 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,
-    remoteParentSampled: urlSampler,
-    remoteParentNotSampled: new AlwaysOffSampler(),
-    localParentSampled: urlSampler,
-    localParentNotSampled: new AlwaysOffSampler(),
-  });
-
-  diag.setLogger(
-    new DiagConsoleLogger(),
-    config.diagLogLevel ? DiagLogLevel[config.diagLogLevel] : DiagLogLevel.INFO,
-  );
-
-  try {
-    const nodeSdkInstrumentation = getNodeAutoInstrumentations({
-      "@opentelemetry/instrumentation-fs": {
-        enabled: config.enableFS ?? false,
-      },
-    });
-
-    let exporter: Exporters;
-
-    if (config.protocol === "http") {
-      exporter = buildHttpExporters(config);
-    } else if (config.protocol === "console") {
-      exporter = buildConsoleExporters(config);
-    } else {
-      exporter = await buildGrpcExporters(config);
-    }
-
-    const sdk = new NodeSDK({
-      resourceDetectors: [
-        new ObservabilityResourceDetector(config.resourceAttributes),
-      ],
-      spanProcessors: exporter.spans,
-      serviceName: config.serviceName,
-      metricReader: exporter.metrics,
-      logRecordProcessors: exporter.logs,
-      sampler: mainSampler,
-      textMapPropagator: new W3CTraceContextPropagator(),
-      instrumentations: [nodeSdkInstrumentation],
-    });
-
-    sdk.start();
-    console.log("NodeJS OpenTelemetry instrumentation started successfully.");
-
-    _shutdownHook(sdk);
-    return sdk;
-  } catch (error) {
-    console.error(
-      "Error starting NodeJS OpenTelemetry instrumentation:",
-      error,
-    );
-  }
-}
-
-function isUrl(url: string): boolean {
-  try {
-    new URL(url);
-    return true;
-  } catch (_) {
-    return false;
-  }
-}

package/lib/internals/hooks.ts

@@ -1,14 +0,0 @@
-export function _shutdownHook(sdk: { shutdown: () => Promise<void> }) {
-  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/lib/internals/redaction/pii-detection.ts

@@ -1,113 +0,0 @@
-import type { AnyValue, AnyValueMap } from "@opentelemetry/api-logs";
-import { Redactor } from "./redactors/index.js";
-
-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.
- */
-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.
- *
- * @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 {string} The cleaned string with any configured PII replaced by `[REDACTED PII_TYPE]`.
- */
-export function _cleanStringPII(
-  value: string,
-  source: PIISource,
-  redactors: Redactor[],
-): string {
-  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,
-  );
-}
-
-export function _recursiveObjectClean<T extends AnyValue>(
-  value: T,
-  source: PIISource,
-  redactors: Redactor[],
-): T {
-  if (typeof value === "string") {
-    return _cleanStringPII(value, source, redactors) as T;
-  }
-
-  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, source, redactors);
-      return encoder.encode(sanitized) as T;
-    } catch {
-      return value;
-    }
-  }
-
-  if (Array.isArray(value)) {
-    return value.map((value) =>
-      _recursiveObjectClean(value, source, redactors),
-    ) as T;
-  }
-
-  if (typeof value === "object") {
-    const sanitized: AnyValueMap = {};
-    for (const [key, val] of Object.entries(value)) {
-      sanitized[key] = _recursiveObjectClean(val, source, redactors);
-    }
-    return sanitized as T;
-  }
-
-  return value;
-}

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

@@ -1,58 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,68 +0,0 @@
-import { _getPIICounterRedactionMetric } from "../../shared-metrics.js";
-
-// Generous IP address matchers (might match some invalid addresses like 192.168.01.1)
-const IPV4_REGEX =
-  /(?<!\d)(?:%[0-9A-Fa-f]{2})?(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}(?:%[0-9A-Fa-f]{2})?(?!\d)/gi;
-const IPV6_REGEX =
-  /(?<![0-9a-f:])(?:%[0-9A-Fa-f]{2})?((?:[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-Fa-f]{2})?(?![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,34 +0,0 @@
-import { Attributes, Counter } from "@opentelemetry/api";
-import { getMetric } from "../metrics.js";
-import { PIISource } from "./redaction/pii-detection.js";
-
-interface RedactionMetric extends Attributes {
-  /** Type of PII redacted (e.g., "email", "phone"). */
-  pii_type: string;
-  /** Domain part of the redacted PII (e.g., "gmail.com"). */
-  pii_email_domain?: string;
-  /** Source of the redaction (trace, log or metric). */
-  redaction_source: PIISource;
-  /** Format or structure of the redacted value. */
-  pii_format: "string" | "url";
-}
-
-// Cached singleton instance of the redaction counter metric
-let _redactedCounter: undefined | Counter;
-
-/**
- * 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", RedactionMetric>("counter", {
-    meterName: "o11y",
-    metricName: "o11y_pii_redaction",
-  });
-  return _redactedCounter;
-}

package/lib/metrics.ts

@@ -1,75 +0,0 @@
-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

@@ -1,34 +0,0 @@
-import { SdkLogRecord, 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: SdkLogRecord, _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

@@ -1,39 +0,0 @@
-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();
-  }
-}