@juspay/neurolink 9.24.0 → 9.25.0

package/dist/observability/FEATURE-STATUS.md

@@ -0,0 +1,269 @@
+# Observability - Status
+
+**Completion:** Beta (Stream token counts and memory trace hierarchy pending verification)
+**Last Updated:** March 9, 2026
+
+## Exporters (9/9)
+
+- Langfuse
+- LangSmith
+- Datadog
+- Sentry
+- Braintrust
+- Arize
+- PostHog
+- Laminar
+- OTel (OpenTelemetry)
+
+## Core Components
+
+| Component          | Status   | Notes                                                                                           |
+| ------------------ | -------- | ----------------------------------------------------------------------------------------------- |
+| ExporterRegistry   | Complete | Circuit breaker protection, multi-exporter support                                              |
+| OtelBridge         | Complete | Bidirectional context propagation                                                               |
+| TokenTracker       | Complete | Multi-provider pricing, custom pricing support                                                  |
+| MetricsAggregator  | Complete | Full percentile support (p50, p75, p90, p95, p99)                                               |
+| SpanSerializer     | Complete | Langfuse, LangSmith, OTel format conversion                                                     |
+| Samplers (9 types) | Complete | Always, Never, Ratio, TraceIdRatio, AttributeBased, Priority, ErrorOnly, Composite, Custom      |
+| SpanProcessor      | Complete | 7 processors: PassThrough, AttributeEnrichment, Filter, Redaction, Truncation, Composite, Batch |
+| RetryPolicy        | Complete | 5 policies: Exponential, Linear, Fixed, NoRetry, CircuitBreakerAware + RetryExecutor            |
+| CLI Commands       | Complete | status, metrics, exporters, costs subcommands                                                   |
+| Tests              | Complete | 100+ test cases across unit and integration                                                     |
+
+## Sampler Types
+
+1. **AlwaysSampler** - Samples 100% of spans
+2. **NeverSampler** - Samples 0% of spans
+3. **RatioSampler** - Probabilistic sampling by ratio
+4. **TraceIdRatioSampler** - Consistent sampling per trace
+5. **AttributeBasedSampler** - Rule-based sampling with priorities
+6. **PrioritySampler** - Always sample errors and high-priority span types
+7. **ErrorOnlySampler** - Only sample error spans
+8. **CompositeSampler** - Weighted combination of multiple samplers
+9. **CustomSampler** - User-provided sampling function
+
+## Span Processor Types
+
+1. **PassThroughProcessor** - Passes spans unchanged
+2. **AttributeEnrichmentProcessor** - Adds static/dynamic attributes
+3. **FilterProcessor** - Drops spans based on predicates
+4. **RedactionProcessor** - Removes sensitive data from spans
+5. **TruncationProcessor** - Truncates large attribute values
+6. **CompositeProcessor** - Chains multiple processors together
+7. **BatchProcessor** - Collects spans for batch processing
+
+## Retry Policy Types
+
+1. **ExponentialBackoffPolicy** - Delay increases exponentially (2^n)
+2. **LinearBackoffPolicy** - Delay increases linearly
+3. **FixedDelayPolicy** - Same delay for all retries
+4. **NoRetryPolicy** - Never retries
+5. **CircuitBreakerAwarePolicy** - Integrates with circuit breaker state
+
+## Architecture
+
+### Span Processing Pipeline
+
+```
+Span Creation → SpanProcessor(s) → Sampler → Exporter(s)
+                     ↓                           ↓
+              Enrichment/Filter          RetryPolicy + CircuitBreaker
+```
+
+### Retry Strategy
+
+The `BaseExporter` abstract class provides basic retry via `withRetry()`. For advanced scenarios, use the `RetryExecutor` with configurable policies:
+
+```typescript
+import { RetryExecutor, RetryPolicyFactory } from "neurolink/observability";
+
+const executor = new RetryExecutor(
+  RetryPolicyFactory.createWithCircuitBreaker(),
+);
+
+await executor.execute(() => exporter.exportBatch(spans), "export-batch");
+```
+
+### Span Processing
+
+Use `SpanProcessorFactory` for pre-configured pipelines:
+
+```typescript
+import { SpanProcessorFactory } from "neurolink/observability";
+
+const pipeline = SpanProcessorFactory.createProductionPipeline({
+  serviceName: "my-service",
+  environment: "production",
+});
+
+const processedSpan = pipeline.process(span);
+```
+
+## Pattern Compliance
+
+**Score:** 100/100
+
+### Compliant Patterns
+
+- Factory + Registry pattern (ExporterRegistry)
+- Abstract base class pattern (BaseExporter, BaseRetryPolicy)
+- Singleton pattern (global registry, token tracker, metrics aggregator)
+- Strategy pattern (Sampler interface, RetryPolicy interface, SpanProcessor interface)
+- Builder pattern (SpanSerializer helpers, SpanProcessorFactory)
+- Composite pattern (CompositeProcessor, CompositeSampler)
+- Circuit breaker pattern (ExporterRegistry, CircuitBreakerAwarePolicy)
+- Chain of responsibility pattern (SpanProcessor pipeline)
+
+## Files
+
+```
+src/lib/observability/
+├── index.ts                    # Main exports
+├── exporterRegistry.ts         # Multi-exporter management
+├── otelBridge.ts               # OpenTelemetry bridge
+├── tokenTracker.ts             # Token usage and cost tracking
+├── metricsAggregator.ts        # Metrics with percentiles
+├── spanProcessor.ts            # Span processing pipeline (NEW)
+├── retryPolicy.ts              # Configurable retry strategies (NEW)
+├── FEATURE-STATUS.md           # This file
+├── exporters/
+│   ├── index.ts
+│   ├── baseExporter.ts         # Abstract base class
+│   ├── langfuseExporter.ts
+│   ├── langsmithExporter.ts
+│   ├── datadogExporter.ts
+│   ├── sentryExporter.ts
+│   ├── braintrustExporter.ts
+│   ├── arizeExporter.ts
+│   ├── posthogExporter.ts
+│   ├── laminarExporter.ts
+│   └── otelExporter.ts
+├── sampling/
+│   ├── index.ts
+│   └── samplers.ts             # 9 sampler implementations
+├── types/
+│   ├── index.ts
+│   ├── exporterTypes.ts
+│   └── spanTypes.ts
+└── utils/
+    ├── index.ts
+    └── spanSerializer.ts
+```
+
+## CLI Commands
+
+```bash
+# Status overview
+neurolink observability status
+
+# Metrics summary
+neurolink observability metrics
+neurolink obs metrics --detailed
+
+# List exporters
+neurolink observability exporters
+neurolink obs exp --format json
+
+# Cost breakdown
+neurolink observability costs
+neurolink obs costs --by-model --by-provider
+```
+
+## Usage Example
+
+```typescript
+import {
+  ExporterRegistry,
+  LangfuseExporter,
+  OtelExporter,
+  RatioSampler,
+  SpanProcessorFactory,
+  RetryPolicyFactory,
+  RetryExecutor,
+  SpanSerializer,
+  SpanType,
+} from "neurolink/observability";
+
+// Create exporters
+const langfuse = new LangfuseExporter({
+  enabled: true,
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+});
+
+const otel = new OtelExporter({
+  enabled: true,
+  endpoint: "https://otel-collector.example.com",
+});
+
+// Setup registry with sampling
+const registry = new ExporterRegistry();
+registry.register(langfuse);
+registry.register(otel);
+registry.setSampler(new RatioSampler(0.1)); // 10% sampling
+
+// Create span processor pipeline
+const processor = SpanProcessorFactory.createProductionPipeline({
+  serviceName: "my-ai-service",
+  environment: "production",
+});
+
+// Create retry executor for resilience
+const retryExecutor = new RetryExecutor(
+  RetryPolicyFactory.createWithCircuitBreaker({
+    failureThreshold: 5,
+    resetTimeoutMs: 30000,
+  }),
+);
+
+// Initialize
+await registry.initializeAll();
+
+// Create and export spans
+const span = SpanSerializer.createGenerationSpan({
+  provider: "openai",
+  model: "gpt-4o",
+  userId: "user-123",
+});
+
+// ... perform AI operation ...
+
+const endedSpan = SpanSerializer.endSpan(span);
+
+// Process span before export
+const processedSpan = processor.process(endedSpan);
+
+if (processedSpan) {
+  // Export with retry
+  await retryExecutor.execute(
+    () => registry.exportToAll(processedSpan),
+    "export-span",
+  );
+}
+```
+
+## Migration from 91% to 100%
+
+### New Components Added (January 31, 2026)
+
+1. **SpanProcessor** (`spanProcessor.ts`)
+   - Fills the SpanProcessor gap identified in pattern compliance
+   - 7 processor types for different use cases
+   - Factory for production/development pipelines
+
+2. **RetryPolicy** (`retryPolicy.ts`)
+   - Addresses "more sophisticated retry policies" gap
+   - 5 policy types with full configuration
+   - Circuit breaker integration
+   - RetryExecutor for easy usage
+
+### Breaking Changes
+
+None - all new components are additive.
+
+### Recommended Upgrades
+
+For production deployments, consider upgrading to use:
+
+1. `SpanProcessorFactory.createProductionPipeline()` for automatic redaction and enrichment
+2. `RetryPolicyFactory.createWithCircuitBreaker()` for resilient exports

