e11y 0.1.0

data/lib/e11y/sampling/load_monitor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module E11y
+  module Sampling
+    # Load Monitor for Adaptive Sampling (FEAT-4842.1)
+    #
+    # Monitors system load and event volume to enable load-based adaptive sampling.
+    # Implements load-based sampling strategy from ADR-009 §3.3.
+    #
+    # Features:
+    # - Event volume tracking (events/second)
+    # - Tiered load levels (normal, high, overload)
+    # - Sliding window for rate calculation
+    # - Thread-safe concurrent access
+    #
+    # @example Configuration
+    #   monitor = E11y::Sampling::LoadMonitor.new(
+    #     window: 60,                    # 60 seconds sliding window
+    #     thresholds: {
+    #       normal: 1_000,               # 0-1k events/sec → 100% sampling
+    #       high: 10_000,                # 1k-10k events/sec → 50% sampling
+    #       very_high: 50_000,           # 10k-50k events/sec → 10% sampling
+    #       overload: 100_000            # >50k events/sec → 1% sampling
+    #     }
+    #   )
+    #
+    # @example Usage
+    #   monitor.record_event
+    #
+    #   sample_rate = case monitor.load_level
+    #                 when :normal then 1.0
+    #                 when :high then 0.5
+    #                 when :very_high then 0.1
+    #                 when :overload then 0.01
+    #                 end
+    class LoadMonitor
+      # Default configuration
+      DEFAULT_WINDOW = 60              # 60 seconds sliding window
+      DEFAULT_THRESHOLDS = {
+        normal: 1_000,                 # 0-1k events/sec → 100% sampling
+        high: 10_000,                  # 1k-10k events/sec → 50% sampling
+        very_high: 50_000,             # 10k-50k events/sec → 10% sampling
+        overload: 100_000              # >100k events/sec → 1% sampling
+      }.freeze
+
+      attr_reader :window, :thresholds
+
+      # Initialize load monitor
+      #
+      # @param config [Hash] Configuration options
+      # @option config [Integer] :window (60) Sliding window in seconds
+      # @option config [Hash] :thresholds ({}) Load thresholds (events/sec)
+      def initialize(config = {})
+        @window = config.fetch(:window, DEFAULT_WINDOW)
+        @thresholds = DEFAULT_THRESHOLDS.merge(config.fetch(:thresholds, {}))
+
+        # Event tracking
+        @events = [] # Timestamps of tracked events
+        @mutex = Mutex.new
+      end
+
+      # Record an event for load tracking
+      def record_event
+        @mutex.synchronize do
+          now = Time.now
+          @events << now
+
+          # Cleanup old events (outside window)
+          cleanup_old_events(now)
+        end
+      end
+
+      # Get current event rate (events per second)
+      #
+      # @return [Float] Events per second
+      def current_rate
+        @mutex.synchronize do
+          now = Time.now
+          cleanup_old_events(now)
+
+          count = @events.count { |ts| (now - ts) <= @window }
+          count.to_f / @window
+        end
+      end
+
+      # Get current load level
+      #
+      # @return [Symbol] Load level (:normal, :high, :very_high, :overload)
+      def load_level
+        rate = current_rate
+
+        # Check thresholds in descending order
+        if rate >= @thresholds[:overload]
+          :overload
+        elsif rate >= @thresholds[:very_high]
+          :very_high
+        elsif rate >= @thresholds[:high]
+          :high
+        elsif rate >= @thresholds[:normal]
+          :high # Between normal and high threshold
+        else
+          :normal
+        end
+      end
+
+      # Get recommended sample rate for current load
+      #
+      # @return [Float] Sample rate (0.0-1.0)
+      def recommended_sample_rate
+        case load_level
+        when :normal
+          1.0   # 100% sampling
+        when :high
+          0.5   # 50% sampling
+        when :very_high
+          0.1   # 10% sampling
+        when :overload
+          0.01  # 1% sampling
+        end
+      end
+
+      # Check if system is overloaded
+      #
+      # @return [Boolean] true if overload level reached
+      def overloaded?
+        load_level == :overload
+      end
+
+      # Reset monitor state (useful for testing)
+      def reset!
+        @mutex.synchronize do
+          @events.clear
+        end
+      end
+
+      # Get load statistics
+      #
+      # @return [Hash] Statistics (rate, level, sample_rate, event_count)
+      def stats
+        # Don't wrap in mutex - methods already handle locking
+        {
+          rate: current_rate,
+          level: load_level,
+          sample_rate: recommended_sample_rate,
+          event_count: @mutex.synchronize { @events.size },
+          window: @window
+        }
+      end
+
+      private
+
+      # Cleanup events outside the sliding window
+      #
+      # @param now [Time] Current timestamp
+      def cleanup_old_events(now)
+        cutoff = now - @window
+        @events.reject! { |ts| ts < cutoff }
+      end
+    end
+  end
+end

