@juspay/neurolink 9.24.0 → 9.25.1

package/dist/lib/observability/sampling/index.js

@@ -0,0 +1,5 @@
+/**
+ * Sampling strategies exports
+ */
+export { AlwaysSampler, AttributeBasedSampler, CompositeSampler, CustomSampler, ErrorOnlySampler, NeverSampler, PrioritySampler, RatioSampler, SamplerFactory, TraceIdRatioSampler, } from "./samplers.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/observability/sampling/samplers.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Sampling Strategies
+ * Control which spans are exported for production optimization
+ */
+import type { SamplerConfig, SamplingRule } from "../types/exporterTypes.js";
+import type { SpanData } from "../types/spanTypes.js";
+/**
+ * Sampler interface for controlling which spans are exported
+ */
+export interface Sampler {
+    /** Sampler name for identification */
+    readonly name: string;
+    /** Determine if a span should be sampled */
+    shouldSample(span: SpanData): boolean;
+    /** Get sampling decision description */
+    getDescription(): string;
+}
+/**
+ * Always sample all spans
+ */
+export declare class AlwaysSampler implements Sampler {
+    readonly name = "always";
+    shouldSample(_span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Never sample any spans
+ */
+export declare class NeverSampler implements Sampler {
+    readonly name = "never";
+    shouldSample(_span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Sample spans based on a probability ratio
+ */
+export declare class RatioSampler implements Sampler {
+    readonly name = "ratio";
+    private readonly ratio;
+    constructor(ratio: number);
+    shouldSample(_span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Sample based on trace ID for consistent sampling across a trace
+ */
+export declare class TraceIdRatioSampler implements Sampler {
+    readonly name = "trace-id-ratio";
+    private readonly ratio;
+    private readonly upperBound;
+    constructor(ratio: number);
+    shouldSample(span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Sample based on span attributes (e.g., errors, specific providers)
+ */
+export declare class AttributeBasedSampler implements Sampler {
+    readonly name = "attribute-based";
+    private readonly rules;
+    private readonly defaultSampler;
+    constructor(rules: SamplingRule[], defaultSampler?: Sampler);
+    shouldSample(span: SpanData): boolean;
+    private matchesRule;
+    getDescription(): string;
+}
+/**
+ * Priority-based sampler - always sample high-priority spans
+ */
+export declare class PrioritySampler implements Sampler {
+    readonly name = "priority";
+    private readonly highPriorityTypes;
+    private readonly fallbackSampler;
+    constructor(highPriorityTypes?: string[], fallbackSampler?: Sampler);
+    shouldSample(span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Error-only sampler - only sample error spans
+ */
+export declare class ErrorOnlySampler implements Sampler {
+    readonly name = "error-only";
+    shouldSample(span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Composite sampler that combines multiple samplers
+ */
+export declare class CompositeSampler implements Sampler {
+    readonly name = "composite";
+    private readonly samplers;
+    private readonly totalWeight;
+    constructor(samplers: Array<{
+        sampler: Sampler;
+        weight: number;
+    }>);
+    shouldSample(span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Custom sampler that uses a user-provided function
+ */
+export declare class CustomSampler implements Sampler {
+    readonly name = "custom";
+    private readonly sampleFn;
+    private readonly description;
+    constructor(sampleFn: (span: SpanData) => boolean, description?: string);
+    shouldSample(span: SpanData): boolean;
+    getDescription(): string;
+}
+/**
+ * Factory for creating samplers from configuration
+ */
+export declare class SamplerFactory {
+    static create(config: SamplerConfig): Sampler;
+}

package/dist/lib/observability/sampling/samplers.js

@@ -0,0 +1,217 @@
+/**
+ * Sampling Strategies
+ * Control which spans are exported for production optimization
+ */
+import { SpanStatus } from "../types/spanTypes.js";
+/**
+ * Always sample all spans
+ */
+export class AlwaysSampler {
+    name = "always";
+    shouldSample(_span) {
+        return true;
+    }
+    getDescription() {
+        return "Samples 100% of spans";
+    }
+}
+/**
+ * Never sample any spans
+ */
+export class NeverSampler {
+    name = "never";
+    shouldSample(_span) {
+        return false;
+    }
+    getDescription() {
+        return "Samples 0% of spans";
+    }
+}
+/**
+ * Sample spans based on a probability ratio
+ */
+export class RatioSampler {
+    name = "ratio";
+    ratio;
+    constructor(ratio) {
+        if (ratio < 0 || ratio > 1) {
+            throw new Error("Ratio must be between 0 and 1");
+        }
+        this.ratio = ratio;
+    }
+    shouldSample(_span) {
+        return Math.random() < this.ratio;
+    }
+    getDescription() {
+        return `Samples ${this.ratio * 100}% of spans`;
+    }
+}
+/**
+ * Sample based on trace ID for consistent sampling across a trace
+ */
+export class TraceIdRatioSampler {
+    name = "trace-id-ratio";
+    ratio;
+    upperBound;
+    constructor(ratio) {
+        if (ratio < 0 || ratio > 1) {
+            throw new Error("Ratio must be between 0 and 1");
+        }
+        this.ratio = ratio;
+        this.upperBound = Math.floor(ratio * 0xffffffff);
+    }
+    shouldSample(span) {
+        // Use first 8 chars of trace ID as hash
+        const hash = parseInt(span.traceId.substring(0, 8), 16);
+        return !isNaN(hash) && hash < this.upperBound;
+    }
+    getDescription() {
+        return `Samples ${this.ratio * 100}% of traces (consistent per trace)`;
+    }
+}
+/**
+ * Sample based on span attributes (e.g., errors, specific providers)
+ */
+export class AttributeBasedSampler {
+    name = "attribute-based";
+    rules;
+    defaultSampler;
+    constructor(rules, defaultSampler = new RatioSampler(0.1)) {
+        // Sort rules by priority (higher first)
+        this.rules = [...rules].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        this.defaultSampler = defaultSampler;
+    }
+    shouldSample(span) {
+        for (const rule of this.rules) {
+            if (this.matchesRule(span, rule)) {
+                return rule.sample;
+            }
+        }
+        return this.defaultSampler.shouldSample(span);
+    }
+    matchesRule(span, rule) {
+        for (const [key, value] of Object.entries(rule.conditions)) {
+            const spanValue = span.attributes[key];
+            // Support wildcard matching
+            if (value === "*" && spanValue !== undefined) {
+                continue;
+            }
+            if (spanValue !== value) {
+                return false;
+            }
+        }
+        return true;
+    }
+    getDescription() {
+        return `Attribute-based sampling with ${this.rules.length} rules`;
+    }
+}
+/**
+ * Priority-based sampler - always sample high-priority spans
+ */
+export class PrioritySampler {
+    name = "priority";
+    highPriorityTypes;
+    fallbackSampler;
+    constructor(highPriorityTypes = ["model.generation", "tool.call"], fallbackSampler = new RatioSampler(0.1)) {
+        this.highPriorityTypes = highPriorityTypes;
+        this.fallbackSampler = fallbackSampler;
+    }
+    shouldSample(span) {
+        // Always sample errors
+        if (span.status === SpanStatus.ERROR) {
+            return true;
+        }
+        // Always sample high-priority span types
+        if (this.highPriorityTypes.includes(span.type)) {
+            return true;
+        }
+        return this.fallbackSampler.shouldSample(span);
+    }
+    getDescription() {
+        return `Priority sampling for ${this.highPriorityTypes.join(", ")} spans`;
+    }
+}
+/**
+ * Error-only sampler - only sample error spans
+ */
+export class ErrorOnlySampler {
+    name = "error-only";
+    shouldSample(span) {
+        return span.status === SpanStatus.ERROR;
+    }
+    getDescription() {
+        return "Samples only error spans";
+    }
+}
+/**
+ * Composite sampler that combines multiple samplers
+ */
+export class CompositeSampler {
+    name = "composite";
+    samplers;
+    totalWeight;
+    constructor(samplers) {
+        this.samplers = samplers;
+        this.totalWeight = samplers.reduce((sum, s) => sum + s.weight, 0);
+    }
+    shouldSample(span) {
+        let random = Math.random() * this.totalWeight;
+        for (const { sampler, weight } of this.samplers) {
+            random -= weight;
+            if (random <= 0) {
+                return sampler.shouldSample(span);
+            }
+        }
+        return this.samplers[this.samplers.length - 1].sampler.shouldSample(span);
+    }
+    getDescription() {
+        return `Composite of ${this.samplers.length} samplers`;
+    }
+}
+/**
+ * Custom sampler that uses a user-provided function
+ */
+export class CustomSampler {
+    name = "custom";
+    sampleFn;
+    description;
+    constructor(sampleFn, description = "Custom sampling function") {
+        this.sampleFn = sampleFn;
+        this.description = description;
+    }
+    shouldSample(span) {
+        return this.sampleFn(span);
+    }
+    getDescription() {
+        return this.description;
+    }
+}
+/**
+ * Factory for creating samplers from configuration
+ */
+export class SamplerFactory {
+    static create(config) {
+        switch (config.type) {
+            case "always":
+                return new AlwaysSampler();
+            case "never":
+                return new NeverSampler();
+            case "ratio":
+                return new RatioSampler(config.ratio ?? 0.1);
+            case "trace-id-ratio":
+                return new TraceIdRatioSampler(config.ratio ?? 0.1);
+            case "attribute-based":
+                return new AttributeBasedSampler(config.rules ?? [], config.defaultRatio !== undefined
+                    ? new RatioSampler(config.defaultRatio)
+                    : undefined);
+            case "priority":
+                return new PrioritySampler();
+            case "error-only":
+                return new ErrorOnlySampler();
+            default:
+                return new RatioSampler(0.1);
+        }
+    }
+}
+//# sourceMappingURL=samplers.js.map

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

@@ -0,0 +1,129 @@
+/**
+ * Span Processor
+ * Handles span processing before export - enrichment, filtering, and transformation
+ * Fills the 9% gap in pattern compliance
+ */
+import type { SpanAttributes, SpanData } from "./types/index.js";
+/**
+ * Span processor interface
+ * Allows for composable span processing pipelines
+ */
+export interface SpanProcessor {
+    /** Processor name for identification */
+    readonly name: string;
+    /** Process a span before export, returns null to drop the span */
+    process(span: SpanData): SpanData | null;
+    /** Optional async processing (for external lookups, etc.) */
+    processAsync?(span: SpanData): Promise<SpanData | null>;
+    /** Shutdown the processor (cleanup resources) */
+    shutdown?(): Promise<void>;
+}
+/**
+ * No-op processor that passes spans through unchanged
+ */
+export declare class PassThroughProcessor implements SpanProcessor {
+    readonly name = "pass-through";
+    process(span: SpanData): SpanData;
+}
+/**
+ * Attribute enrichment processor
+ * Adds additional attributes to spans based on configuration
+ */
+export declare class AttributeEnrichmentProcessor implements SpanProcessor {
+    readonly name = "attribute-enrichment";
+    private readonly staticAttributes;
+    private readonly dynamicAttributes;
+    constructor(config: {
+        staticAttributes?: SpanAttributes;
+        dynamicAttributes?: (span: SpanData) => Partial<SpanAttributes>;
+    });
+    process(span: SpanData): SpanData;
+}
+/**
+ * Filter processor - drops spans based on conditions
+ */
+export declare class FilterProcessor implements SpanProcessor {
+    readonly name = "filter";
+    private readonly predicate;
+    constructor(predicate: (span: SpanData) => boolean);
+    process(span: SpanData): SpanData | null;
+}
+/**
+ * Redaction processor - removes sensitive data from spans
+ */
+export declare class RedactionProcessor implements SpanProcessor {
+    readonly name = "redaction";
+    private readonly sensitiveKeys;
+    private readonly redactedValue;
+    constructor(config?: {
+        sensitiveKeys?: string[];
+        redactedValue?: string;
+    });
+    process(span: SpanData): SpanData;
+    private redactObject;
+}
+/**
+ * Truncation processor - truncates large attribute values
+ */
+export declare class TruncationProcessor implements SpanProcessor {
+    readonly name = "truncation";
+    private readonly maxStringLength;
+    private readonly maxArrayLength;
+    constructor(config?: {
+        maxStringLength?: number;
+        maxArrayLength?: number;
+    });
+    process(span: SpanData): SpanData;
+    private truncateAttributes;
+    private truncateValue;
+}
+/**
+ * Composite processor - chains multiple processors together
+ */
+export declare class CompositeProcessor implements SpanProcessor {
+    readonly name = "composite";
+    private readonly processors;
+    constructor(processors: SpanProcessor[]);
+    process(span: SpanData): SpanData | null;
+    processAsync(span: SpanData): Promise<SpanData | null>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Batch processor - collects spans and processes them in batches
+ */
+export declare class BatchProcessor implements SpanProcessor {
+    readonly name = "batch";
+    private readonly innerProcessor;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private batch;
+    private flushTimer;
+    private onBatchReady?;
+    constructor(config: {
+        processor?: SpanProcessor;
+        batchSize?: number;
+        flushIntervalMs?: number;
+        onBatchReady?: (spans: SpanData[]) => void;
+    });
+    process(span: SpanData): SpanData | null;
+    private startFlushTimer;
+    private flush;
+    shutdown(): Promise<void>;
+}
+/**
+ * Factory for creating span processors
+ */
+export declare class SpanProcessorFactory {
+    /**
+     * Create a standard processor pipeline for production use
+     */
+    static createProductionPipeline(config?: {
+        serviceName?: string;
+        environment?: string;
+        additionalProcessors?: SpanProcessor[];
+    }): CompositeProcessor;
+    /**
+     * Create a minimal processor pipeline for development
+     */
+    static createDevelopmentPipeline(): CompositeProcessor;
+}