@devilsdev/rag-pipeline-utils 2.6.2 → 2.7.0

package/dist/types/core/observability/event-logger.d.ts

@@ -0,0 +1,211 @@
+/**
+ * In-memory log of pipeline events (plugin and stage lifecycle, memory
+ * warnings, custom events) tagged with a session id. A session is started
+ * on the first event if startSession was not called.
+ */
+export class PipelineEventLogger {
+    _events: any[];
+    _sessionId: string;
+    /**
+     * Start a new session with a fresh id and start time. Existing events are kept.
+     * @returns {string} The new session id
+     */
+    startSession(): string;
+    _sessionStartTime: string;
+    /**
+     * Current time as an ISO 8601 string.
+     * @returns {string}
+     */
+    nowISO(): string;
+    /**
+     * Describe a value's size: length for arrays and strings, key count for
+     * objects, type only for null and primitives.
+     * @param {*} v - Value to describe
+     * @returns {{type: string, length?: number, keys?: number}}
+     */
+    getInputSize(v: any): {
+        type: string;
+        length?: number;
+        keys?: number;
+    };
+    /**
+     * Same as getInputSize.
+     * @param {*} v - Value to describe
+     * @returns {{type: string, length?: number, keys?: number}}
+     */
+    getResultSize(v: any): {
+        type: string;
+        length?: number;
+        keys?: number;
+    };
+    /**
+     * Record a debug-level plugin.start event with the input size and process info.
+     * @param {Object} event
+     * @param {string} event.pluginType - Plugin type, such as embedder or retriever
+     * @param {string} event.pluginName - Plugin name
+     * @param {*} [event.input] - Plugin input; only its size is recorded
+     * @param {Object<string, *>} [event.context={}] - Extra metadata
+     * @returns {void}
+     */
+    logPluginStart({ pluginType, pluginName, input, context }: {
+        pluginType: string;
+        pluginName: string;
+        input?: any;
+        context?: {
+            [x: string]: any;
+        };
+    }): void;
+    /**
+     * Record a debug-level plugin.end event. When the result is an array, or
+     * has a vectors array, its length is recorded as resultSize.vectorCount.
+     * @param {Object} event
+     * @param {string} event.pluginType - Plugin type
+     * @param {string} event.pluginName - Plugin name
+     * @param {number} [event.duration] - Duration in milliseconds
+     * @param {*} [event.result] - Plugin result; only its length is recorded
+     * @param {string} [event.status='success'] - Outcome
+     * @param {Object<string, *>} [event.context={}] - Extra metadata
+     * @returns {void}
+     */
+    logPluginEnd({ pluginType, pluginName, duration, result, status, context, }: {
+        pluginType: string;
+        pluginName: string;
+        duration?: number;
+        result?: any;
+        status?: string;
+        context?: {
+            [x: string]: any;
+        };
+    }): void;
+    /**
+     * Record an error-level plugin.error event with the error's name, message and code.
+     * @param {Object} event
+     * @param {string} event.pluginType - Plugin type
+     * @param {string} event.pluginName - Plugin name
+     * @param {number} [event.duration] - Duration in milliseconds
+     * @param {Error & {code?: string}} [event.error] - The error thrown
+     * @param {Object<string, *>} [event.context={}] - Extra metadata
+     * @returns {void}
+     */
+    logPluginError({ pluginType, pluginName, duration, error, context }: {
+        pluginType: string;
+        pluginName: string;
+        duration?: number;
+        error?: Error & {
+            code?: string;
+        };
+        context?: {
+            [x: string]: any;
+        };
+    }): void;
+    /**
+     * Record an info-level stage.start event.
+     * @param {string} stage - Stage name
+     * @returns {void}
+     */
+    logStageStart(stage: string): void;
+    /**
+     * Record a warn-level memory.warning event. usagePercentage is heapUsed
+     * (or rss if heapUsed is missing) in MB as a percentage of threshold.
+     * @param {Object} event
+     * @param {{heapUsed?: number, rss?: number}} event.memoryUsage - Memory figures in bytes, as from process.memoryUsage()
+     * @param {number} [event.threshold=512] - Threshold in MB
+     * @returns {void}
+     */
+    logMemoryWarning({ memoryUsage, threshold }: {
+        memoryUsage: {
+            heapUsed?: number;
+            rss?: number;
+        };
+        threshold?: number;
+    }): void;
+    /**
+     * Recorded events, oldest first, optionally filtered.
+     * @param {Object} [filters]
+     * @param {string} [filters.eventType]
+     * @param {string} [filters.severity]
+     * @param {string} [filters.pluginType]
+     * @param {string|number|Date} [filters.since] - Only events at or after this time
+     * @param {string|number|Date} [filters.until] - Only events at or before this time
+     * @param {number} [filters.limit] - Keep only the most recent `limit` events
+     * @returns {Object[]}
+     */
+    getEventHistory({ eventType, severity, pluginType, since, until, limit, }?: {
+        eventType?: string;
+        severity?: string;
+        pluginType?: string;
+        since?: string | number | Date;
+        until?: string | number | Date;
+        limit?: number;
+    }): any[];
+    /**
+     * Serialize the session id and the events matching the filters.
+     * @param {Object} [filters] - Same filters as getEventHistory
+     * @returns {string} JSON string with sessionId, eventCount and events
+     */
+    exportEvents(filters?: any): string;
+    /**
+     * Record an event of any type.
+     * @param {string} eventType - Event type
+     * @param {string} severity - Severity level
+     * @param {Object<string, *>} [metadata={}] - Event metadata
+     * @param {string} [message] - Message; defaults to 'Event: ' plus the event type
+     * @returns {this}
+     */
+    logEvent(eventType: string, severity: string, metadata?: {
+        [x: string]: any;
+    }, message?: string): this;
+    /**
+     * Remove all recorded events. The session id is kept.
+     * @returns {this}
+     */
+    clearHistory(): this;
+    /**
+     * Record an info-level stage.end event.
+     * @param {string} stage - Stage name
+     * @param {number} duration - Duration in milliseconds
+     * @param {Object<string, *>} [metadata={}] - Extra metadata merged into the event metadata
+     * @returns {this}
+     */
+    logStageEnd(stage: string, duration: number, metadata?: {
+        [x: string]: any;
+    }): this;
+    /**
+     * Current session id. Starts a session if none is active.
+     * @returns {string}
+     */
+    get sessionId(): string;
+    /**
+     * Session id, total event count, session start time and the distinct event
+     * types recorded. Starts a session if none is active.
+     * @returns {{sessionId: string, totalEvents: number, startTime: string, eventTypes: string[]}}
+     */
+    getSessionStats(): {
+        sessionId: string;
+        totalEvents: number;
+        startTime: string;
+        eventTypes: string[];
+    };
+}
+/**
+ * Event type names used by PipelineEventLogger. The logger also emits
+ * 'stage.end' and 'memory.warning', which have no entry here.
+ * @type {{PLUGIN_START: string, PLUGIN_END: string, PLUGIN_ERROR: string, STAGE_START: string, STAGE_ERROR: string}}
+ */
+export const EventTypes: {
+    PLUGIN_START: string;
+    PLUGIN_END: string;
+    PLUGIN_ERROR: string;
+    STAGE_START: string;
+    STAGE_ERROR: string;
+};
+/**
+ * Severity levels used by PipelineEventLogger. Memory warnings use 'warn',
+ * which has no entry here.
+ * @type {{DEBUG: string, INFO: string, ERROR: string}}
+ */
+export const EventSeverity: {
+    DEBUG: string;
+    INFO: string;
+    ERROR: string;
+};