data/lib/e11y/sampling/stratified_tracker.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module E11y
+  module Sampling
+    # Stratified Sampling Tracker for SLO accuracy (FEAT-4851, C11 Resolution)
+    #
+    # Tracks sampling statistics per severity stratum to enable sampling correction
+    # in SLO calculations. Ensures accurate SLO metrics even with aggressive sampling.
+    #
+    # @example Usage in sampling middleware
+    #   tracker = StratifiedTracker.new
+    #   tracker.record_sample(severity: :success, sample_rate: 0.1, sampled: true)
+    #   tracker.record_sample(severity: :error, sample_rate: 1.0, sampled: true)
+    #
+    #   correction = tracker.sampling_correction(:success) # => 10.0 (1/0.1)
+    #
+    # @see ADR-009 §3.7 Stratified Sampling for SLO Accuracy
+    # @see UC-014 Adaptive Sampling (C11 Resolution)
+    class StratifiedTracker
+      # @return [Hash{Symbol => Hash}] Stratum statistics
+      attr_reader :strata
+
+      def initialize
+        @strata = Hash.new { |h, k| h[k] = { sampled_count: 0, total_count: 0, sample_rate_sum: 0.0 } }
+        @mutex = Mutex.new
+      end
+
+      # Record a sampling decision for a severity stratum
+      #
+      # @param severity [Symbol] Event severity (:debug, :info, :success, :warn, :error, :fatal)
+      # @param sample_rate [Float] Sample rate used (0.0-1.0)
+      # @param sampled [Boolean] Whether event was sampled
+      # @return [void]
+      def record_sample(severity:, sample_rate:, sampled:)
+        @mutex.synchronize do
+          stratum = @strata[severity]
+          stratum[:total_count] += 1
+          stratum[:sampled_count] += 1 if sampled
+          stratum[:sample_rate_sum] += sample_rate
+        end
+      end
+
+      # Get sampling correction factor for a severity
+      #
+      # Correction factor = 1 / sample_rate
+      # Multiply observed counts by this to estimate true counts.
+      #
+      # @param severity [Symbol] Event severity
+      # @return [Float] Correction factor (1.0 if no samples)
+      def sampling_correction(severity)
+        @mutex.synchronize do
+          stratum = @strata[severity]
+          return 1.0 if stratum[:sampled_count].zero?
+
+          # Average sample rate for this stratum
+          avg_sample_rate = stratum[:sample_rate_sum] / stratum[:total_count]
+          return 1.0 if avg_sample_rate.zero?
+
+          1.0 / avg_sample_rate
+        end
+      end
+
+      # Get statistics for a severity stratum
+      #
+      # @param severity [Symbol] Event severity
+      # @return [Hash] Stratum statistics
+      def stratum_stats(severity)
+        @mutex.synchronize do
+          @strata[severity].dup
+        end
+      end
+
+      # Get statistics for all strata
+      #
+      # @return [Hash{Symbol => Hash}] All stratum statistics
+      def all_strata_stats
+        @mutex.synchronize do
+          @strata.transform_values(&:dup)
+        end
+      end
+
+      # Reset all statistics
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          @strata.clear
+        end
+      end
+    end
+  end
+end

