@juspay/neurolink 9.23.0 → 9.25.0

package/dist/observability/exporters/sentryExporter.js

@@ -0,0 +1,165 @@
+/**
+ * Sentry Exporter
+ * Exports spans to Sentry error tracking and performance platform
+ */
+import { logger } from "../../utils/logger.js";
+import { SpanStatus } from "../types/spanTypes.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Sentry exporter for error tracking and performance monitoring
+ * Captures AI errors as exceptions and traces as transactions
+ */
+export class SentryExporter extends BaseExporter {
+    dsn;
+    tracesSampleRate;
+    release;
+    sentryHub = null;
+    constructor(config) {
+        super("sentry", config);
+        this.dsn = config.dsn;
+        this.tracesSampleRate = config.tracesSampleRate ?? 1.0;
+        this.release = config.release;
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Dynamically import Sentry to avoid bundling issues
+        // @sentry/node is an optional peer dependency
+        const sentry = await this.loadSentry();
+        if (sentry) {
+            sentry.init({
+                dsn: this.dsn,
+                tracesSampleRate: this.tracesSampleRate,
+                release: this.release,
+                environment: this.config.environment ?? "production",
+            });
+            this.sentryHub = sentry;
+        }
+        this.initialized = true;
+    }
+    /**
+     * Load Sentry SDK dynamically as an optional dependency
+     * @returns Sentry module or null if not installed
+     */
+    async loadSentry() {
+        try {
+            // Use standard dynamic import for optional peer dependency
+            // @ts-expect-error - @sentry/node is an optional peer dependency
+            const sentry = await import("@sentry/node");
+            return sentry;
+        }
+        catch {
+            logger.warn("[Sentry] Sentry SDK not installed. Install @sentry/node to use SentryExporter.");
+            return null;
+        }
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        if (!this.sentryHub) {
+            // Sentry not available, just succeed silently
+            return this.createSuccessResult(0, Date.now() - startTime);
+        }
+        try {
+            const Sentry = this.sentryHub;
+            // For errors, capture as Sentry exception
+            if (span.status === SpanStatus.ERROR) {
+                Sentry.withScope((scope) => {
+                    scope.setTags({
+                        "ai.provider": span.attributes["ai.provider"] ?? "",
+                        "ai.model": span.attributes["ai.model"] ?? "",
+                        "span.type": span.type,
+                    });
+                    scope.setContext("ai", {
+                        tokens: {
+                            input: span.attributes["ai.tokens.input"],
+                            output: span.attributes["ai.tokens.output"],
+                            total: span.attributes["ai.tokens.total"],
+                        },
+                        cost: span.attributes["ai.cost.total"],
+                        duration_ms: span.durationMs,
+                    });
+                    if (span.attributes["user.id"]) {
+                        scope.setUser({
+                            id: span.attributes["user.id"],
+                        });
+                    }
+                    Sentry.captureException(new Error(span.statusMessage ?? "AI operation failed"));
+                });
+            }
+            // Create Sentry transaction for performance tracking
+            const transaction = Sentry.startInactiveSpan({
+                name: span.name,
+                op: span.type,
+                startTime: new Date(span.startTime).getTime() / 1000,
+                attributes: {
+                    "ai.provider": span.attributes["ai.provider"],
+                    "ai.model": span.attributes["ai.model"],
+                    "ai.tokens.total": span.attributes["ai.tokens.total"],
+                    "ai.cost.total": span.attributes["ai.cost.total"],
+                },
+            });
+            // End the transaction
+            if (span.endTime) {
+                transaction.end(new Date(span.endTime).getTime() / 1000);
+            }
+            else {
+                transaction.end();
+            }
+            return this.createSuccessResult(1, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult([span.spanId], error instanceof Error ? error.message : String(error), Date.now() - startTime, false);
+        }
+    }
+    async exportBatch(spans) {
+        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.buffer.length > 0) {
+            const spans = [...this.buffer];
+            this.buffer = [];
+            await this.exportBatch(spans);
+        }
+        // Flush Sentry's internal buffer
+        if (this.sentryHub) {
+            await this.sentryHub.flush(2000);
+        }
+    }
+    async shutdown() {
+        await this.flush();
+        // Close Sentry SDK
+        if (this.sentryHub) {
+            await this.sentryHub.close(2000);
+        }
+        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 Sentry SDK is functional
+     */
+    async ping() {
+        if (!this.sentryHub) {
+            throw new Error("Sentry SDK not initialized");
+        }
+        // Sentry SDK is available, consider it healthy
+        // Note: Sentry doesn't have a simple ping endpoint, but the SDK initialization verifies DSN
+    }
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Observability Module
+ * Multi-platform observability with OpenTelemetry integration
+ */
+export { ExporterRegistry, getExporterRegistry, resetExporterRegistry, } from "./exporterRegistry.js";
+export { ArizeExporter } from "./exporters/arizeExporter.js";
+export { BaseExporter, NoOpExporter } from "./exporters/baseExporter.js";
+export { BraintrustExporter } from "./exporters/braintrustExporter.js";
+export { DatadogExporter } from "./exporters/datadogExporter.js";
+export { LaminarExporter } from "./exporters/laminarExporter.js";
+export { LangfuseExporter } from "./exporters/langfuseExporter.js";
+export { LangSmithExporter } from "./exporters/langsmithExporter.js";
+export { OtelExporter } from "./exporters/otelExporter.js";
+export { PostHogExporter } from "./exporters/posthogExporter.js";
+export { SentryExporter } from "./exporters/sentryExporter.js";
+export { getMetricsAggregator, type LatencyStats, MetricsAggregator, type MetricsAggregatorConfig, type MetricsSummary, type ModelCostStats, type ProviderCostStats, resetMetricsAggregator, type TimeWindowStats, } from "./metricsAggregator.js";
+export { OtelBridge } from "./otelBridge.js";
+export { BaseRetryPolicy, CircuitBreakerAwarePolicy, ExponentialBackoffPolicy, FixedDelayPolicy, LinearBackoffPolicy, NoRetryPolicy, type RetryContext, type RetryDecision, RetryExecutor, type RetryPolicy, RetryPolicyFactory, } from "./retryPolicy.js";
+export { AlwaysSampler, AttributeBasedSampler, CompositeSampler, CustomSampler, ErrorOnlySampler, NeverSampler, PrioritySampler, RatioSampler, type Sampler, SamplerFactory, TraceIdRatioSampler, } from "./sampling/samplers.js";
+export { AttributeEnrichmentProcessor, BatchProcessor, CompositeProcessor, FilterProcessor, PassThroughProcessor, RedactionProcessor, type SpanProcessor, SpanProcessorFactory, TruncationProcessor, } from "./spanProcessor.js";
+export { enrichSpanWithTokenUsage, getTokenTracker, type ModelPricing, type ModelTokenStats, type ProviderTokenStats, resetTokenTracker, TokenTracker, type TokenUsageStats, } from "./tokenTracker.js";
+export type { ArizeExporterConfig, BraintrustExporterConfig, DatadogExporterConfig, ExportError, ExporterConfig, ExporterHealthStatus, ExporterPlugin, ExportResult, ExtendedObservabilityConfig, LaminarExporterConfig, LangfuseExporterConfig, LangSmithExporterConfig, OtelExporterConfig, OtelProtocol, PostHogExporterConfig, SamplerConfig, SamplingRule, SentryExporterConfig, } from "./types/exporterTypes.js";
+export type { TraceView } from "./metricsAggregator.js";
+export { AGENT_ATTRIBUTES, GENAI_ATTRIBUTES, type LangfuseSpan, type LangSmithRun, type OtelSpan, type SpanAttributes, type SpanData, type SpanEvent, type SpanLink, SpanStatus, SpanType, } from "./types/spanTypes.js";
+export { SpanSerializer } from "./utils/spanSerializer.js";

package/dist/observability/index.js

@@ -0,0 +1,31 @@
+/**
+ * Observability Module
+ * Multi-platform observability with OpenTelemetry integration
+ */
+// Core - Registry with singleton pattern
+export { ExporterRegistry, getExporterRegistry, resetExporterRegistry, } from "./exporterRegistry.js";
+export { ArizeExporter } from "./exporters/arizeExporter.js";
+// Exporters
+export { BaseExporter, NoOpExporter } from "./exporters/baseExporter.js";
+export { BraintrustExporter } from "./exporters/braintrustExporter.js";
+export { DatadogExporter } from "./exporters/datadogExporter.js";
+export { LaminarExporter } from "./exporters/laminarExporter.js";
+export { LangfuseExporter } from "./exporters/langfuseExporter.js";
+export { LangSmithExporter } from "./exporters/langsmithExporter.js";
+export { OtelExporter } from "./exporters/otelExporter.js";
+export { PostHogExporter } from "./exporters/posthogExporter.js";
+export { SentryExporter } from "./exporters/sentryExporter.js";
+// Metrics Aggregation with singleton pattern
+export { getMetricsAggregator, MetricsAggregator, resetMetricsAggregator, } from "./metricsAggregator.js";
+export { OtelBridge } from "./otelBridge.js";
+// Retry Policies
+export { BaseRetryPolicy, CircuitBreakerAwarePolicy, ExponentialBackoffPolicy, FixedDelayPolicy, LinearBackoffPolicy, NoRetryPolicy, RetryExecutor, RetryPolicyFactory, } from "./retryPolicy.js";
+// Sampling
+export { AlwaysSampler, AttributeBasedSampler, CompositeSampler, CustomSampler, ErrorOnlySampler, NeverSampler, PrioritySampler, RatioSampler, SamplerFactory, TraceIdRatioSampler, } from "./sampling/samplers.js";
+// Span Processing
+export { AttributeEnrichmentProcessor, BatchProcessor, CompositeProcessor, FilterProcessor, PassThroughProcessor, RedactionProcessor, SpanProcessorFactory, TruncationProcessor, } from "./spanProcessor.js";
+export { enrichSpanWithTokenUsage, getTokenTracker, resetTokenTracker, TokenTracker, } from "./tokenTracker.js";
+// Types
+export { AGENT_ATTRIBUTES, GENAI_ATTRIBUTES, SpanStatus, SpanType, } from "./types/spanTypes.js";
+// Utilities
+export { SpanSerializer } from "./utils/spanSerializer.js";

package/dist/observability/metricsAggregator.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Metrics Aggregator
+ * Comprehensive metrics aggregation with latency percentiles, token usage, and cost tracking
+ */
+import type { TokenUsageStats } from "./tokenTracker.js";
+import { TokenTracker } from "./tokenTracker.js";
+import type { SpanData } from "./types/spanTypes.js";
+/**
+ * Latency statistics with percentile calculations
+ */
+export type LatencyStats = {
+    /** Minimum latency in milliseconds */
+    min: number;
+    /** Maximum latency in milliseconds */
+    max: number;
+    /** Mean/average latency in milliseconds */
+    mean: number;
+    /** Median latency (p50) in milliseconds */
+    median: number;
+    /** 50th percentile latency in milliseconds */
+    p50: number;
+    /** 75th percentile latency in milliseconds */
+    p75: number;
+    /** 90th percentile latency in milliseconds */
+    p90: number;
+    /** 95th percentile latency in milliseconds */
+    p95: number;
+    /** 99th percentile latency in milliseconds */
+    p99: number;
+    /** Standard deviation in milliseconds */
+    stdDev: number;
+    /** Total number of samples */
+    count: number;
+};
+/**
+ * Cost breakdown by provider
+ */
+export type ProviderCostStats = {
+    provider: string;
+    totalCost: number;
+    requestCount: number;
+    avgCostPerRequest: number;
+    inputCost: number;
+    outputCost: number;
+};
+/**
+ * Cost breakdown by model
+ */
+export type ModelCostStats = {
+    model: string;
+    provider: string;
+    totalCost: number;
+    requestCount: number;
+    avgCostPerRequest: number;
+    inputTokens: number;
+    outputTokens: number;
+    inputCost: number;
+    outputCost: number;
+};
+/**
+ * Time window statistics
+ */
+export type TimeWindowStats = {
+    windowStart: Date;
+    windowEnd: Date;
+    windowDurationMs: number;
+    requestCount: number;
+    errorCount: number;
+    successRate: number;
+    throughput: number;
+    latency: LatencyStats;
+    tokens: TokenUsageStats;
+    costByProvider: Map<string, ProviderCostStats>;
+    costByModel: Map<string, ModelCostStats>;
+};
+/**
+ * Aggregated metrics summary
+ */
+export type MetricsSummary = {
+    /** Total number of spans tracked */
+    totalSpans: number;
+    /** Number of successful spans */
+    successfulSpans: number;
+    /** Number of failed spans */
+    failedSpans: number;
+    /** Overall success rate (0-1) */
+    successRate: number;
+    /** Latency statistics */
+    latency: LatencyStats;
+    /** Token usage statistics */
+    tokens: TokenUsageStats;
+    /** Cost by provider */
+    costByProvider: ProviderCostStats[];
+    /** Cost by model */
+    costByModel: ModelCostStats[];
+    /** Total cost across all providers */
+    totalCost: number;
+    /** Span count by type */
+    spansByType: Record<string, number>;
+    /** Timestamp of first span */
+    firstSpanTime?: Date;
+    /** Timestamp of last span */
+    lastSpanTime?: Date;
+    /** Tracking duration in milliseconds */
+    trackingDurationMs?: number;
+};
+/**
+ * Hierarchical trace view grouping related spans
+ */
+export type TraceView = {
+    /** Trace identifier shared by all spans in this trace */
+    traceId: string;
+    /** The root/parent span of this trace */
+    rootSpan: SpanData;
+    /** Child spans linked to the root */
+    childSpans: SpanData[];
+    /** Total duration from first to last span */
+    totalDurationMs: number;
+    /** Total number of spans in this trace */
+    spanCount: number;
+    /** Overall trace status */
+    status: "ok" | "error" | "partial";
+};
+/**
+ * Configuration for the metrics aggregator
+ */
+export type MetricsAggregatorConfig = {
+    /** Maximum spans to retain in memory */
+    maxSpansRetained?: number;
+    /** Enable time-window statistics */
+    enableTimeWindows?: boolean;
+    /** Time window size in milliseconds (default: 60000 = 1 minute) */
+    timeWindowMs?: number;
+    /** Maximum time windows to retain */
+    maxTimeWindows?: number;
+};
+/**
+ * Metrics Aggregator for comprehensive telemetry analysis
+ * Provides latency percentiles, token aggregation, and cost tracking
+ */
+export declare class MetricsAggregator {
+    private spans;
+    private latencyValues;
+    private tokenTracker;
+    private timeWindows;
+    private config;
+    private spansByType;
+    private costByProvider;
+    private costByModel;
+    private successCount;
+    private failureCount;
+    private firstSpanTime?;
+    private lastSpanTime?;
+    constructor(config?: MetricsAggregatorConfig);
+    /**
+     * Record a span for metrics aggregation
+     */
+    recordSpan(span: SpanData): void;
+    /**
+     * Track cost aggregations from a span
+     */
+    private trackCosts;
+    /**
+     * Update time window statistics
+     */
+    private updateTimeWindow;
+    /**
+     * Create an empty time window
+     */
+    private createEmptyTimeWindow;
+    /**
+     * Create empty latency stats
+     */
+    private createEmptyLatencyStats;
+    /**
+     * Calculate latency percentile from sorted array
+     */
+    private calculatePercentile;
+    /**
+     * Calculate standard deviation
+     */
+    private calculateStdDev;
+    /**
+     * Get comprehensive latency statistics
+     */
+    getLatencyStats(): LatencyStats;
+    /**
+     * Get token usage statistics
+     */
+    getTokenStats(): TokenUsageStats;
+    /**
+     * Get cost breakdown by provider
+     */
+    getCostByProvider(): ProviderCostStats[];
+    /**
+     * Get cost breakdown by model
+     */
+    getCostByModel(): ModelCostStats[];
+    /**
+     * Get total cost across all providers
+     */
+    getTotalCost(): number;
+    /**
+     * Get time window statistics
+     */
+    getTimeWindows(): TimeWindowStats[];
+    /**
+     * Get statistics for a specific time range
+     */
+    getStatsForTimeRange(startTime: Date, endTime: Date): TimeWindowStats;
+    /**
+     * Record a latency measurement for an operation
+     * Use this for standalone latency tracking without a full span
+     */
+    recordLatency(operation: string, latencyMs: number): void;
+    /**
+     * Get comprehensive metrics summary (alias for getSummary)
+     */
+    getMetrics(): MetricsSummary;
+    /**
+     * Get comprehensive metrics summary
+     */
+    getSummary(): MetricsSummary;
+    /**
+     * Get all recorded spans (returns a copy)
+     */
+    getSpans(): SpanData[];
+    /**
+     * Get spans grouped by traceId as hierarchical trace views
+     */
+    getTraces(): TraceView[];
+    /**
+     * Get the underlying token tracker for custom pricing configuration
+     */
+    getTokenTracker(): TokenTracker;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Export metrics as JSON
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Format cost as currency string
+     */
+    formatCost(cost: number, currency?: string): string;
+    /**
+     * Get a formatted summary string
+     */
+    getFormattedSummary(): string;
+}
+/**
+ * Get the global metrics aggregator instance
+ */
+export declare function getMetricsAggregator(): MetricsAggregator;
+/**
+ * Reset the global metrics aggregator (for testing)
+ */
+export declare function resetMetricsAggregator(): void;