e11y 0.1.0

data/lib/e11y/reliability/dlq/filter.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module E11y
+  module Reliability
+    module DLQ
+      # DLQ Filter determines which failed events should be saved to DLQ.
+      #
+      # Supports:
+      # - Always save patterns (e.g., payment.*, audit.*)
+      # - Always discard patterns (e.g., debug.*, test.*)
+      # - Severity-based filtering (e.g., always save :error, :fatal)
+      #
+      # @example Configuration
+      #   filter = Filter.new(
+      #     always_save_patterns: [/^payment\./, /^audit\./],
+      #     always_discard_patterns: [/^debug\./, /^test\./],
+      #     save_severities: [:error, :fatal]
+      #   )
+      #
+      #   filter.should_save?(event_data)  # => true/false
+      #
+      # @see ADR-013 §4.3 (DLQ Filter)
+      # @see UC-021 §3.2 (DLQ Filter Configuration)
+      class Filter
+        # @param always_save_patterns [Array<Regexp>] Event patterns to always save
+        # @param always_discard_patterns [Array<Regexp>] Event patterns to always discard
+        # @param save_severities [Array<Symbol>] Severities to always save (:error, :fatal)
+        # @param default_behavior [Symbol] Default behavior when no rule matches (:save or :discard)
+        def initialize(
+          always_save_patterns: [],
+          always_discard_patterns: [],
+          save_severities: %i[error fatal],
+          default_behavior: :save
+        )
+          @always_save_patterns = always_save_patterns
+          @always_discard_patterns = always_discard_patterns
+          @save_severities = save_severities
+          @default_behavior = default_behavior
+        end
+
+        # Check if event should be saved to DLQ.
+        #
+        # Priority order:
+        # 1. Always discard patterns (highest priority)
+        # 2. Always save patterns
+        # 3. Severity-based rules
+        # 4. Default behavior
+        #
+        # @param event_data [Hash] Event data
+        # @return [Boolean] true if event should be saved to DLQ
+        def should_save?(event_data)
+          event_name = event_data[:event_name].to_s
+          severity = event_data[:severity]
+
+          # Priority 1: Always discard (highest priority)
+          if matches_patterns?(event_name, @always_discard_patterns)
+            increment_metric("e11y.dlq.filter.discarded", reason: "always_discard_pattern")
+            return false
+          end
+
+          # Priority 2: Always save
+          if matches_patterns?(event_name, @always_save_patterns)
+            increment_metric("e11y.dlq.filter.saved", reason: "always_save_pattern")
+            return true
+          end
+
+          # Priority 3: Severity-based
+          if @save_severities.include?(severity)
+            increment_metric("e11y.dlq.filter.saved", reason: "severity")
+            return true
+          end
+
+          # Priority 4: Default behavior
+          if @default_behavior == :save
+            increment_metric("e11y.dlq.filter.saved", reason: "default")
+            true
+          else
+            increment_metric("e11y.dlq.filter.discarded", reason: "default")
+            false
+          end
+        end
+
+        # Get filter statistics.
+        #
+        # @return [Hash] Filter configuration stats
+        def stats
+          {
+            always_save_patterns: @always_save_patterns.map(&:inspect),
+            always_discard_patterns: @always_discard_patterns.map(&:inspect),
+            save_severities: @save_severities,
+            default_behavior: @default_behavior
+          }
+        end
+
+        private
+
+        # Check if event name matches any of the patterns.
+        #
+        # @param event_name [String] Event name
+        # @param patterns [Array<Regexp>] Patterns to match
+        # @return [Boolean] true if event matches any pattern
+        def matches_patterns?(event_name, patterns)
+          patterns.any? { |pattern| pattern.match?(event_name) }
+        end
+
+        # Increment DLQ filter metric.
+        #
+        # @param metric_name [String] Metric name
+        # @param tags [Hash] Additional tags
+        def increment_metric(metric_name, tags = {})
+          # TODO: Integrate with Yabeda metrics
+          # E11y::Metrics.increment(metric_name, tags)
+        end
+      end
+    end
+  end
+end

