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

Opentelemetry standard instrumentation SDK for NodeJS based project

import type { Metadata } from "@grpc/grpc-js";
import { BasicRedactor } from "../../sdk-core/lib/index.js";
import type { GeoHeaderMap } from "../../sdk-core/lib/index.js";
import type { InstrumentationConfigMap } from "@opentelemetry/auto-instrumentations-node";
import type { Instrumentation } from "@opentelemetry/instrumentation";
import type { Sampler, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import type { BatchLogRecordProcessorOptions, LogRecordProcessor } from "@opentelemetry/sdk-logs";
import type { ContextManager, TextMapPropagator } from "@opentelemetry/api";
import { NodeSDK } from "@opentelemetry/sdk-node";
interface BaseNodeSDKConfig {
    /**
     * 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;
    /**
     * 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;
    metrics?: {
        /**
         * Delay in milliseconds for the metric reader to initiate metric collection.
         *
         * @default 60_000
         */
        exportIntervalMs?: number;
    };
    /**
     * Flag to enable or disable the tracing for node:fs module
     *
     * @default false disabling `instrumentation-fs` because it bloating the traces
     * @deprecated This option will be removed in a future version and is currently and replaced by the autoInstrumentationConfig option.
     */
    enableFS?: boolean;
    /**
     * Configuration object for auto instrumentations.
     * @default {"@opentelemetry/instrumentation-fs":{enabled:false}}
     */
    autoInstrumentationConfig?: InstrumentationConfigMap;
    /**
     * Additional custom instrumentations to be added to the NodeSDK
     * @default []
     */
    additionalInstrumentations?: Instrumentation[];
    /**
     * 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;
        /**
         * Redact PPSN (Personal Public Service Number)
         * @default true
         */
        ppsn?: boolean;
        /**
         * Custom redactors to be added together with the default ones
         * @default []
         */
        custom?: BasicRedactor[];
    };
    /**
     * Configuration for the pseudo-profiling span processor
     * @default {enabled:false}
     */
    pseudoProfiling?: {
        /**
         * Enable/Disable pseudo-profiling span processor
         * @default false
         */
        enabled: boolean;
    };
    /**
     * Additional span processors to prepend to the processing pipeline.
     * These run before the default OTLP exporters.
     * You may use this for vendor-specific processors (e.g. sentry).
     * @default []
     */
    prependSpanProcessors?: SpanProcessor[];
    /**
     * Additional log record processors to prepend to the pipeline.
     * @default []
     */
    prependLogProcessors?: LogRecordProcessor[];
    /**
     * Custom sampler factory function.
     * Receives the default o11y sampler and should return the sampler to use.
     * You may use this to wrap the default sampler with vendor-specific samplers.
     *
     * @default undefined (uses default sampler)
     */
    samplerWrapper?: (defaultSampler: Sampler) => Sampler;
    /**
     * Custom context manager to use, required by some vendors (e.g. sentry requires its own SentryContextManager).
     * @default undefined (uses AsyncLocalStorageContextManager from otel)
     */
    contextManager?: ContextManager;
    /**
     * Additional propagators to include in the composite propagator.
     * W3CTraceContextPropagator is always included by default.
     * @default []
     */
    additionalPropagators?: TextMapPropagator[];
    /**
     * Callback function that is invoked once the SDK has been started.
     *
     * @param sdk The started NodeSDK instance.
     */
    onSdkStarted?: (sdk: NodeSDK) => void;
    /**
     * Configuration for automatic geo enrichment from provider headers.
     *
     * When enabled, geo attributes are automatically added to spans, logs and metrics and
     * propagated downstream via the geo-baggage propagator.
     *
     * When disabled, you may still enrich individual signals manually with
     * `createGeoAttributesFromHeaders` / `createGeoAttributesFrom`.
     *
     * @default disabled
     */
    geoEnrichment?: {
        /**
         * Enable or disable automatic geo enrichment.
         * @default false
         */
        enabled: boolean;
        /** Header name mapping. Defaults to `CF_GEO_HEADERS`. */
        headerMap?: GeoHeaderMap;
        /** Geohash precision. */
        precision?: number;
    };
}
/**
 * Configuration for batch collector mode (default).
 * Sends multiple signals within a time window, optimized to reduce http/grpc calls in production.
 */
export interface BatchNodeSDKConfig extends BaseNodeSDKConfig {
    collectorMode?: "batch";
    /**
     * Configuration for the batch processor buffer.
     */
    batchProcessorsConfig?: Omit<BatchLogRecordProcessorOptions, "exporter">;
}
/**
 * Configuration for single collector mode.
 * Makes an http/grpc request for each signal, immediately processed inside grafana.
 */
export interface SingleNodeSDKConfig extends BaseNodeSDKConfig {
    collectorMode: "single";
    batchProcessorsConfig?: never;
}
export type NodeSDKConfig = BatchNodeSDKConfig | SingleNodeSDKConfig;
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";
export {};