data/lib/e11y/sampling/value_extractor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module E11y
+  module Sampling
+    # ValueExtractor for extracting numeric values from event payloads (FEAT-4847)
+    #
+    # Supports:
+    # - Nested field access (dot notation: "user.balance")
+    # - Type coercion (strings to numbers)
+    # - Nil handling (returns 0.0 for missing fields)
+    #
+    # Used by value-based sampling to prioritize high-value events.
+    #
+    # @example Basic usage
+    #   extractor = ValueExtractor.new
+    #   event_data = { amount: 1500, currency: "USD" }
+    #   value = extractor.extract(event_data, :amount) # => 1500.0
+    #
+    # @example Nested fields
+    #   event_data = { user: { balance: 5000 } }
+    #   value = extractor.extract(event_data, "user.balance") # => 5000.0
+    #
+    # @example Type coercion
+    #   event_data = { amount: "1234.56" }
+    #   value = extractor.extract(event_data, :amount) # => 1234.56
+    #
+    # @example Nil handling
+    #   event_data = {}
+    #   value = extractor.extract(event_data, :missing) # => 0.0
+    class ValueExtractor
+      # Extract numeric value from event data
+      #
+      # @param event_data [Hash] Event payload
+      # @param field [String, Symbol] Field path (supports dot notation for nested fields)
+      # @return [Float] Extracted value (0.0 if field is missing or non-numeric)
+      def extract(event_data, field)
+        value = navigate_to_field(event_data, field)
+        coerce_to_number(value)
+      end
+
+      private
+
+      # Navigate to nested field using dot notation
+      #
+      # @param data [Hash] Current data hash
+      # @param field [String, Symbol] Field path
+      # @return [Object, nil] Field value or nil if not found
+      def navigate_to_field(data, field)
+        return nil unless data.is_a?(Hash)
+
+        field_path = field.to_s.split(".")
+        field_path.reduce(data) do |current, key|
+          break nil unless current.is_a?(Hash)
+
+          current[key.to_sym] || current[key.to_s]
+        end
+      end
+
+      # Coerce value to Float
+      #
+      # @param value [Object] Value to coerce
+      # @return [Float] Numeric value (0.0 for nil or non-coercible)
+      def coerce_to_number(value)
+        return 0.0 if value.nil?
+
+        case value
+        when Numeric
+          value.to_f
+        when String
+          # Try to convert string to float
+          Float(value)
+        else
+          # Non-numeric types default to 0.0
+          0.0
+        end
+      rescue ArgumentError, TypeError
+        # Invalid numeric string or type - return 0.0
+        0.0
+      end
+    end
+  end
+end

data/lib/e11y/self_monitoring/buffer_monitor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "e11y/metrics"
+
+module E11y
+  module SelfMonitoring
+    # Buffer monitoring for E11y internal operations.
+    #
+    # Tracks buffer metrics:
+    # - Buffer size (current utilization)
+    # - Buffer overflows
+    # - Buffer flushes
+    #
+    # @see ADR-016 §3.3 (Buffer Metrics)
+    # @example
+    #   E11y::SelfMonitoring::BufferMonitor.track_buffer_size(42, buffer_type: 'ring')
+    module BufferMonitor
+      # Track current buffer size.
+      #
+      # @param size [Integer] Current number of events in buffer
+      # @param buffer_type [String] Buffer type (e.g., 'ring', 'request_scoped')
+      # @return [void]
+      def self.track_buffer_size(size, buffer_type:)
+        E11y::Metrics.gauge(
+          :e11y_buffer_size,
+          size,
+          { buffer_type: buffer_type }
+        )
+      end
+
+      # Track buffer overflow (event dropped due to full buffer).
+      #
+      # @param buffer_type [String] Buffer type
+      # @return [void]
+      def self.track_buffer_overflow(buffer_type:)
+        E11y::Metrics.increment(
+          :e11y_buffer_overflows_total,
+          { buffer_type: buffer_type }
+        )
+      end
+
+      # Track buffer flush operation.
+      #
+      # @param buffer_type [String] Buffer type
+      # @param event_count [Integer] Number of events flushed
+      # @param trigger [String] Flush trigger (e.g., 'size', 'timeout', 'explicit')
+      # @return [void]
+      def self.track_buffer_flush(buffer_type:, event_count:, trigger:)
+        E11y::Metrics.increment(
+          :e11y_buffer_flushes_total,
+          {
+            buffer_type: buffer_type,
+            trigger: trigger
+          }
+        )
+
+        E11y::Metrics.histogram(
+          :e11y_buffer_flush_events_count,
+          event_count,
+          { buffer_type: buffer_type },
+          buckets: [1, 10, 50, 100, 500, 1000, 5000]
+        )
+      end
+
+      # Track buffer utilization (percentage).
+      #
+      # @param utilization_percent [Numeric] Buffer utilization percentage (0-100)
+      # @param buffer_type [String] Buffer type
+      # @return [void]
+      def self.track_buffer_utilization(utilization_percent, buffer_type:)
+        E11y::Metrics.gauge(
+          :e11y_buffer_utilization_percent,
+          utilization_percent,
+          { buffer_type: buffer_type }
+        )
+      end
+    end
+  end
+end