data/lib/e11y/reliability/retry_handler.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module E11y
+  module Reliability
+    # Retry handler with exponential backoff and jitter.
+    #
+    # Automatically retries transient failures with increasing delays.
+    # Integrates with CircuitBreaker and DLQ for comprehensive error handling.
+    #
+    # @example Usage
+    #   retry_handler = RetryHandler.new(config: config)
+    #
+    #   retry_handler.with_retry(adapter: adapter, event: event_data) do
+    #     adapter.send(event_data)
+    #   end
+    #
+    # @see ADR-013 §3 (Retry Policy)
+    # @see UC-021 §2 (Exponential Backoff with Jitter)
+    class RetryHandler
+      # Retry exhausted error (all retries failed)
+      class RetryExhaustedError < StandardError
+        attr_reader :original_error, :retry_count
+
+        def initialize(original_error, retry_count:)
+          @original_error = original_error
+          @retry_count = retry_count
+          super("Retry exhausted after #{retry_count} attempts: #{original_error.message}")
+        end
+      end
+
+      # Transient errors that should be retried
+      TRANSIENT_ERRORS = [
+        Timeout::Error,
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        Errno::ETIMEDOUT,
+        Errno::EHOSTUNREACH,
+        Errno::ENETUNREACH
+      ].freeze
+
+      # HTTP status codes that should be retried (5xx server errors)
+      RETRIABLE_HTTP_STATUS_CODES = (500..599)
+
+      # @param config [Hash] Configuration options
+      # @option config [Integer] :max_attempts Maximum retry attempts (default: 3)
+      # @option config [Float] :base_delay_ms Initial delay in milliseconds (default: 100)
+      # @option config [Float] :max_delay_ms Maximum delay in milliseconds (default: 5000)
+      # @option config [Float] :jitter_factor Jitter factor (0.0-1.0, default: 0.1)
+      # @option config [Boolean] :fail_on_error Raise error after max retries (default: true)
+      def initialize(config: {})
+        @max_attempts = config[:max_attempts] || 3
+        @base_delay_ms = config[:base_delay_ms] || 100.0
+        @max_delay_ms = config[:max_delay_ms] || 5000.0
+        @jitter_factor = config[:jitter_factor] || 0.1
+        @fail_on_error = config.fetch(:fail_on_error, true)
+      end
+
+      # Execute block with retry logic.
+      #
+      # @param adapter [E11y::Adapters::Base] Adapter instance
+      # @param event [Hash] Event data
+      # @yield Block to execute (adapter send)
+      # @return [Object] Result of block execution
+      # @raise [RetryExhaustedError] if all retries fail and fail_on_error is true
+      def with_retry(adapter:, event:)
+        attempt = 0
+
+        loop do
+          attempt += 1
+
+          begin
+            result = yield
+            on_success(adapter, event, attempt)
+            return result # Return actual result, not true
+          rescue StandardError => e
+            # Check if error is retriable
+            unless retriable_error?(e)
+              on_permanent_failure(adapter, event, e, attempt)
+              raise RetryExhaustedError.new(e, retry_count: attempt) if @fail_on_error
+
+              return nil
+            end
+
+            # Check if max attempts reached
+            if attempt >= @max_attempts
+              on_max_retries_exhausted(adapter, event, e, attempt)
+              raise RetryExhaustedError.new(e, retry_count: attempt) if @fail_on_error
+
+              return nil
+            end
+
+            # Calculate backoff delay
+            delay_ms = calculate_backoff_delay(attempt)
+            on_retry_attempt(adapter, event, e, attempt, delay_ms)
+
+            # Sleep with backoff
+            sleep(delay_ms / 1000.0)
+          end
+        end
+      end
+
+      private
+
+      # Check if error should be retried.
+      #
+      # @param error [StandardError] The error that occurred
+      # @return [Boolean] true if error is retriable
+      def retriable_error?(error)
+        # Check if error class is in transient errors list
+        return true if TRANSIENT_ERRORS.any? { |klass| error.is_a?(klass) }
+
+        # Check HTTP status codes (if error has response)
+        if error.respond_to?(:response) && error.response.respond_to?(:code)
+          status_code = error.response.code.to_i
+          return true if RETRIABLE_HTTP_STATUS_CODES.cover?(status_code)
+        end
+
+        false
+      end
+
+      # Calculate exponential backoff delay with jitter.
+      #
+      # Formula: base_delay * (2 ^ attempt) + jitter
+      # Jitter: random value between [-jitter_factor * delay, +jitter_factor * delay]
+      #
+      # @param attempt [Integer] Current attempt number (1-indexed)
+      # @return [Float] Delay in milliseconds
+      def calculate_backoff_delay(attempt)
+        # Exponential backoff: base * 2^(attempt-1)
+        exponential_delay = @base_delay_ms * (2**(attempt - 1))
+
+        # Cap at max_delay
+        exponential_delay = [@max_delay_ms, exponential_delay].min
+
+        # Add jitter: +/- jitter_factor * delay
+        jitter_range = exponential_delay * @jitter_factor
+        jitter = rand(-jitter_range..jitter_range)
+
+        exponential_delay + jitter
+      end
+
+      # Handle successful execution.
+      def on_success(adapter, _event, attempt)
+        increment_metric("e11y.retry.success", adapter: adapter.class.name, attempts: attempt)
+
+        # Log if retry was needed
+        return unless attempt > 1
+
+        increment_metric("e11y.retry.recovered", adapter: adapter.class.name, attempts: attempt)
+      end
+
+      # Handle permanent failure (non-retriable error).
+      def on_permanent_failure(adapter, _event, error, attempt)
+        increment_metric(
+          "e11y.retry.permanent_failure",
+          adapter: adapter.class.name,
+          error: error.class.name,
+          attempt: attempt
+        )
+      end
+
+      # Handle max retries exhausted (all attempts failed).
+      def on_max_retries_exhausted(adapter, _event, error, attempt)
+        increment_metric(
+          "e11y.retry.exhausted",
+          adapter: adapter.class.name,
+          error: error.class.name,
+          attempts: attempt
+        )
+      end
+
+      # Handle retry attempt.
+      def on_retry_attempt(adapter, _event, error, attempt, delay_ms)
+        increment_metric(
+          "e11y.retry.attempt",
+          adapter: adapter.class.name,
+          error: error.class.name,
+          attempt: attempt
+        )
+
+        # Track backoff delay histogram
+        track_histogram("e11y.retry.backoff_delay_ms", delay_ms, adapter: adapter.class.name)
+      end
+
+      # Increment retry metric.
+      #
+      # @param metric_name [String] Metric name
+      # @param tags [Hash] Additional tags
+      def increment_metric(metric_name, tags = {})
+        # TODO: Integrate with Yabeda metrics
+        # E11y::Metrics.increment(metric_name, tags)
+      end
+
+      # Track histogram metric.
+      #
+      # @param metric_name [String] Metric name
+      # @param value [Numeric] Value to track
+      # @param tags [Hash] Additional tags
+      def track_histogram(metric_name, value, tags = {})
+        # TODO: Integrate with Yabeda metrics
+        # E11y::Metrics.histogram(metric_name, value, tags)
+      end
+    end
+  end
+end