package/dist/observability/exporterRegistry.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Exporter Registry
+ * Manages multiple observability exporters with circuit breaker protection
+ */
+import type { BaseExporter } from "./exporters/baseExporter.js";
+import type { Sampler } from "./sampling/samplers.js";
+import type { ExporterHealthStatus, ExportResult, SpanData } from "./types/index.js";
+/**
+ * Circuit breaker state for an exporter
+ */
+type CircuitBreakerState = {
+    failures: number;
+    lastFailure: number;
+    state: "closed" | "open" | "half-open";
+};
+/**
+ * Circuit breaker configuration
+ */
+type CircuitBreakerConfig = {
+    /** Number of failures before opening the circuit */
+    failureThreshold: number;
+    /** Time in ms to wait before trying half-open state */
+    resetTimeout: number;
+};
+/**
+ * Registry for managing multiple observability exporters
+ * Includes circuit breaker protection to prevent cascading failures
+ */
+export declare class ExporterRegistry {
+    private exporters;
+    private defaultExporter;
+    private sampler;
+    private circuitBreakers;
+    private readonly circuitBreakerConfig;
+    /**
+     * Register an exporter
+     */
+    register(exporter: BaseExporter): void;
+    /**
+     * Unregister an exporter
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get an exporter by name
+     */
+    get(name: string): BaseExporter | undefined;
+    /**
+     * Get all registered exporter names
+     */
+    getNames(): string[];
+    /**
+     * Get total exporter count
+     */
+    getCount(): number;
+    /**
+     * Set the default exporter
+     */
+    setDefault(name: string): void;
+    /**
+     * Get the default exporter
+     */
+    getDefault(): BaseExporter | undefined;
+    /**
+     * Set the sampler for the registry
+     */
+    setSampler(sampler: Sampler): void;
+    /**
+     * Get the current sampler
+     */
+    getSampler(): Sampler;
+    /**
+     * Configure the circuit breaker settings
+     * @param config - Partial circuit breaker configuration
+     */
+    configureCircuitBreaker(config: Partial<CircuitBreakerConfig>): void;
+    /**
+     * Check if circuit is open for an exporter
+     * @param exporterName - Name of the exporter
+     * @returns true if circuit is open (exporter should be skipped)
+     */
+    private isCircuitOpen;
+    /**
+     * Record a failure for an exporter's circuit breaker
+     * @param exporterName - Name of the exporter
+     */
+    private recordFailure;
+    /**
+     * Record a success for an exporter's circuit breaker
+     * Resets the circuit to closed state
+     * @param exporterName - Name of the exporter
+     */
+    private recordSuccess;
+    /**
+     * Get circuit breaker status for an exporter
+     * @param exporterName - Name of the exporter
+     * @returns Circuit breaker state or undefined if not tracked
+     */
+    getCircuitBreakerStatus(exporterName: string): CircuitBreakerState | undefined;
+    /**
+     * Reset circuit breaker for an exporter
+     * @param exporterName - Name of the exporter
+     */
+    resetCircuitBreaker(exporterName: string): void;
+    /**
+     * Export span to all registered exporters
+     * Applies sampling and circuit breaker protection before export
+     */
+    exportToAll(span: SpanData): Promise<Map<string, ExportResult>>;
+    /**
+     * Export span to a specific exporter
+     * Applies sampling and circuit breaker protection
+     */
+    exportTo(name: string, span: SpanData): Promise<ExportResult | null>;
+    /**
+     * Initialize all exporters
+     */
+    initializeAll(): Promise<void>;
+    /**
+     * Shutdown all exporters
+     */
+    shutdownAll(): Promise<void>;
+    /**
+     * Flush all exporters
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Get health status of all exporters
+     */
+    healthCheckAll(): Promise<Map<string, ExporterHealthStatus>>;
+    /**
+     * Check if all exporters are healthy
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Get total pending spans across all exporters
+     */
+    getTotalPendingSpans(): number;
+    /**
+     * Clear all registered exporters and reset state
+     * (For testing and cleanup)
+     */
+    clear(): void;
+}
+/**
+ * Get the global exporter registry instance
+ */
+export declare function getExporterRegistry(): ExporterRegistry;
+/**
+ * Reset the global exporter registry (for testing)
+ */
+export declare function resetExporterRegistry(): void;
+export {};