arvo-core/dist/OpenTelemetry/index.d.ts

The core Arvo package which provides application tier core primitives and contract system for building production-grade event-driven application. Provides ArvoEvent (CloudEvents-compliant), ArvoContract for type-safe service interfaces, event factories, O

import { type Context, type Span, type SpanOptions, type Tracer } from '@opentelemetry/api';
import type { OpenTelemetryHeaders, TelemetryLogLevel } from './types';
/**
 * Singleton class for managing OpenTelemetry instrumentation across libraries
 */
export declare class ArvoOpenTelemetry {
    /** OpenTelemetry tracer instance for creating spans */
    tracer: Tracer;
    private static instance;
    private constructor();
    /**
     * Gets or creates the singleton instance of ArvoOpenTelemetry.
     * This method ensures only one instance of ArvoOpenTelemetry exists throughout the application.
     *
     * @param {Object} [config] - Optional configuration object for initializing the instance
     * @param {Tracer} [config.tracer] - Optional custom OpenTelemetry tracer instance.
     *                                   If not provided, defaults to a tracer with name 'arvo-instrumentation'
     *
     * @returns {ArvoOpenTelemetry} The singleton instance of ArvoOpenTelemetry
     *
     * @example
     * // Get instance with default tracer
     * const telemetry = ArvoOpenTelemetry.getInstance();
     *
     * @example
     * // Get instance with custom tracer
     * const customTracer = trace.getTracer('custom-tracer', '2.0.0');
     * const telemetry = ArvoOpenTelemetry.getInstance({ tracer: customTracer });
     *
     * @remarks
     * The tracer configuration is only applied when creating a new instance.
     * Subsequent calls with different tracer configurations will not modify the existing instance.
     */
    static getInstance(config?: {
        tracer?: Tracer;
    }): ArvoOpenTelemetry;
    /**
     * Forces a reinitialization of the ArvoOpenTelemetry instance.
     * Use this method with caution as it will affect all existing traces and spans.
     *
     * @param {Object} config - Configuration object for reinitializing the instance
     * @param {Tracer} [config.tracer] - Optional custom OpenTelemetry tracer instance
     * @param {boolean} [config.force=false] - If true, skips active span checks
     *
     * @throws {Error} If there are active spans and force is not set to true
     * @throws {Error} If called before instance initialization
     *
     * @example
     * // Safe reinitialization
     * const customTracer = trace.getTracer('new-tracer', '2.0.0');
     * ArvoOpenTelemetry.reinitialize({ tracer: customTracer });
     */
    static reinitialize(config: {
        tracer?: Tracer;
        force?: boolean;
    }): void;
    /**
     * Creates and manages an active span for a given operation. This function provides two modes of operation:
     * 1. Automatic span management (default): Handles span lifecycle, status, and error recording
     * 2. Manual span management: Gives full control to the user when disableSpanManagement is true
     *
     * @template F - Function type that accepts a Span parameter and returns a value
     * @param {Object} param - Configuration object for the span
     * @param {string} param.name - Name of the span to be created
     * @param {F} param.fn - Function to execute within the span context. Receives the span as a parameter
     * @param {SpanOptions} [param.spanOptions] - Optional configuration for the span creation
     * @param {boolean} [param.disableSpanManagement] - When true, disables automatic span lifecycle management
     * @param {Object} [param.context] - Optional context configuration for span inheritance
     * @param {string} param.context.inheritFrom - Specifies the type of context inheritance ('TRACE_HEADERS' | 'CONTEXT')
     * @param {OpenTelemetryHeaders} param.context.traceHeaders - Required when inheritFrom is 'TRACE_HEADERS'
     * @param {Context} param.context.context - Required when inheritFrom is 'CONTEXT'
     * @returns {ReturnType<F>} The return value of the executed function
     */
    startActiveSpan<F extends (span: Span) => unknown>(param: {
        name: string;
        fn: F;
        spanOptions?: SpanOptions;
        context?: {
            inheritFrom: 'TRACE_HEADERS';
            traceHeaders: OpenTelemetryHeaders;
        } | {
            inheritFrom: 'CONTEXT';
            context: Context;
        };
        disableSpanManagement?: boolean;
    }): ReturnType<F>;
}
/**
 * Logs a message to a span with additional parameters.
 * @param params - The parameters for the log message.
 * @param span - The span to log the message to. If not provided, the active span is used.
 *               If no active span is available, the message is logged to the console.
 */
export declare const logToSpan: (params: {
    level: TelemetryLogLevel;
    message: string;
    [key: string]: string;
}, span?: Span | undefined) => void;
/**
 * Logs an exception to a span and sets exception-related attributes.
 * @param error - The error object to be logged.
 * @param span - The span to log the exception to. If not provided, the active span is used.
 *               If no active span is available, the error is logged to the console.
 */
export declare const exceptionToSpan: (error: Error, span?: Span | undefined) => void;
/**
 * A constant representing a null or not applicable value in OpenTelemetry context.
 */
export declare const OTelNull = "N/A";
/**
 * Retrieves the current OpenTelemetry headers from the active context.
 * @returns An object containing the traceparent and tracestate headers.
 */
export declare function currentOpenTelemetryHeaders(): OpenTelemetryHeaders;
export declare const getOtelHeaderFromSpan: (span: Span) => OpenTelemetryHeaders;
export declare const makeOpenTelemetryContextContext: (traceparent: string, tracestate: string | null) => Context;