e11y 0.1.0

data/lib/e11y/logger/bridge.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module E11y
+  module Logger
+    # Rails.logger Bridge (SimpleDelegator wrapper)
+    #
+    # Transparent wrapper around Rails.logger that:
+    # 1. Delegates all calls to the original logger (preserves Rails behavior)
+    # 2. Optionally tracks log calls as E11y events (when enabled)
+    #
+    # **Why SimpleDelegator instead of full replacement:**
+    # - ✅ Simpler: No need to reimplement entire Logger API
+    # - ✅ Safer: Preserves all Rails.logger behavior
+    # - ✅ Flexible: Can be enabled/disabled without breaking anything
+    # - ✅ Rails Way: Extends functionality without replacing core components
+    #
+    # @example Basic usage
+    #   # Automatically enabled by E11y::Railtie if config.logger_bridge.enabled = true
+    #   Rails.logger = E11y::Logger::Bridge.new(Rails.logger)
+    #
+    # @example Manual setup
+    #   E11y.configure do |config|
+    #     config.logger_bridge.enabled = true
+    #     config.logger_bridge.track_to_e11y = true  # Send logs to E11y events (optional)
+    #   end
+    #
+    # @see ADR-008 §7 (Rails.logger Migration)
+    # @see UC-016 (Rails Logger Migration)
+    class Bridge < SimpleDelegator
+      # Setup Rails.logger bridge
+      #
+      # Wraps Rails.logger with E11y::Logger::Bridge.
+      #
+      # @return [void]
+      def self.setup!
+        return unless E11y.config.logger_bridge&.enabled
+        return unless defined?(Rails)
+
+        # Wrap Rails.logger (preserves original behavior)
+        Rails.logger = Bridge.new(Rails.logger)
+      end
+
+      # Initialize bridge wrapper
+      # @param original_logger [Logger] Original Rails logger
+      def initialize(original_logger)
+        super
+        @severity_mapping = {
+          ::Logger::DEBUG => :debug,
+          ::Logger::INFO => :info,
+          ::Logger::WARN => :warn,
+          ::Logger::ERROR => :error,
+          ::Logger::FATAL => :fatal,
+          ::Logger::UNKNOWN => :warn
+        }
+      end
+
+      # Intercept logger methods to optionally track to E11y
+      # All calls are delegated to the original logger via SimpleDelegator
+
+      # Log debug message
+      # @param message [String, nil] Log message
+      # @yield Block that returns log message
+      # @return [true] Always returns true (Logger API)
+      def debug(message = nil, &)
+        track_to_e11y(:debug, message, &) if should_track_severity?(:debug)
+        super # Delegate to original logger
+      end
+
+      # Log info message
+      # @param message [String, nil] Log message
+      # @yield Block that returns log message
+      # @return [true] Always returns true (Logger API)
+      def info(message = nil, &)
+        track_to_e11y(:info, message, &) if should_track_severity?(:info)
+        super # Delegate to original logger
+      end
+
+      # Log warn message
+      # @param message [String, nil] Log message
+      # @yield Block that returns log message
+      # @return [true] Always returns true (Logger API)
+      def warn(message = nil, &)
+        track_to_e11y(:warn, message, &) if should_track_severity?(:warn)
+        super # Delegate to original logger
+      end
+
+      # Log error message
+      # @param message [String, nil] Log message
+      # @yield Block that returns log message
+      # @return [true] Always returns true (Logger API)
+      def error(message = nil, &)
+        track_to_e11y(:error, message, &) if should_track_severity?(:error)
+        super # Delegate to original logger
+      end
+
+      # Log fatal message
+      # @param message [String, nil] Log message
+      # @yield Block that returns log message
+      # @return [true] Always returns true (Logger API)
+      def fatal(message = nil, &)
+        track_to_e11y(:fatal, message, &) if should_track_severity?(:fatal)
+        super # Delegate to original logger
+      end
+
+      # Generic log method
+      # @param severity [Integer] Logger severity constant
+      # @param message [String, nil] Log message
+      # @param progname [String, nil] Program name
+      # @yield Block that returns log message
+      # @return [true] Always returns true (Logger API)
+      def add(severity, message = nil, progname = nil, &)
+        e11y_severity = @severity_mapping[severity] || :info
+        track_to_e11y(e11y_severity, message || progname, &) if should_track_severity?(e11y_severity)
+        super # Delegate to original logger
+      end
+
+      alias log add
+
+      private
+
+      # Check if E11y tracking is enabled for specific severity
+      # Supports both boolean and per-severity Hash configuration
+      #
+      # @param severity [Symbol] E11y severity (:debug, :info, :warn, :error, :fatal)
+      # @return [Boolean]
+      #
+      # @example Boolean config (all or nothing)
+      #   config.logger_bridge.track_to_e11y = true  # Track all
+      #   config.logger_bridge.track_to_e11y = false # Track none
+      #
+      # @example Per-severity config (granular control)
+      #   config.logger_bridge.track_to_e11y = {
+      #     debug: false,
+      #     info: true,
+      #     warn: true,
+      #     error: true,
+      #     fatal: true
+      #   }
+      def should_track_severity?(severity)
+        config = E11y.config.logger_bridge&.track_to_e11y
+        return false unless config
+
+        case config
+        when TrueClass
+          true # Track all severities
+        when FalseClass
+          false # Track none
+        when Hash
+          config[severity] || false # Check per-severity config
+        else
+          false # Unknown config type
+        end
+      end
+
+      # Track log message as E11y event
+      # @param severity [Symbol] E11y severity
+      # @param message [String, nil] Log message
+      # @yield Block that returns log message
+      # @return [void]
+      def track_to_e11y(severity, message = nil, &block)
+        # Extract message
+        msg = message || (block_given? ? block.call : nil)
+        return if msg.nil? || (msg.respond_to?(:empty?) && msg.empty?)
+
+        # Track to E11y using severity-specific class
+        require "e11y/events/rails/log"
+        event_class = event_class_for_severity(severity)
+        event_class.track(
+          message: msg.to_s,
+          caller_location: extract_caller_location
+        )
+      rescue StandardError => e
+        # Silently ignore E11y tracking errors (don't break logging!)
+        # In development/test, you might want to log this
+        warn "E11y logger tracking failed: #{e.message}" if defined?(Rails) && Rails.env.development?
+      end
+
+      # Get event class for severity
+      # @param severity [Symbol] E11y severity
+      # @return [Class] Event class
+      def event_class_for_severity(severity)
+        case severity
+        when :debug then E11y::Events::Rails::Log::Debug
+        when :info then E11y::Events::Rails::Log::Info
+        when :warn then E11y::Events::Rails::Log::Warn
+        when :error then E11y::Events::Rails::Log::Error
+        when :fatal then E11y::Events::Rails::Log::Fatal
+        else E11y::Events::Rails::Log::Info # Fallback
+        end
+      end
+
+      # Extract caller location (first caller outside E11y)
+      # @return [String, nil] Caller location string
+      def extract_caller_location
+        caller_locations.find do |loc|
+          !loc.path.include?("e11y")
+        end&.then do |loc|
+          "#{loc.path}:#{loc.lineno}:in `#{loc.label}'"
+        end
+      end
+    end
+  end
+end

