@juspay/neurolink 9.24.0 → 9.25.0

package/dist/lib/observability/spanProcessor.js

@@ -0,0 +1,288 @@
+/**
+ * Span Processor
+ * Handles span processing before export - enrichment, filtering, and transformation
+ * Fills the 9% gap in pattern compliance
+ */
+/**
+ * No-op processor that passes spans through unchanged
+ */
+export class PassThroughProcessor {
+    name = "pass-through";
+    process(span) {
+        return span;
+    }
+}
+/**
+ * Attribute enrichment processor
+ * Adds additional attributes to spans based on configuration
+ */
+export class AttributeEnrichmentProcessor {
+    name = "attribute-enrichment";
+    staticAttributes;
+    dynamicAttributes;
+    constructor(config) {
+        this.staticAttributes = config.staticAttributes ?? {};
+        this.dynamicAttributes = config.dynamicAttributes ?? (() => ({}));
+    }
+    process(span) {
+        return {
+            ...span,
+            attributes: {
+                ...this.staticAttributes,
+                ...span.attributes,
+                ...this.dynamicAttributes(span),
+            },
+        };
+    }
+}
+/**
+ * Filter processor - drops spans based on conditions
+ */
+export class FilterProcessor {
+    name = "filter";
+    predicate;
+    constructor(predicate) {
+        this.predicate = predicate;
+    }
+    process(span) {
+        return this.predicate(span) ? span : null;
+    }
+}
+/**
+ * Redaction processor - removes sensitive data from spans
+ */
+export class RedactionProcessor {
+    name = "redaction";
+    sensitiveKeys;
+    redactedValue;
+    constructor(config) {
+        this.sensitiveKeys = new Set(config?.sensitiveKeys ?? [
+            "api_key",
+            "apiKey",
+            "secret",
+            "password",
+            "token",
+            "authorization",
+            "credentials",
+            "private_key",
+            "privateKey",
+        ]);
+        this.redactedValue = config?.redactedValue ?? "[REDACTED]";
+    }
+    process(span) {
+        const redactedAttributes = {};
+        for (const [key, value] of Object.entries(span.attributes)) {
+            const lowerKey = key.toLowerCase();
+            const isSensitive = Array.from(this.sensitiveKeys).some((sensitiveKey) => lowerKey.includes(sensitiveKey.toLowerCase()));
+            if (isSensitive && typeof value === "string") {
+                redactedAttributes[key] = this.redactedValue;
+            }
+            else if (typeof value === "object" && value !== null) {
+                redactedAttributes[key] = this.redactObject(value);
+            }
+            else {
+                redactedAttributes[key] = value;
+            }
+        }
+        return {
+            ...span,
+            attributes: redactedAttributes,
+        };
+    }
+    redactObject(obj) {
+        if (typeof obj !== "object" || obj === null) {
+            return obj;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this.redactObject(item));
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const lowerKey = key.toLowerCase();
+            const isSensitive = Array.from(this.sensitiveKeys).some((sensitiveKey) => lowerKey.includes(sensitiveKey.toLowerCase()));
+            if (isSensitive && typeof value === "string") {
+                result[key] = this.redactedValue;
+            }
+            else if (typeof value === "object" && value !== null) {
+                result[key] = this.redactObject(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Truncation processor - truncates large attribute values
+ */
+export class TruncationProcessor {
+    name = "truncation";
+    maxStringLength;
+    maxArrayLength;
+    constructor(config) {
+        this.maxStringLength = config?.maxStringLength ?? 10000;
+        this.maxArrayLength = config?.maxArrayLength ?? 100;
+    }
+    process(span) {
+        return {
+            ...span,
+            attributes: this.truncateAttributes(span.attributes),
+        };
+    }
+    truncateAttributes(attrs) {
+        const result = {};
+        for (const [key, value] of Object.entries(attrs)) {
+            result[key] = this.truncateValue(value);
+        }
+        return result;
+    }
+    truncateValue(value) {
+        if (typeof value === "string" && value.length > this.maxStringLength) {
+            return value.substring(0, this.maxStringLength) + "...[truncated]";
+        }
+        if (Array.isArray(value) && value.length > this.maxArrayLength) {
+            return [
+                ...value.slice(0, this.maxArrayLength),
+                `...[${value.length - this.maxArrayLength} more items]`,
+            ];
+        }
+        if (typeof value === "object" && value !== null) {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+                result[k] = this.truncateValue(v);
+            }
+            return result;
+        }
+        return value;
+    }
+}
+/**
+ * Composite processor - chains multiple processors together
+ */
+export class CompositeProcessor {
+    name = "composite";
+    processors;
+    constructor(processors) {
+        this.processors = processors;
+    }
+    process(span) {
+        let result = span;
+        for (const processor of this.processors) {
+            if (result === null) {
+                return null;
+            }
+            result = processor.process(result);
+        }
+        return result;
+    }
+    async processAsync(span) {
+        let result = span;
+        for (const processor of this.processors) {
+            if (result === null) {
+                return null;
+            }
+            if (processor.processAsync) {
+                result = await processor.processAsync(result);
+            }
+            else {
+                result = processor.process(result);
+            }
+        }
+        return result;
+    }
+    async shutdown() {
+        await Promise.all(this.processors.map((p) => p.shutdown ? p.shutdown() : Promise.resolve()));
+    }
+}
+/**
+ * Batch processor - collects spans and processes them in batches
+ */
+export class BatchProcessor {
+    name = "batch";
+    innerProcessor;
+    batchSize;
+    flushIntervalMs;
+    batch = [];
+    flushTimer = null;
+    onBatchReady;
+    constructor(config) {
+        this.innerProcessor = config.processor ?? new PassThroughProcessor();
+        this.batchSize = config.batchSize ?? 100;
+        this.flushIntervalMs = config.flushIntervalMs ?? 5000;
+        this.onBatchReady = config.onBatchReady;
+        this.startFlushTimer();
+    }
+    process(span) {
+        const processed = this.innerProcessor.process(span);
+        if (processed) {
+            this.batch.push(processed);
+            if (this.batch.length >= this.batchSize) {
+                this.flush();
+            }
+        }
+        return processed;
+    }
+    startFlushTimer() {
+        this.flushTimer = setInterval(() => {
+            this.flush();
+        }, this.flushIntervalMs);
+    }
+    flush() {
+        if (this.batch.length > 0 && this.onBatchReady) {
+            const spans = [...this.batch];
+            this.batch = [];
+            this.onBatchReady(spans);
+        }
+    }
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.flush();
+        if (this.innerProcessor.shutdown) {
+            await this.innerProcessor.shutdown();
+        }
+    }
+}
+/**
+ * Factory for creating span processors
+ */
+export class SpanProcessorFactory {
+    /**
+     * Create a standard processor pipeline for production use
+     */
+    static createProductionPipeline(config) {
+        const processors = [
+            // Add service context
+            new AttributeEnrichmentProcessor({
+                staticAttributes: {
+                    "service.name": config?.serviceName ?? "neurolink",
+                    "deployment.environment": config?.environment ?? "production",
+                },
+            }),
+            // Redact sensitive data
+            new RedactionProcessor(),
+            // Truncate large values
+            new TruncationProcessor(),
+        ];
+        if (config?.additionalProcessors) {
+            processors.push(...config.additionalProcessors);
+        }
+        return new CompositeProcessor(processors);
+    }
+    /**
+     * Create a minimal processor pipeline for development
+     */
+    static createDevelopmentPipeline() {
+        return new CompositeProcessor([
+            new AttributeEnrichmentProcessor({
+                staticAttributes: {
+                    "deployment.environment": "development",
+                },
+            }),
+        ]);
+    }
+}
+//# sourceMappingURL=spanProcessor.js.map

package/dist/lib/observability/tokenTracker.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Token Usage Tracker
+ * Aggregates token usage and cost across spans
+ */
+import type { SpanData } from "./types/spanTypes.js";
+/**
+ * Token usage statistics by provider
+ */
+export type ProviderTokenStats = {
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cost: number;
+    requestCount: number;
+};
+/**
+ * Token usage statistics by model
+ */
+export type ModelTokenStats = {
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cost: number;
+    requestCount: number;
+    avgTokensPerRequest: number;
+};
+/**
+ * Aggregated token usage statistics
+ */
+export type TokenUsageStats = {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    totalCost: number;
+    byProvider: Map<string, ProviderTokenStats>;
+    byModel: Map<string, ModelTokenStats>;
+    bySpanType: Map<string, number>;
+};
+/**
+ * Model pricing information
+ */
+export type ModelPricing = {
+    inputPricePerMillion: number;
+    outputPricePerMillion: number;
+    cachedInputPricePerMillion?: number;
+};
+/**
+ * Token tracker for aggregating usage across spans
+ */
+export declare class TokenTracker {
+    private stats;
+    private customPricing;
+    /**
+     * Set custom pricing for a single model
+     * @param modelName - The model name (e.g., "gpt-4o", "claude-3-5-sonnet")
+     * @param pricing - The pricing information
+     */
+    setModelPricing(modelName: string, pricing: ModelPricing): void;
+    /**
+     * Update pricing for an existing model (alias for setModelPricing)
+     * @param model - The model name
+     * @param pricing - The new pricing information
+     */
+    updatePricing(model: string, pricing: ModelPricing): void;
+    /**
+     * Load pricing configuration from a config object
+     * Useful for loading pricing from environment or config files
+     * @param config - Record of model names to pricing information
+     */
+    loadPricingFromConfig(config: Record<string, ModelPricing>): void;
+    /**
+     * Get pricing for a specific model
+     * @param model - The model name
+     * @returns The pricing information or undefined if not found
+     */
+    getModelPricing(model: string): ModelPricing | undefined;
+    /**
+     * Get all available model pricing (custom + built-in)
+     * @returns Record of all model pricing
+     */
+    getAllPricing(): Record<string, ModelPricing>;
+    /**
+     * Remove custom pricing for a model (falls back to built-in)
+     * @param model - The model name to remove custom pricing for
+     */
+    removeCustomPricing(model: string): boolean;
+    /**
+     * Track token usage from a span
+     */
+    trackSpan(span: SpanData): void;
+    /**
+     * Calculate cost from token counts and provider/model
+     */
+    private calculateCost;
+    /**
+     * Track token usage from a simple usage object
+     * This is a convenience method for tracking usage without a full span
+     * @param usage - Token usage data
+     */
+    trackUsage(usage: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        model?: string;
+        provider?: string;
+    }): void;
+    /**
+     * Get current stats
+     */
+    getStats(): TokenUsageStats;
+    /**
+     * Get stats for a specific time window of spans
+     */
+    getStatsForWindow(spans: SpanData[]): TokenUsageStats;
+    /**
+     * Reset all stats
+     */
+    reset(): void;
+    /**
+     * Export stats as JSON
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Format cost as currency string
+     */
+    formatCost(cost: number, currency?: string): string;
+    /**
+     * Get a summary string of current stats
+     */
+    getSummary(): string;
+}
+/**
+ * Enrich span with token usage attributes
+ */
+export declare function enrichSpanWithTokenUsage(span: SpanData, usage: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+    reasoningTokens?: number;
+}): SpanData;
+/**
+ * Get the global token tracker instance
+ */
+export declare function getTokenTracker(): TokenTracker;
+/**
+ * Reset the global token tracker (for testing)
+ */
+export declare function resetTokenTracker(): void;