data/lib/e11y/reliability/retry_rate_limiter.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module E11y
+  module Reliability
+    # Retry Rate Limiter prevents thundering herd on adapter recovery.
+    #
+    # Implements staged batching with jitter to smooth retry load.
+    # Prevents retry storms when adapters recover from failures.
+    #
+    # @example Usage
+    #   limiter = RetryRateLimiter.new(limit: 50, window: 1.0)
+    #
+    #   limiter.allow?(adapter_name, event_data)  # => true/false
+    #
+    # @see ADR-013 §3.5 (C06 Resolution: Retry Rate Limiting)
+    # @see UC-021 §5 (Retry Storm Prevention)
+    class RetryRateLimiter
+      # @param limit [Integer] Max retries per window (default: 50 retries/sec)
+      # @param window [Float] Window size in seconds (default: 1.0)
+      # @param on_limit_exceeded [Symbol] Action when limit exceeded (:delay or :dlq, default: :delay)
+      # @param jitter_range [Float] Jitter factor (0.0-1.0, default: 0.2 = ±20%)
+      def initialize(limit: 50, window: 1.0, on_limit_exceeded: :delay, jitter_range: 0.2)
+        @limit = limit
+        @window = window
+        @on_limit_exceeded = on_limit_exceeded
+        @jitter_range = jitter_range
+
+        # Track retry counts per adapter per window
+        @retry_counts = Hash.new { |h, k| h[k] = [] }
+        @mutex = Mutex.new
+      end
+
+      # Check if retry is allowed for adapter.
+      #
+      # @param adapter_name [String] Adapter name
+      # @param event_data [Hash] Event data (optional, for metrics)
+      # @return [Boolean] true if retry allowed
+      def allow?(adapter_name, event_data = {})
+        @mutex.synchronize do
+          cleanup_old_entries(adapter_name)
+
+          current_count = @retry_counts[adapter_name].size
+
+          if current_count >= @limit
+            on_limit_exceeded(adapter_name, event_data)
+            false
+          else
+            @retry_counts[adapter_name] << Time.now
+            increment_metric("e11y.retry_rate_limiter.allowed", adapter: adapter_name)
+            true
+          end
+        end
+      end
+
+      # Get current retry rate for adapter.
+      #
+      # @param adapter_name [String] Adapter name
+      # @return [Hash] Current stats (count, limit, window)
+      def stats(adapter_name)
+        @mutex.synchronize do
+          cleanup_old_entries(adapter_name)
+
+          {
+            adapter: adapter_name,
+            current_count: @retry_counts[adapter_name].size,
+            limit: @limit,
+            window: @window,
+            utilization: (@retry_counts[adapter_name].size.to_f / @limit * 100).round(2)
+          }
+        end
+      end
+
+      # Reset retry counts for adapter (for testing).
+      #
+      # @param adapter_name [String] Adapter name
+      def reset!(adapter_name = nil)
+        @mutex.synchronize do
+          if adapter_name
+            @retry_counts.delete(adapter_name)
+          else
+            @retry_counts.clear
+          end
+        end
+      end
+
+      private
+
+      # Remove retry entries outside current window.
+      def cleanup_old_entries(adapter_name)
+        cutoff_time = Time.now - @window
+        @retry_counts[adapter_name].reject! { |timestamp| timestamp < cutoff_time }
+      end
+
+      # Handle limit exceeded based on configured strategy.
+      def on_limit_exceeded(adapter_name, _event_data)
+        increment_metric("e11y.retry_rate_limiter.exceeded", adapter: adapter_name)
+
+        case @on_limit_exceeded
+        when :delay
+          # Calculate delay with jitter
+          delay_sec = @window + rand((-@jitter_range * @window)..(@jitter_range * @window))
+          increment_metric("e11y.retry_rate_limiter.delayed", adapter: adapter_name, delay_sec: delay_sec)
+          # Caller should sleep(delay_sec) before retry
+        when :dlq
+          # Caller should save to DLQ instead of retrying
+          increment_metric("e11y.retry_rate_limiter.dlq", adapter: adapter_name)
+        end
+      end
+
+      # Increment retry rate limiter metric.
+      def increment_metric(metric_name, tags = {})
+        # TODO: Integrate with Yabeda metrics
+        # E11y::Metrics.increment(metric_name, tags)
+      end
+    end
+  end
+end