data/lib/e11y/metrics/cardinality_protection.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "cardinality_tracker"
+require_relative "relabeling"
+
+module E11y
+  module Metrics
+    # Cardinality protection for metrics labels.
+    #
+    # Implements 3-layer defense system to prevent cardinality explosions:
+    # 1. Universal Denylist - Block high-cardinality fields (user_id, order_id, etc.)
+    # 2. Per-Metric Limits - Track unique values per metric, drop if exceeded
+    # 3. Dynamic Monitoring - Alert when approaching limits
+    #
+    # Now supports optional relabeling to reduce cardinality while preserving signal.
+    #
+    # @example Basic usage
+    #   protection = E11y::Metrics::CardinalityProtection.new
+    #   labels = { user_id: '123', status: 'paid', currency: 'USD' }
+    #   safe_labels = protection.filter(labels, 'orders.total')
+    #   # => { status: 'paid', currency: 'USD' } (user_id dropped)
+    #
+    # @example With relabeling
+    #   protection = E11y::Metrics::CardinalityProtection.new
+    #   protection.relabel(:http_status) { |v| "#{v.to_i / 100}xx" }
+    #   labels = { http_status: 200, path: '/api/users' }
+    #   safe_labels = protection.filter(labels, 'http.requests')
+    #   # => { http_status: '2xx', path: '/api/users' }
+    #
+    # @see ADR-002 §4 (Cardinality Protection)
+    # @see UC-013 (High Cardinality Protection)
+    class CardinalityProtection
+      # Universal denylist - high-cardinality fields that should NEVER be labels
+      UNIVERSAL_DENYLIST = %i[
+        id
+        user_id
+        order_id
+        session_id
+        request_id
+        trace_id
+        span_id
+        email
+        phone
+        ip_address
+        token
+        api_key
+        password
+        uuid
+        guid
+        timestamp
+        created_at
+        updated_at
+      ].freeze
+
+      # Default per-metric cardinality limit
+      DEFAULT_CARDINALITY_LIMIT = 1000
+
+      attr_reader :tracker, :relabeler
+
+      # Initialize cardinality protection
+      # @param config [Hash] Configuration options
+      # @option config [Integer] :cardinality_limit (1000) Max unique label combinations per metric
+      # @option config [Array<Symbol>] :additional_denylist Additional fields to deny
+      # @option config [Boolean] :enabled (true) Enable/disable protection
+      # @option config [Boolean] :relabeling_enabled (true) Enable/disable relabeling
+      def initialize(config = {})
+        @cardinality_limit = config.fetch(:cardinality_limit, DEFAULT_CARDINALITY_LIMIT)
+        @enabled = config.fetch(:enabled, true)
+        @relabeling_enabled = config.fetch(:relabeling_enabled, true)
+        @denylist = Set.new(UNIVERSAL_DENYLIST + (config[:additional_denylist] || []))
+
+        # Use extracted components
+        @tracker = CardinalityTracker.new(limit: @cardinality_limit)
+        @relabeler = Relabeling.new
+      end
+
+      # Define relabeling rule for a label
+      #
+      # @param label_key [Symbol, String] Label key to relabel
+      # @yield [value] Block that transforms label value
+      # @return [void]
+      #
+      # @example HTTP status to class
+      #   protection.relabel(:http_status) { |v| "#{v.to_i / 100}xx" }
+      #
+      # @example Path normalization
+      #   protection.relabel(:path) { |v| v.gsub(/\/\d+/, '/:id') }
+      def relabel(label_key, &)
+        @relabeler.define(label_key, &)
+      end
+
+      # Filter labels to prevent cardinality explosions
+      #
+      # Applies 3-layer defense + optional relabeling:
+      # 1. Relabel high-cardinality values (if enabled)
+      # 2. Drop denylisted fields
+      # 3. Track and limit per-metric cardinality
+      # 4. Alert on limit exceeded
+      #
+      # @param labels [Hash] Raw labels from event
+      # @param metric_name [String] Metric name for tracking
+      # @return [Hash] Filtered safe labels
+      def filter(labels, metric_name)
+        return labels unless @enabled
+
+        safe_labels = {}
+
+        labels.each do |key, value|
+          # Step 1: Relabel if rule exists (reduces cardinality)
+          relabeled_value = @relabeling_enabled ? @relabeler.apply(key, value) : value
+
+          # Step 2: Denylist - drop high-cardinality fields
+          next if should_deny?(key)
+
+          # Step 3: Per-Metric Cardinality Limit
+          if @tracker.track(metric_name, key, relabeled_value)
+            safe_labels[key] = relabeled_value
+          else
+            # Step 4: Alert when limit exceeded
+            warn_cardinality_exceeded(metric_name, key)
+          end
+        end
+
+        safe_labels
+      end
+
+      # Check if cardinality limit is exceeded for a metric
+      # @param metric_name [String] Metric name
+      # @return [Boolean] True if ANY label exceeded limit
+      def cardinality_exceeded?(metric_name)
+        # Check if any label has exceeded limit
+        @tracker.cardinalities(metric_name).values.any? { |count| count >= @cardinality_limit }
+      end
+
+      # Get current cardinality for a metric (all labels)
+      # @param metric_name [String] Metric name
+      # @return [Hash{Symbol => Integer}] Label key => cardinality
+      def cardinality(metric_name)
+        @tracker.cardinalities(metric_name)
+      end
+
+      # Get all metrics with their cardinalities
+      # @return [Hash{String => Hash{Symbol => Integer}}] Metric => Label => cardinality
+      def cardinalities
+        @tracker.all_cardinalities
+      end
+
+      # Reset cardinality tracking (for testing)
+      # @return [void]
+      def reset!
+        @tracker.reset_all!
+        @relabeler.reset!
+      end
+
+      private
+
+      # Check if label should be denied (Layer 1: Denylist)
+      # @param key [Symbol] Label key
+      # @return [Boolean] True if should be denied
+      def should_deny?(key)
+        @denylist.include?(key)
+      end
+
+      # Warn about cardinality limit exceeded (Layer 3: Monitoring)
+      # @param metric_name [String] Metric name
+      # @param key [Symbol] Label key
+      def warn_cardinality_exceeded(metric_name, key)
+        warn "E11y Metrics: Cardinality limit exceeded for #{metric_name}:#{key} (limit: #{@cardinality_limit})"
+      end
+    end
+  end
+end

