@ogcio/o11y-sdk-node/lib/index.ts

Opentelemetry standard instrumentation SDK for NodeJS based project

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;
  };
}

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";