data/lib/e11y/sampling/error_spike_detector.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module E11y
+  module Sampling
+    # Error Spike Detector for Adaptive Sampling (FEAT-4838.1)
+    #
+    # Detects sudden increases in error rates and adjusts sampling accordingly.
+    # Implements error-based adaptive sampling strategy from ADR-009 §3.2.
+    #
+    # Features:
+    # - Sliding window for error rate calculation
+    # - Absolute threshold (errors/minute)
+    # - Relative threshold (ratio to baseline)
+    # - Per-event and global error tracking
+    #
+    # @example Configuration
+    #   detector = E11y::Sampling::ErrorSpikeDetector.new(
+    #     window: 60,                    # 60 seconds sliding window
+    #     absolute_threshold: 100,       # 100 errors/min triggers spike
+    #     relative_threshold: 3.0,       # 3x normal rate triggers spike
+    #     spike_duration: 300            # Keep 100% sampling for 5 minutes
+    #   )
+    #
+    # @example Usage
+    #   if detector.error_spike?
+    #     sample_rate = 1.0  # 100% sampling during spike
+    #   else
+    #     sample_rate = 0.1  # 10% normal sampling
+    #   end
+    #
+    #   detector.record_event(event_name: "payment.processed", severity: :error)
+    class ErrorSpikeDetector
+      # Default configuration
+      DEFAULT_WINDOW = 60              # 60 seconds sliding window
+      DEFAULT_ABSOLUTE_THRESHOLD = 100 # 100 errors/min triggers spike
+      DEFAULT_RELATIVE_THRESHOLD = 3.0 # 3x normal rate triggers spike
+      DEFAULT_SPIKE_DURATION = 300     # Keep elevated sampling for 5 minutes
+
+      attr_reader :window, :absolute_threshold, :relative_threshold, :spike_duration
+
+      # Initialize error spike detector
+      #
+      # @param config [Hash] Configuration options
+      # @option config [Integer] :window (60) Sliding window in seconds
+      # @option config [Integer] :absolute_threshold (100) Errors/min to trigger spike
+      # @option config [Float] :relative_threshold (3.0) Multiplier vs baseline to trigger spike
+      # @option config [Integer] :spike_duration (300) Seconds to keep elevated sampling
+      def initialize(config = {})
+        @window = config.fetch(:window, DEFAULT_WINDOW)
+        @absolute_threshold = config.fetch(:absolute_threshold, DEFAULT_ABSOLUTE_THRESHOLD)
+        @relative_threshold = config.fetch(:relative_threshold, DEFAULT_RELATIVE_THRESHOLD)
+        @spike_duration = config.fetch(:spike_duration, DEFAULT_SPIKE_DURATION)
+
+        # Event tracking (per event name)
+        @error_events = Hash.new { |h, k| h[k] = [] }  # event_name => [timestamp, ...]
+        @all_errors = []                               # All errors (global)
+        @baseline_rates = Hash.new(0.0)                # event_name => baseline error rate
+
+        # Spike state
+        @spike_started_at = nil
+        @mutex = Mutex.new
+      end
+
+      # Check if currently in error spike state
+      #
+      # @return [Boolean] true if error spike detected
+      def error_spike?
+        @mutex.synchronize do
+          # Check if spike is still active (within spike_duration)
+          if @spike_started_at
+            elapsed = Time.now - @spike_started_at
+            return true if elapsed < @spike_duration
+
+            # Spike expired - check if it should continue
+            if spike_detected?
+              @spike_started_at = Time.now # Extend spike
+              return true
+            else
+              @spike_started_at = nil # End spike
+              return false
+            end
+          end
+
+          # Check for new spike
+          if spike_detected?
+            @spike_started_at = Time.now
+            return true
+          end
+
+          false
+        end
+      end
+
+      # Record an event for error rate tracking
+      #
+      # @param event_data [Hash] Event payload
+      # @option event_data [String] :event_name Event name
+      # @option event_data [Symbol] :severity Event severity
+      def record_event(event_data)
+        return unless error_severity?(event_data[:severity])
+
+        @mutex.synchronize do
+          now = Time.now
+          event_name = event_data[:event_name]
+
+          # Record error
+          @error_events[event_name] << now
+          @all_errors << now
+
+          # Cleanup old events (outside window)
+          cleanup_old_events(now)
+
+          # Update baseline (if not in spike)
+          update_baseline(event_name) unless @spike_started_at
+        end
+      end
+
+      # Get current error rate (errors per minute)
+      #
+      # @param event_name [String, nil] Event name, or nil for global rate
+      # @return [Float] Errors per minute
+      def current_error_rate(event_name = nil)
+        @mutex.synchronize do
+          now = Time.now
+          cleanup_old_events(now)
+
+          events = event_name ? @error_events[event_name] : @all_errors
+          count = events.count { |ts| (now - ts) <= @window }
+
+          # Convert to per-minute rate
+          (count.to_f / @window) * 60
+        end
+      end
+
+      # Get baseline error rate
+      #
+      # @param event_name [String] Event name
+      # @return [Float] Baseline errors per minute
+      def baseline_error_rate(event_name)
+        @mutex.synchronize { @baseline_rates[event_name] }
+      end
+
+      # Reset detector state (useful for testing)
+      def reset!
+        @mutex.synchronize do
+          @error_events.clear
+          @all_errors.clear
+          @baseline_rates.clear
+          @spike_started_at = nil
+        end
+      end
+
+      private
+
+      # Check if severity is an error
+      #
+      # @param severity [Symbol, nil] Severity level
+      # @return [Boolean] true if error or fatal
+      def error_severity?(severity)
+        %i[error fatal].include?(severity)
+      end
+
+      # Detect if spike conditions are met
+      #
+      # @return [Boolean] true if spike detected
+      def spike_detected?
+        # Check absolute threshold (global)
+        global_rate = current_error_rate_unsafe
+        return true if global_rate > @absolute_threshold
+
+        # Check relative threshold (per event name)
+        @error_events.each_key do |event_name|
+          current_rate = current_error_rate_unsafe(event_name)
+          baseline = @baseline_rates[event_name]
+
+          # Only check relative if we have a baseline
+          return true if baseline.positive? && current_rate > (baseline * @relative_threshold)
+        end
+
+        false
+      end
+
+      # Get current error rate (unsafe - must be called within mutex)
+      #
+      # @param event_name [String, nil] Event name, or nil for global
+      # @return [Float] Errors per minute
+      def current_error_rate_unsafe(event_name = nil)
+        now = Time.now
+        events = event_name ? @error_events[event_name] : @all_errors
+        count = events.count { |ts| (now - ts) <= @window }
+        (count.to_f / @window) * 60
+      end
+
+      # Update baseline error rate (unsafe - must be called within mutex)
+      #
+      # @param event_name [String] Event name
+      def update_baseline(event_name)
+        # Exponential moving average (EMA) with alpha = 0.1
+        current_rate = current_error_rate_unsafe(event_name)
+        old_baseline = @baseline_rates[event_name]
+
+        @baseline_rates[event_name] = if old_baseline.zero?
+                                        current_rate
+                                      else
+                                        (0.1 * current_rate) + (0.9 * old_baseline)
+                                      end
+      end
+
+      # Cleanup events outside the sliding window
+      #
+      # @param now [Time] Current timestamp
+      def cleanup_old_events(now)
+        cutoff = now - @window
+
+        # Cleanup per-event errors
+        @error_events.each_value do |events|
+          events.reject! { |ts| ts < cutoff }
+        end
+
+        # Cleanup global errors
+        @all_errors.reject! { |ts| ts < cutoff }
+      end
+    end
+  end
+end