koatty_trace/dist/index.d.ts

Full link tracking and error interception for koatty.

/*!
* @Author: richen
* @Date: 2025-06-05 16:25:32
* @License: BSD (3-Clause)
* @Copyright (c) - <richenlin(at)gmail.com>
* @HomePage: https://koatty.org/
*/
import { Instrumentation } from '@opentelemetry/instrumentation';
import { Koatty } from 'koatty_core';
import { KoattyContext } from 'koatty_core';
import { KoattyNext } from 'koatty_core';

/**
 * Trace middleware for Koatty framework that provides request tracing, topology analysis,
 * and request lifecycle management capabilities.
 *
 * @param {TraceOptions} options - Configuration options for the trace middleware
 * @param {Koatty} app - Koatty application instance
 * @returns {Function} Middleware function that handles request tracing and lifecycle
 *
 * Features:
 * - Request tracing with OpenTelemetry
 * - Request ID generation and propagation
 * - Service topology analysis
 * - Request lifecycle management
 * - Server shutdown handling
 * - Async hooks support for request context
 *
 * @export
 */
export declare function Trace(options: TraceOptions, app: Koatty): (ctx: KoattyContext, next: KoattyNext) => Promise<any>;

/**
 * TraceOptions
 *
 * @export
 * @interface TraceOptions
 */
declare interface TraceOptions {
    timeout?: number;
    requestIdHeaderName?: string;
    requestIdName?: string;
    idFactory?: Function;
    encoding?: string;
    enableTrace?: boolean;
    asyncHooks?: boolean;
    /**
     * Metrics configuration
     */
    metricsConf?: {
        /**
         * Metrics reporter function
         */
        reporter?: (metrics: {
            duration: number;
            status: number;
            path: string;
            attributes: Record<string, any>;
        }) => void;
        /**
         * Default attributes for metrics
         */
        defaultAttributes?: Record<string, any>;
        /**
         * Prometheus metrics endpoint (production only)
         */
        metricsEndpoint?: string;
        /**
         * Metrics report interval in milliseconds (default: 5000)
         */
        reportInterval?: number;
        /**
         * Prometheus metrics port (default: 9464)
         */
        metricsPort?: number;
    };
    /**
     * OpenTelemetry configuration
     */
    opentelemetryConf?: {
        /**
         * OTLP endpoint URL
         */
        endpoint?: string;
        /**
         * Whether to enable topology analysis (default: same as enableTrace)
         *
         */
        enableTopology?: boolean;
        /**
         * OTLP headers
         */
        headers?: Record<string, string>;
        /**
         * Resource attributes
         */
        resourceAttributes?: Record<string, string>;
        /**
         * Instrumentations to enable
         */
        instrumentations?: Instrumentation[];
        /**
         * Exporter timeout in milliseconds
         */
        timeout?: number;
        /**
         * Maximum lifetime for a span in milliseconds
         */
        spanTimeout?: number;
        /**
         * Maximum number of active spans in memory (default: 1000)
         */
        maxActiveSpans?: number;
        /**
         * Request attributes to be added to the span
         */
        spanAttributes?: (ctx: KoattyContext) => Record<string, any>;
        /**
         * Sampling rate (0.0 - 1.0)
         */
        samplingRate?: number;
        /**
         * Maximum number of spans in batch queue
         */
        batchMaxQueueSize?: number;
        /**
         * Maximum number of spans to export in one batch
         */
        batchMaxExportSize?: number;
        /**
         * Delay between batch exports in milliseconds
         */
        batchDelayMillis?: number;
        /**
         * Timeout for batch export in milliseconds
         */
        batchExportTimeout?: number;
    };
    /**
     * Retry configuration
     */
    retryConf?: {
        /**
         * Whether to enable retry mechanism (default: false)
         */
        enabled?: boolean;
        /**
         * Max retry count when error occurs (default: 3)
         */
        count?: number;
        /**
         * Retry interval in milliseconds (default: 1000)
         */
        interval?: number;
        /**
         * Custom function to determine if error should be retried
         */
        conditions?: (error: any) => boolean;
    };
}

export { }