@juspay/neurolink 9.23.0 → 9.25.0

package/dist/observability/exporterRegistry.js

@@ -0,0 +1,413 @@
+/**
+ * Exporter Registry
+ * Manages multiple observability exporters with circuit breaker protection
+ */
+import { logger } from "../utils/logger.js";
+import { AlwaysSampler } from "./sampling/samplers.js";
+/** Default timeout for exporter API calls (30 seconds) */
+const DEFAULT_EXPORT_TIMEOUT_MS = 30_000;
+/**
+ * Wrap a promise with a timeout. Rejects with a descriptive error if the
+ * promise does not settle within `timeoutMs` milliseconds.
+ */
+function withExportTimeout(promise, timeoutMs, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Export to '${label}' timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/**
+ * Registry for managing multiple observability exporters
+ * Includes circuit breaker protection to prevent cascading failures
+ */
+export class ExporterRegistry {
+    exporters = new Map();
+    defaultExporter = null;
+    sampler = new AlwaysSampler();
+    circuitBreakers = new Map();
+    circuitBreakerConfig = {
+        failureThreshold: 5,
+        resetTimeout: 30000, // 30 seconds
+    };
+    /**
+     * Register an exporter
+     */
+    register(exporter) {
+        this.exporters.set(exporter.getName(), exporter);
+    }
+    /**
+     * Unregister an exporter
+     */
+    unregister(name) {
+        return this.exporters.delete(name);
+    }
+    /**
+     * Get an exporter by name
+     */
+    get(name) {
+        return this.exporters.get(name);
+    }
+    /**
+     * Get all registered exporter names
+     */
+    getNames() {
+        return Array.from(this.exporters.keys());
+    }
+    /**
+     * Get total exporter count
+     */
+    getCount() {
+        return this.exporters.size;
+    }
+    /**
+     * Set the default exporter
+     */
+    setDefault(name) {
+        if (!this.exporters.has(name)) {
+            throw new Error(`Exporter '${name}' not registered`);
+        }
+        this.defaultExporter = name;
+    }
+    /**
+     * Get the default exporter
+     */
+    getDefault() {
+        if (!this.defaultExporter) {
+            return undefined;
+        }
+        return this.exporters.get(this.defaultExporter);
+    }
+    /**
+     * Set the sampler for the registry
+     */
+    setSampler(sampler) {
+        this.sampler = sampler;
+    }
+    /**
+     * Get the current sampler
+     */
+    getSampler() {
+        return this.sampler;
+    }
+    /**
+     * Configure the circuit breaker settings
+     * @param config - Partial circuit breaker configuration
+     */
+    configureCircuitBreaker(config) {
+        Object.assign(this.circuitBreakerConfig, config);
+    }
+    /**
+     * Check if circuit is open for an exporter
+     * @param exporterName - Name of the exporter
+     * @returns true if circuit is open (exporter should be skipped)
+     */
+    isCircuitOpen(exporterName) {
+        const breaker = this.circuitBreakers.get(exporterName);
+        if (!breaker) {
+            return false;
+        }
+        if (breaker.state === "open") {
+            // Check if we should try half-open
+            if (Date.now() - breaker.lastFailure >
+                this.circuitBreakerConfig.resetTimeout) {
+                breaker.state = "half-open";
+                logger.info(`[ExporterRegistry] Circuit half-open for ${exporterName}, attempting recovery`);
+                return false;
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Record a failure for an exporter's circuit breaker
+     * @param exporterName - Name of the exporter
+     */
+    recordFailure(exporterName) {
+        let breaker = this.circuitBreakers.get(exporterName);
+        if (!breaker) {
+            breaker = { failures: 0, lastFailure: 0, state: "closed" };
+            this.circuitBreakers.set(exporterName, breaker);
+        }
+        breaker.failures++;
+        breaker.lastFailure = Date.now();
+        if (breaker.failures >= this.circuitBreakerConfig.failureThreshold) {
+            breaker.state = "open";
+            logger.warn(`[ExporterRegistry] Circuit opened for ${exporterName} after ${breaker.failures} failures`);
+        }
+    }
+    /**
+     * Record a success for an exporter's circuit breaker
+     * Resets the circuit to closed state
+     * @param exporterName - Name of the exporter
+     */
+    recordSuccess(exporterName) {
+        const breaker = this.circuitBreakers.get(exporterName);
+        if (breaker) {
+            if (breaker.state === "half-open") {
+                logger.info(`[ExporterRegistry] Circuit closed for ${exporterName} after successful recovery`);
+            }
+            breaker.failures = 0;
+            breaker.state = "closed";
+        }
+    }
+    /**
+     * Get circuit breaker status for an exporter
+     * @param exporterName - Name of the exporter
+     * @returns Circuit breaker state or undefined if not tracked
+     */
+    getCircuitBreakerStatus(exporterName) {
+        return this.circuitBreakers.get(exporterName);
+    }
+    /**
+     * Reset circuit breaker for an exporter
+     * @param exporterName - Name of the exporter
+     */
+    resetCircuitBreaker(exporterName) {
+        this.circuitBreakers.delete(exporterName);
+    }
+    /**
+     * Export span to all registered exporters
+     * Applies sampling and circuit breaker protection before export
+     */
+    async exportToAll(span) {
+        const results = new Map();
+        // Apply sampling
+        if (!this.sampler.shouldSample(span)) {
+            // Return empty results if not sampled
+            return results;
+        }
+        const exportPromises = Array.from(this.exporters.entries()).map(async ([name, exporter]) => {
+            // Check circuit breaker before attempting export
+            if (this.isCircuitOpen(name)) {
+                results.set(name, {
+                    success: false,
+                    exportedCount: 0,
+                    failedCount: 1,
+                    errors: [
+                        {
+                            spanId: span.spanId,
+                            error: "Circuit breaker open - exporter temporarily disabled",
+                            retryable: true,
+                        },
+                    ],
+                    durationMs: 0,
+                });
+                return;
+            }
+            if (exporter.isInitialized()) {
+                try {
+                    const result = await withExportTimeout(exporter.exportSpan(span), DEFAULT_EXPORT_TIMEOUT_MS, name);
+                    results.set(name, result);
+                    // Record success or failure based on result
+                    if (result.success) {
+                        this.recordSuccess(name);
+                    }
+                    else {
+                        this.recordFailure(name);
+                    }
+                }
+                catch (error) {
+                    this.recordFailure(name);
+                    results.set(name, {
+                        success: false,
+                        exportedCount: 0,
+                        failedCount: 1,
+                        errors: [
+                            {
+                                spanId: span.spanId,
+                                error: error instanceof Error ? error.message : String(error),
+                                retryable: true,
+                            },
+                        ],
+                        durationMs: 0,
+                    });
+                }
+            }
+            else {
+                logger.debug(`[ExporterRegistry] Skipping uninitialized exporter '${name}' for span ${span.spanId}`);
+            }
+        });
+        await Promise.all(exportPromises);
+        return results;
+    }
+    /**
+     * Export span to a specific exporter
+     * Applies sampling and circuit breaker protection
+     */
+    async exportTo(name, span) {
+        const exporter = this.exporters.get(name);
+        if (!exporter) {
+            return null;
+        }
+        if (!exporter.isInitialized()) {
+            logger.debug(`[ExporterRegistry] Skipping uninitialized exporter '${name}' for span ${span.spanId}`);
+            return null;
+        }
+        // Check circuit breaker before attempting export
+        if (this.isCircuitOpen(name)) {
+            return {
+                success: false,
+                exportedCount: 0,
+                failedCount: 1,
+                errors: [
+                    {
+                        spanId: span.spanId,
+                        error: "Circuit breaker open - exporter temporarily disabled",
+                        retryable: true,
+                    },
+                ],
+                durationMs: 0,
+            };
+        }
+        // Apply sampling
+        if (!this.sampler.shouldSample(span)) {
+            return {
+                success: true,
+                exportedCount: 0,
+                failedCount: 0,
+                durationMs: 0,
+            };
+        }
+        try {
+            const result = await withExportTimeout(exporter.exportSpan(span), DEFAULT_EXPORT_TIMEOUT_MS, name);
+            if (result.success) {
+                this.recordSuccess(name);
+            }
+            else {
+                this.recordFailure(name);
+            }
+            return result;
+        }
+        catch (error) {
+            this.recordFailure(name);
+            return {
+                success: false,
+                exportedCount: 0,
+                failedCount: 1,
+                errors: [
+                    {
+                        spanId: span.spanId,
+                        error: error instanceof Error ? error.message : String(error),
+                        retryable: true,
+                    },
+                ],
+                durationMs: 0,
+            };
+        }
+    }
+    /**
+     * Initialize all exporters
+     */
+    async initializeAll() {
+        const results = await Promise.allSettled(Array.from(this.exporters.entries()).map(([name, e]) => e.initialize().catch((err) => {
+            logger.error(`[ExporterRegistry] Failed to initialize exporter '${name}':`, err);
+            throw err;
+        })));
+        for (const result of results) {
+            if (result.status === "rejected") {
+                logger.warn(`[ExporterRegistry] One or more exporters failed to initialize`);
+                break;
+            }
+        }
+    }
+    /**
+     * Shutdown all exporters
+     */
+    async shutdownAll() {
+        const results = await Promise.allSettled(Array.from(this.exporters.entries()).map(([name, e]) => e.shutdown().catch((err) => {
+            logger.error(`[ExporterRegistry] Failed to shutdown exporter '${name}':`, err);
+            throw err;
+        })));
+        for (const result of results) {
+            if (result.status === "rejected") {
+                logger.warn(`[ExporterRegistry] One or more exporters failed to shutdown`);
+                break;
+            }
+        }
+    }
+    /**
+     * Flush all exporters
+     */
+    async flushAll() {
+        const results = await Promise.allSettled(Array.from(this.exporters.entries()).map(([name, e]) => e.flush().catch((err) => {
+            logger.error(`[ExporterRegistry] Failed to flush exporter '${name}':`, err);
+            throw err;
+        })));
+        for (const result of results) {
+            if (result.status === "rejected") {
+                logger.warn(`[ExporterRegistry] One or more exporters failed to flush`);
+                break;
+            }
+        }
+    }
+    /**
+     * Get health status of all exporters
+     */
+    async healthCheckAll() {
+        const results = new Map();
+        const healthPromises = Array.from(this.exporters.entries()).map(async ([name, exporter]) => {
+            const status = await exporter.healthCheck();
+            results.set(name, status);
+        });
+        await Promise.all(healthPromises);
+        return results;
+    }
+    /**
+     * Check if all exporters are healthy
+     */
+    async isHealthy() {
+        const statuses = await this.healthCheckAll();
+        return Array.from(statuses.values()).every((s) => s.healthy);
+    }
+    /**
+     * Get total pending spans across all exporters
+     */
+    getTotalPendingSpans() {
+        let total = 0;
+        const exporterArray = Array.from(this.exporters.values());
+        for (const exporter of exporterArray) {
+            total += exporter.getPendingCount();
+        }
+        return total;
+    }
+    /**
+     * Clear all registered exporters and reset state
+     * (For testing and cleanup)
+     */
+    clear() {
+        this.exporters.clear();
+        this.defaultExporter = null;
+        this.circuitBreakers.clear();
+        this.sampler = new AlwaysSampler();
+    }
+}
+/**
+ * Global exporter registry instance (singleton pattern from main)
+ */
+let globalRegistry = null;
+/**
+ * Get the global exporter registry instance
+ */
+export function getExporterRegistry() {
+    if (!globalRegistry) {
+        globalRegistry = new ExporterRegistry();
+    }
+    return globalRegistry;
+}
+/**
+ * Reset the global exporter registry (for testing)
+ */
+export function resetExporterRegistry() {
+    if (globalRegistry) {
+        globalRegistry.clear();
+    }
+    globalRegistry = null;
+}

package/dist/observability/exporters/arizeExporter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Arize Exporter
+ * Exports spans to Arize ML monitoring platform
+ */
+import type { ArizeExporterConfig, ExporterHealthStatus, ExportResult, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Arize exporter for ML monitoring and prediction logs
+ * Supports feature tracking and model performance monitoring
+ */
+export declare class ArizeExporter extends BaseExporter {
+    private readonly spaceKey;
+    private readonly apiKey;
+    private readonly modelId;
+    private readonly modelVersion;
+    private readonly endpoint;
+    constructor(config: ArizeExporterConfig);
+    initialize(): Promise<void>;
+    exportSpan(span: SpanData): Promise<ExportResult>;
+    exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Verify connectivity to Arize API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Convert span to Arize prediction log format
+     */
+    private convertToArizePrediction;
+}

package/dist/observability/exporters/arizeExporter.js

@@ -0,0 +1,138 @@
+/**
+ * Arize Exporter
+ * Exports spans to Arize ML monitoring platform
+ */
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Arize exporter for ML monitoring and prediction logs
+ * Supports feature tracking and model performance monitoring
+ */
+export class ArizeExporter extends BaseExporter {
+    spaceKey;
+    apiKey;
+    modelId;
+    modelVersion;
+    endpoint = "https://api.arize.com/v1";
+    constructor(config) {
+        super("arize", config);
+        this.spaceKey = config.spaceKey;
+        this.apiKey = config.apiKey;
+        this.modelId = config.modelId ?? "neurolink-ai";
+        this.modelVersion = config.modelVersion ?? "1.0.0";
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 10000);
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            const prediction = this.convertToArizePrediction(span);
+            const response = await fetch(`${this.endpoint}/log`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "space-key": this.spaceKey,
+                },
+                body: JSON.stringify(prediction),
+            });
+            if (!response.ok) {
+                throw new Error(`Export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(1, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult([span.spanId], error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async exportBatch(spans) {
+        // Arize's /v1/log endpoint does not support batch payloads, so we send
+        // individual requests in parallel. This is intentional — not a missed
+        // optimization.
+        const results = await Promise.all(spans.map((s) => this.exportSpan(s)));
+        const successful = results.filter((r) => r.success).length;
+        const failed = spans.length - successful;
+        return {
+            success: failed === 0,
+            exportedCount: successful,
+            failedCount: failed,
+            errors: results.flatMap((r) => r.errors ?? []),
+            durationMs: results.reduce((sum, r) => sum + r.durationMs, 0),
+        };
+    }
+    async flush() {
+        if (!this.initialized || this.buffer.length === 0) {
+            return;
+        }
+        const spans = [...this.buffer];
+        this.buffer = [];
+        await this.exportBatch(spans);
+    }
+    async shutdown() {
+        await this.flush();
+        this.stopFlushInterval();
+        this.initialized = false;
+    }
+    async healthCheck() {
+        try {
+            await this.withRetry(() => this.ping(), "health check");
+            return this.createHealthStatus(true);
+        }
+        catch {
+            return this.createHealthStatus(false, ["Health check failed"]);
+        }
+    }
+    /**
+     * Verify connectivity to Arize API
+     */
+    async ping() {
+        const response = await fetch(`${this.endpoint}/health`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "space-key": this.spaceKey,
+            },
+        });
+        if (!response.ok && response.status !== 404) {
+            // 404 is acceptable as health endpoint may not exist
+            throw new Error(`Arize API unreachable: ${response.status}`);
+        }
+    }
+    /**
+     * Convert span to Arize prediction log format
+     */
+    convertToArizePrediction(span) {
+        return {
+            space_key: this.spaceKey,
+            model_id: span.attributes["ai.model"] ?? this.modelId,
+            model_version: this.modelVersion,
+            prediction_id: span.spanId,
+            prediction_timestamp: new Date(span.startTime).getTime(),
+            features: {
+                provider: span.attributes["ai.provider"],
+                temperature: span.attributes["ai.temperature"],
+                max_tokens: span.attributes["ai.max_tokens"],
+                user_id: span.attributes["user.id"],
+                session_id: span.attributes["session.id"],
+            },
+            prediction: {
+                input: span.attributes["input"],
+                output: span.attributes["output"],
+            },
+            tags: {
+                span_type: span.type,
+                environment: this.config.environment,
+            },
+            latency_ms: span.durationMs,
+            token_count: {
+                prompt: span.attributes["ai.tokens.input"],
+                completion: span.attributes["ai.tokens.output"],
+                total: span.attributes["ai.tokens.total"],
+            },
+        };
+    }
+}

package/dist/observability/exporters/baseExporter.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Abstract base class for all observability exporters
+ * Follows NeuroLink's factory pattern and Mastra's unified exporter interface
+ */
+import type { ExporterConfig, ExporterHealthStatus, ExportResult, SpanData } from "../types/index.js";
+/**
+ * Abstract base class for all observability exporters
+ * Provides common functionality: buffering, flush intervals, health checks, retry logic
+ */
+export declare abstract class BaseExporter {
+    protected readonly name: string;
+    protected readonly config: ExporterConfig;
+    protected initialized: boolean;
+    protected buffer: SpanData[];
+    protected readonly maxBufferSize: number;
+    protected readonly retries: number;
+    protected flushInterval: ReturnType<typeof setInterval> | null;
+    protected lastExportTime: number;
+    constructor(name: string, config: ExporterConfig);
+    /**
+     * Initialize the exporter connection
+     * Must be called before exporting spans
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Export a single span
+     * @param span - The span data to export
+     */
+    abstract exportSpan(span: SpanData): Promise<ExportResult>;
+    /**
+     * Export multiple spans in batch
+     * @param spans - Array of span data to export
+     */
+    abstract exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    /**
+     * Flush all buffered spans
+     */
+    abstract flush(): Promise<void>;
+    /**
+     * Shutdown the exporter gracefully
+     * Should flush remaining spans before closing
+     */
+    abstract shutdown(): Promise<void>;
+    /**
+     * Check exporter health status
+     * Implementations should make an actual API call to verify connectivity
+     */
+    abstract healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Ping the exporter's backend to verify connectivity
+     * Override this in subclasses to provide backend-specific health check
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Buffer a span for batch export
+     * Triggers flush if buffer is full
+     */
+    protected bufferSpan(span: SpanData): void;
+    /**
+     * Start automatic flush interval
+     * @param intervalMs - Interval in milliseconds between flushes
+     */
+    protected startFlushInterval(intervalMs: number): void;
+    /**
+     * Stop the automatic flush interval
+     */
+    protected stopFlushInterval(): void;
+    /**
+     * Get exporter name
+     */
+    getName(): string;
+    /**
+     * Check if exporter is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get number of pending spans in buffer
+     */
+    getPendingCount(): number;
+    /**
+     * Get last export timestamp
+     */
+    getLastExportTime(): number;
+    /**
+     * Create a standard export result for success
+     */
+    protected createSuccessResult(exportedCount: number, durationMs: number): ExportResult;
+    /**
+     * Create a standard export result for failure
+     */
+    protected createFailureResult(spanIds: string[], error: string, durationMs: number, retryable?: boolean): ExportResult;
+    /**
+     * Create a standard health status
+     */
+    protected createHealthStatus(healthy: boolean, errors?: string[]): ExporterHealthStatus;
+    /**
+     * Execute an operation with exponential backoff retry
+     * @param operation - The async operation to execute
+     * @param operationName - Name for logging purposes
+     * @returns The result of the operation
+     * @throws The last error if all retries fail
+     */
+    protected withRetry<T>(operation: () => Promise<T>, operationName: string): Promise<T>;
+}
+/**
+ * No-op exporter for when observability is disabled
+ * Provides zero-overhead behavior
+ */
+export declare class NoOpExporter extends BaseExporter {
+    constructor();
+    initialize(): Promise<void>;
+    exportSpan(_span: SpanData): Promise<ExportResult>;
+    exportBatch(_spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+}