data/lib/e11y/self_monitoring/performance_monitor.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "e11y/metrics"
+
+module E11y
+  module SelfMonitoring
+    # Performance monitoring for E11y internal operations.
+    #
+    # Tracks latency metrics for:
+    # - Event tracking (E11y.track)
+    # - Middleware execution
+    # - Adapter writes
+    # - Buffer flushes
+    #
+    # @see ADR-016 §3.1 (Performance Metrics)
+    # @example
+    #   E11y::SelfMonitoring::PerformanceMonitor.track_latency(0.5, event_class: 'OrderCreated', severity: :info)
+    module PerformanceMonitor
+      # Track E11y.track() latency.
+      #
+      # @param duration_ms [Numeric] Duration in milliseconds
+      # @param event_class [String] Event class name
+      # @param severity [Symbol] Event severity
+      # @return [void]
+      def self.track_latency(duration_ms, event_class:, severity:)
+        E11y::Metrics.histogram(
+          :e11y_track_duration_seconds,
+          duration_ms / 1000.0,
+          {
+            event_class: event_class,
+            severity: severity
+          },
+          buckets: [0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1] # 0.1ms to 100ms
+        )
+      end
+
+      # Track middleware execution time.
+      #
+      # @param middleware_name [String] Middleware class name
+      # @param duration_ms [Numeric] Duration in milliseconds
+      # @return [void]
+      def self.track_middleware_latency(middleware_name, duration_ms)
+        E11y::Metrics.histogram(
+          :e11y_middleware_duration_seconds,
+          duration_ms / 1000.0,
+          { middleware: middleware_name },
+          buckets: [0.00001, 0.0001, 0.0005, 0.001, 0.005] # 0.01ms to 5ms
+        )
+      end
+
+      # Track adapter send latency.
+      #
+      # @param adapter_name [String] Adapter class name
+      # @param duration_ms [Numeric] Duration in milliseconds
+      # @return [void]
+      def self.track_adapter_latency(adapter_name, duration_ms)
+        E11y::Metrics.histogram(
+          :e11y_adapter_send_duration_seconds,
+          duration_ms / 1000.0,
+          { adapter: adapter_name },
+          buckets: [0.001, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0] # 1ms to 5s
+        )
+      end
+
+      # Track buffer flush latency.
+      #
+      # @param duration_ms [Numeric] Duration in milliseconds
+      # @param event_count [Integer] Number of events flushed
+      # @return [void]
+      def self.track_flush_latency(duration_ms, event_count)
+        E11y::Metrics.histogram(
+          :e11y_buffer_flush_duration_seconds,
+          duration_ms / 1000.0,
+          { event_count_bucket: bucket_event_count(event_count) },
+          buckets: [0.001, 0.01, 0.05, 0.1, 0.5, 1.0]
+        )
+      end
+
+      # Convert event count to a low-cardinality bucket label.
+      #
+      # @param count [Integer] Event count
+      # @return [String] Bucket label
+      # @api private
+      def self.bucket_event_count(count)
+        case count
+        when 0..10 then "1-10"
+        when 11..50 then "11-50"
+        when 51..100 then "51-100"
+        when 101..500 then "101-500"
+        else "500+"
+        end
+      end
+
+      private_class_method :bucket_event_count
+    end
+  end
+end