data/lib/e11y/metrics/cardinality_tracker.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module E11y
+  module Metrics
+    # Thread-safe cardinality tracker for metrics labels.
+    #
+    # Tracks unique label value combinations per metric to detect
+    # cardinality explosions. Separated from CardinalityProtection
+    # for single responsibility and easier testing.
+    #
+    # @example Track label values
+    #   tracker = CardinalityTracker.new(limit: 100)
+    #   tracker.track('orders.total', :status, 'paid')
+    #   tracker.track('orders.total', :status, 'failed')
+    #   tracker.cardinality('orders.total', :status) # => 2
+    #
+    # @see CardinalityProtection
+    class CardinalityTracker
+      # @return [Integer] Default cardinality limit per metric
+      DEFAULT_LIMIT = 1000
+
+      # Initialize tracker
+      #
+      # @param limit [Integer] Maximum unique values per metric+label
+      def initialize(limit: DEFAULT_LIMIT)
+        @limit = limit
+        @tracker = Hash.new { |h, k| h[k] = Hash.new { |h2, k2| h2[k2] = Set.new } }
+        @mutex = Mutex.new
+      end
+
+      # Track a label value for a metric
+      #
+      # Records unique label values per metric+label combination.
+      # Thread-safe operation.
+      #
+      # @param metric_name [String] Metric name
+      # @param label_key [Symbol, String] Label key
+      # @param label_value [Object] Label value to track
+      # @return [Boolean] true if within limit, false if limit exceeded
+      def track(metric_name, label_key, label_value)
+        @mutex.synchronize do
+          value_set = @tracker[metric_name][label_key]
+
+          # Allow if already tracked (existing value)
+          return true if value_set.include?(label_value)
+
+          # Check if adding new value would exceed limit
+          if value_set.size >= @limit
+            false
+          else
+            value_set.add(label_value)
+            true
+          end
+        end
+      end
+
+      # Check if metric+label has exceeded cardinality limit
+      #
+      # @param metric_name [String] Metric name
+      # @param label_key [Symbol, String] Label key
+      # @return [Boolean] true if at or above limit
+      def exceeded?(metric_name, label_key)
+        @mutex.synchronize do
+          @tracker.dig(metric_name, label_key)&.size.to_i >= @limit
+        end
+      end
+
+      # Get current cardinality for metric+label
+      #
+      # @param metric_name [String] Metric name
+      # @param label_key [Symbol, String] Label key
+      # @return [Integer] Number of unique values tracked
+      def cardinality(metric_name, label_key)
+        @mutex.synchronize do
+          @tracker.dig(metric_name, label_key)&.size || 0
+        end
+      end
+
+      # Get cardinalities for all labels of a metric
+      #
+      # @param metric_name [String] Metric name
+      # @return [Hash{Symbol => Integer}] Label key => cardinality
+      def cardinalities(metric_name)
+        @mutex.synchronize do
+          metric_data = @tracker[metric_name]
+          metric_data.transform_values(&:size)
+        end
+      end
+
+      # Get all tracked cardinalities across all metrics
+      #
+      # @return [Hash{String => Hash{Symbol => Integer}}] Nested hash of metric => label => cardinality
+      def all_cardinalities
+        @mutex.synchronize do
+          result = {}
+          @tracker.each do |metric_name, labels|
+            label_cardinalities = labels.transform_values(&:size)
+            # Only include metrics with non-zero cardinalities
+            result[metric_name] = label_cardinalities if label_cardinalities.values.any?(&:positive?)
+          end
+          result
+        end
+      end
+
+      # Reset tracking for specific metric
+      #
+      # @param metric_name [String] Metric name to reset
+      # @return [void]
+      def reset_metric!(metric_name)
+        @mutex.synchronize do
+          @tracker.delete(metric_name)
+        end
+      end
+
+      # Reset all tracking data
+      #
+      # @return [void]
+      def reset_all!
+        @mutex.synchronize do
+          @tracker.clear
+        end
+      end
+
+      # Get total number of tracked metrics
+      #
+      # @return [Integer] Number of unique metrics being tracked
+      def metrics_count
+        @mutex.synchronize do
+          @tracker.size
+        end
+      end
+    end
+  end
+end