data/lib/e11y/self_monitoring/reliability_monitor.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "e11y/metrics"
+
+module E11y
+  module SelfMonitoring
+    # Reliability monitoring for E11y internal operations.
+    #
+    # Tracks success/failure rates for:
+    # - Event tracking
+    # - Adapter writes
+    # - Buffer operations
+    # - DLQ saves
+    #
+    # @see ADR-016 §3.2 (Reliability Metrics)
+    # @example
+    #   E11y::SelfMonitoring::ReliabilityMonitor.track_event_success(event_type: 'order.created')
+    module ReliabilityMonitor
+      # Track successful event tracking.
+      #
+      # @param event_type [String] Event type/name
+      # @return [void]
+      def self.track_event_success(event_type:)
+        E11y::Metrics.increment(
+          :e11y_events_tracked_total,
+          {
+            event_type: event_type,
+            status: "success"
+          }
+        )
+      end
+
+      # Track failed event tracking.
+      #
+      # @param event_type [String] Event type/name
+      # @param reason [String] Failure reason (e.g., 'validation_error', 'adapter_error')
+      # @return [void]
+      def self.track_event_failure(event_type:, reason:)
+        E11y::Metrics.increment(
+          :e11y_events_tracked_total,
+          {
+            event_type: event_type,
+            status: "failure",
+            reason: reason
+          }
+        )
+      end
+
+      # Track dropped event (rate limited, sampled out, etc).
+      #
+      # @param event_type [String] Event type/name
+      # @param reason [String] Drop reason (e.g., 'rate_limited', 'sampled_out')
+      # @return [void]
+      def self.track_event_dropped(event_type:, reason:)
+        E11y::Metrics.increment(
+          :e11y_events_dropped_total,
+          {
+            event_type: event_type,
+            reason: reason
+          }
+        )
+      end
+
+      # Track adapter write success.
+      #
+      # @param adapter_name [String] Adapter class name
+      # @return [void]
+      def self.track_adapter_success(adapter_name:)
+        E11y::Metrics.increment(
+          :e11y_adapter_writes_total,
+          {
+            adapter: adapter_name,
+            status: "success"
+          }
+        )
+      end
+
+      # Track adapter write failure.
+      #
+      # @param adapter_name [String] Adapter class name
+      # @param error_class [String] Error class name
+      # @return [void]
+      def self.track_adapter_failure(adapter_name:, error_class:)
+        E11y::Metrics.increment(
+          :e11y_adapter_writes_total,
+          {
+            adapter: adapter_name,
+            status: "failure",
+            error_class: error_class
+          }
+        )
+      end
+
+      # Track DLQ save operation.
+      #
+      # @param reason [String] Reason for DLQ save (e.g., 'adapter_error', 'rate_limited')
+      # @return [void]
+      def self.track_dlq_save(reason:)
+        E11y::Metrics.increment(
+          :e11y_dlq_saves_total,
+          { reason: reason }
+        )
+      end
+
+      # Track DLQ replay operation.
+      #
+      # @param status [String] Replay status ('success' or 'failure')
+      # @return [void]
+      def self.track_dlq_replay(status:)
+        E11y::Metrics.increment(
+          :e11y_dlq_replays_total,
+          { status: status }
+        )
+      end
+
+      # Track circuit breaker state change.
+      #
+      # @param adapter_name [String] Adapter class name
+      # @param state [String] New circuit state ('open', 'half_open', 'closed')
+      # @return [void]
+      def self.track_circuit_state(adapter_name:, state:)
+        E11y::Metrics.gauge(
+          :e11y_circuit_breaker_state,
+          state_to_value(state),
+          { adapter: adapter_name }
+        )
+      end
+
+      # Convert circuit state to numeric value for gauge.
+      #
+      # @param state [String] Circuit state
+      # @return [Integer] Numeric representation (0=closed, 1=half_open, 2=open)
+      # @api private
+      def self.state_to_value(state)
+        case state
+        when "closed" then 0
+        when "half_open" then 1
+        when "open" then 2
+        else 0
+        end
+      end
+
+      private_class_method :state_to_value
+    end
+  end
+end