e11y 0.2.0 → 1.0.0

data/lib/e11y/middleware/rate_limiting.rb

@@ -30,7 +30,7 @@ module E11y
     #
     # @example Critical Event Bypass (C02)
     #   # Payment events bypass rate limiting → DLQ if limited
-    #   config.dlq_filter.always_save_patterns = [/^payment\./]
+    #   config.dlq_filter.should_save?(event_data) # Event DSL: use_dlq
     #
     #   # Result: Rate-limited payment events go to DLQ, not dropped
     #
@@ -40,22 +40,33 @@ module E11y
       # Initialize rate limiting middleware
       #
       # @param app [Object] Next middleware in pipeline
-      # @param global_limit [Integer] Max events/sec globally (default: 10_000)
-      # @param per_event_limit [Integer] Max events/sec per event type (default: 1_000)
-      # @param window [Float] Time window in seconds (default: 1.0)
-      def initialize(app, global_limit: 10_000, per_event_limit: 1_000, window: 1.0)
+      # @param global_limit [Integer] Max events/sec globally (default: from E11y.config)
+      # @param per_event_limit [Integer] Max events/sec per event type (default: from E11y.config)
+      # @param window [Float] Time window in seconds (default: from E11y.config)
+      def initialize(app, global_limit: nil, per_event_limit: nil, window: nil)
         super(app)
-        @global_limit = global_limit
-        @per_event_limit = per_event_limit
-        @window = window
+        config = E11y.config
+        # When explicit limits are passed (e.g. from pipeline options), enable for this instance
+        explicit_opts = global_limit || per_event_limit || window
+        @enabled = explicit_opts ? true : config.rate_limiting_enabled
+        @global_limit = global_limit || config.rate_limiting_global_limit
+        @global_window = window || config.rate_limiting_global_window
+        @window = @global_window # Alias for spec compatibility
+        @per_event_limit = per_event_limit || config.rate_limiting_per_event_limit
+        @explicit_per_event = per_event_limit && window
 
         # Token buckets for rate limiting
-        @global_bucket = TokenBucket.new(capacity: @global_limit, refill_rate: @global_limit, window: @window)
+        @global_bucket = TokenBucket.new(
+          capacity: @global_limit,
+          refill_rate: @global_limit,
+          window: @global_window
+        )
         @per_event_buckets = Hash.new do |hash, event_name|
+          limit_cfg = @explicit_per_event ? { limit: @per_event_limit, window: @window } : config.rate_limit_for(event_name)
           hash[event_name] = TokenBucket.new(
-            capacity: @per_event_limit,
-            refill_rate: @per_event_limit,
-            window: @window
+            capacity: limit_cfg[:limit],
+            refill_rate: limit_cfg[:limit],
+            window: limit_cfg[:window]
           )
         end
 
@@ -67,6 +78,8 @@ module E11y
       # @param event_data [Hash] Event payload
       # @return [Hash, nil] Event data if allowed, nil if rate limited
       def call(event_data)
+        return @app.call(event_data) unless @enabled
+
         event_name = event_data[:event_name]
 
         # Check global rate limit
@@ -83,7 +96,7 @@ module E11y
         end
 
         # Rate limit not exceeded - continue pipeline
-        event_data
+        @app.call(event_data)
       end
 
       private
@@ -97,16 +110,31 @@ module E11y
       def handle_rate_limited(event_data, limit_type)
         event_name = event_data[:event_name]
 
-        # Log rate limiting
-        warn "[E11y] Rate limit exceeded (#{limit_type}) for event: #{event_name}"
+        # Log rate limiting (via E11y.logger so it respects Rails.logger in test env)
+        E11y.logger&.warn("[E11y] Rate limit exceeded (#{limit_type}) for event: #{event_name}")
 
         # C02 Resolution: Check if event should be saved to DLQ
-        return unless should_save_to_dlq?(event_data)
-
-        save_to_dlq(event_data, limit_type)
+        if should_save_to_dlq?(event_data)
+          record_dropped_metric(event_data, "rate_limited_#{limit_type}_dlq")
+          save_to_dlq(event_data, limit_type)
+        else
+          record_dropped_metric(event_data, "rate_limited_#{limit_type}")
+        end
+      end
 
-        # Non-critical events are dropped (no DLQ)
-        # TODO: Track metric e11y.rate_limiter.dropped
+      # Record e11y_events_dropped_total metric (non-fatal, safe when Metrics unavailable)
+      #
+      # @param event_data [Hash] Event payload
+      # @param reason [String] Drop reason (e.g., sampled_out, rate_limited_global)
+      def record_dropped_metric(event_data, reason)
+        return unless defined?(E11y::Metrics) && E11y::Metrics.respond_to?(:increment)
+
+        E11y::Metrics.increment(:e11y_events_dropped_total, {
+                                  reason: reason,
+                                  event_type: event_data[:event_name].to_s
+                                })
+      rescue StandardError
+        # non-fatal
       end
 
       # Check if rate-limited event should be saved to DLQ (C02 Resolution)
@@ -120,9 +148,8 @@ module E11y
         dlq_filter = E11y.config.dlq_filter
         return false unless dlq_filter
 
-        # Check if event matches always_save_patterns
-        event_name = event_data[:event_name]
-        dlq_filter.always_save_patterns&.any? { |pattern| pattern.match?(event_name) }
+        # Use DLQ filter (Event DSL: use_dlq, severity, default)
+        dlq_filter.should_save?(event_data)
       end
 
       # Save rate-limited critical event to DLQ (C02 Resolution)
@@ -135,19 +162,19 @@ module E11y
         dlq_storage = E11y.config.dlq_storage
         return unless dlq_storage
 
+        per_event_limit = limit_type == :per_event ? E11y.config.rate_limit_for(event_data[:event_name])[:limit] : @per_event_limit
         dlq_storage.save(event_data, metadata: {
                            reason: "rate_limited_#{limit_type}",
                            limit_type: limit_type,
                            global_limit: @global_limit,
-                           per_event_limit: @per_event_limit,
+                           per_event_limit: per_event_limit,
                            timestamp: Time.now.utc.iso8601
                          })
 
-        warn "[E11y] Rate-limited critical event saved to DLQ: #{event_data[:event_name]}"
-        # TODO: Track metric e11y.rate_limiter.dlq_saved
+        E11y.logger&.warn("[E11y] Rate-limited critical event saved to DLQ: #{event_data[:event_name]}")
       rescue StandardError => e
         # Don't fail if DLQ save fails (C18 Resolution)
-        warn "[E11y] Failed to save rate-limited event to DLQ: #{e.message}"
+        E11y.logger&.warn("[E11y] Failed to save rate-limited event to DLQ: #{e.message}")
       end
 
       # Token Bucket implementation for rate limiting

data/lib/e11y/middleware/request.rb

@@ -2,6 +2,8 @@
 
 require "rack/request"
 require "securerandom"
+require "e11y/tracing/propagator"
+require "e11y/trace_context/sampler"
 
 module E11y
   module Middleware
@@ -32,13 +34,14 @@ module E11y
       # Process request
       # @param env [Hash] Rack environment
       # @return [Array] Rack response [status, headers, body]
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       # Rack middleware request processing requires sequential setup of tracing, context, buffer, and SLO tracking
       def call(env)
         request = Rack::Request.new(env)
 
-        # Extract or generate trace_id
-        trace_id = extract_trace_id(request) || generate_trace_id
+        # Extract or generate trace context (trace_id, sampled from traceparent)
+        trace_ctx = extract_trace_context(request)
+        trace_id = trace_ctx[:trace_id] || generate_trace_id
         span_id = generate_span_id
 
         # Set request context (ActiveSupport::CurrentAttributes)
@@ -50,9 +53,10 @@ module E11y
         E11y::Current.user_agent = request.user_agent
         E11y::Current.request_method = request.request_method
         E11y::Current.request_path = request.path
+        E11y::Current.sampled = resolve_sampled(trace_ctx)
 
         # Start request-scoped buffer (for debug events)
-        E11y::Buffers::RequestScopedBuffer.initialize! if E11y.config.request_buffer&.enabled
+        E11y::Buffers::EphemeralBuffer.initialize! if E11y.config.ephemeral_buffer_enabled
 
         # Track request start time for SLO
         start_time = Time.now
@@ -60,6 +64,9 @@ module E11y
         # Call next middleware/app
         status, headers, body = @app.call(env)
 
+        # Flush buffer if status matches configured flush_on_statuses (default: 5xx only)
+        E11y::Buffers::EphemeralBuffer.flush_on_error if should_flush_buffer?(status)
+
         # Track SLO metrics (if enabled)
         track_http_request_slo(env, status, start_time)
 
@@ -70,38 +77,80 @@ module E11y
         [status, headers, body]
       rescue StandardError
         # Flush request buffer on error (includes debug events)
-        E11y::Buffers::RequestScopedBuffer.flush_on_error if E11y.config.request_buffer&.enabled
+        E11y::Buffers::EphemeralBuffer.flush_on_error if E11y.config.ephemeral_buffer_enabled
 
         raise # Re-raise original exception
       ensure
         # Discard request buffer on success (not on error, already flushed above)
         # We need to check if we're here from normal completion or exception
         # If there was an exception, buffer was already flushed in rescue block
-        if !$ERROR_INFO && E11y.config.request_buffer&.enabled # No exception occurred
-          E11y::Buffers::RequestScopedBuffer.discard
-        end
+        E11y::Buffers::EphemeralBuffer.discard if !$ERROR_INFO && E11y.config.ephemeral_buffer_enabled # No exception occurred
 
         # Reset context
         E11y::Current.reset
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       private
 
-      # Extract trace_id from request headers (W3C Trace Context or custom headers)
+      # Determine whether the request-scoped buffer should be flushed for this status code.
+      #
+      # Two independent conditions (either is sufficient):
+      # - +flush_on_error+ (default: true) — flushes on any 5xx server error
+      # - +flush_on_statuses+ (default: []) — extra status codes/ranges, e.g. [403]
+      #
+      # @example Default behaviour — flush on 5xx only
+      #   config.ephemeral_buffer_flush_on_error   = true  # default
+      #   config.ephemeral_buffer_flush_on_statuses = []   # default
+      #
+      # @example Flush on 403 in addition to 5xx
+      #   config.ephemeral_buffer_flush_on_statuses = [403]
+      #
+      # @example Flush only on explicit statuses (disable 5xx default)
+      #   config.ephemeral_buffer_flush_on_error    = false
+      #   config.ephemeral_buffer_flush_on_statuses = [403, 422]
+      #
+      # @param status [Integer] HTTP response status code
+      # @return [Boolean]
+      def should_flush_buffer?(status)
+        return false unless E11y.config.ephemeral_buffer_enabled
+
+        # Condition 1: server error flush (5xx)
+        return true if E11y.config.ephemeral_buffer_flush_on_error && status >= 500
+
+        # Condition 2: explicit extra statuses
+        extra = E11y.config.ephemeral_buffer_flush_on_statuses
+        extra&.any? { |s| s === status } || false # rubocop:disable Style/CaseEquality
+      end
+
+      # Extract trace context from request headers (W3C Trace Context or custom).
+      # Also extracts tracestate into E11y::Current.baggage (F-014).
       # @param request [Rack::Request] Rack request
-      # @return [String, nil] Trace ID or nil if not found
-      def extract_trace_id(request)
-        # W3C Trace Context (traceparent header)
-        # Format: version-trace_id-span_id-flags
-        # Example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
+      # @return [Hash] { trace_id:, sampled: (from traceparent, or nil if new trace) }
+      def extract_trace_context(request)
         traceparent = request.get_header("HTTP_TRACEPARENT")
-        return traceparent.split("-")[1] if traceparent
+        tracestate = request.get_header("HTTP_TRACESTATE")
+
+        if tracestate && E11y::Current.respond_to?(:baggage=)
+          baggage = E11y::Tracing::Propagator.parse_tracestate(tracestate)
+          E11y::Current.baggage = baggage if baggage.any?
+        end
+
+        if traceparent
+          parsed = E11y::Tracing::Propagator.parse(traceparent)
+          return { trace_id: parsed[:trace_id], sampled: parsed[:sampled] } if parsed
+        end
+
+        trace_id = request.get_header("HTTP_X_REQUEST_ID") || request.get_header("HTTP_X_TRACE_ID")
+        { trace_id: trace_id, sampled: nil }
+      end
+
+      # Resolve sampling decision: from parent (traceparent) or Sampler for new trace.
+      # Context for Sampler = E11y::Current.to_context (already set above).
+      def resolve_sampled(trace_ctx)
+        return trace_ctx[:sampled] if trace_ctx.key?(:sampled) && !trace_ctx[:sampled].nil?
 
-        # X-Request-ID (Rails default)
-        request.get_header("HTTP_X_REQUEST_ID") ||
-          # X-Trace-Id (custom)
-          request.get_header("HTTP_X_TRACE_ID")
+        E11y::TraceContext::Sampler.should_sample?(E11y::Current.to_context)
       end
 
       # Extract request_id from Rack env
@@ -141,10 +190,9 @@ module E11y
       # @param start_time [Time] Request start time
       # @return [void]
       # @api private
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
       # SLO tracking requires extracting controller/action, calculating duration, and error handling
       def track_http_request_slo(env, status, start_time)
-        return unless E11y.config.slo_tracking&.enabled
+        return unless E11y.config.respond_to?(:slo_tracking_enabled) && E11y.config.slo_tracking_enabled
 
         duration_ms = ((Time.now - start_time) * 1000).round(2)
 
@@ -163,7 +211,6 @@ module E11y
         # Don't fail if SLO tracking fails
         warn "[E11y] SLO tracking error: #{e.message}"
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
     end
   end
 end

data/lib/e11y/middleware/routing.rb

@@ -40,13 +40,8 @@ module E11y
     #   # Rule: ->(e) { :audit_encrypted if e[:audit_event] }
     #   # Routes to: [:audit_encrypted]
     #
-    # @example Retention-based routing
-    #   event_data = {
-    #     event_name: 'order.placed',
-    #     retention_until: '2026-04-21T...'  # 90 days
-    #   }
-    #   # Rule: ->(e) { days > 30 ? :s3_standard : :loki }
-    #   # Routes to: [:s3_standard]
+    # Note: retention_until is for archival jobs (run separately), not for routing.
+    # Archival happens later — cron/Loki compaction filters by retention_until.
     class Routing < Base
       middleware_zone :adapters
 
@@ -58,10 +53,23 @@ module E11y
       # @option event_data [Boolean] :audit_event Audit event flag (optional, for routing rules)
       # @option event_data [Symbol] :severity Event severity (optional, for routing rules)
       # @return [Hash, nil] Event data (passed to next middleware), or nil if dropped
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
       # Routing logic requires adapter selection, iteration with error handling,
       # metadata enrichment, and metrics tracking
       def call(event_data)
+        # Handle nil from upstream middleware (e.g., rate limiting, sampling)
+        return nil unless event_data
+
+        # 0. Request-scoped buffer: buffer debug events instead of writing when enabled
+        # Skip when event is from a flush (avoid re-buffering)
+        if !event_data[:from_ephemeral_buffer_flush] &&
+           event_data[:severity] == :debug &&
+           E11y.config.ephemeral_buffer_enabled &&
+           E11y::Buffers::EphemeralBuffer.active? && E11y::Buffers::EphemeralBuffer.add_event(event_data)
+          # Buffered — skip adapter writes, pass through
+          return @app&.call(event_data)
+        end
+
         # 1. Determine target adapters (explicit or via routing rules)
         target_adapters = if event_data[:adapters]&.any?
                             # Explicit adapters bypass routing rules
@@ -71,18 +79,28 @@ module E11y
                             apply_routing_rules(event_data)
                           end
 
+        # 1.5. Validate audit events have proper routing (UC-012 compliance requirement)
+        validate_audit_routing!(event_data, target_adapters)
+
         # 2. Write to selected adapters
         target_adapters.each do |adapter_name|
           adapter = E11y.configuration.adapters[adapter_name]
           next unless adapter
 
+          # Per-adapter payload: merge payload_rewrites only when present (explicit_pii exclude_adapters)
+          data_to_write = if event_data[:payload_rewrites] && event_data[:payload_rewrites][adapter_name]
+                            payload = event_data[:payload]&.dup || {}
+                            payload.merge!(event_data[:payload_rewrites][adapter_name])
+                            event_data.merge(payload: payload)
+                          else
+                            event_data
+                          end
+
           begin
-            adapter.write(event_data)
-            increment_metric("e11y.middleware.routing.write_success", adapter: adapter_name)
+            adapter.write(data_to_write)
           rescue StandardError => e
             # Log routing error but don't fail pipeline
             warn "E11y routing error for adapter #{adapter_name}: #{e.message}"
-            increment_metric("e11y.middleware.routing.write_error", adapter: adapter_name)
           end
         end
 
@@ -94,9 +112,9 @@ module E11y
         }
 
         # 4. Increment metrics
-        increment_metric("e11y.middleware.routing.routed",
-                         adapters_count: target_adapters.size,
-                         routing_type: event_data[:routing][:routing_type])
+        E11y::Metrics.increment("e11y.middleware.routing.routed",
+                                adapters_count: target_adapters.size,
+                                routing_type: event_data[:routing][:routing_type])
 
         # 5. Log routing decision (for debugging)
         log_routing_decision(event_data, target_adapters) if debug_enabled?
@@ -104,7 +122,7 @@ module E11y
         # 6. Pass to next app (if any)
         @app&.call(event_data)
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
 
       private
 
@@ -124,12 +142,12 @@ module E11y
       #     ->(event) { :audit_encrypted if event[:audit_event] },
       #     ->(event) {
       #       days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      #       days > 90 ? :s3_glacier : :loki
+      #       days > 90 ? :archive : :loki
       #     }
       #   ]
       #
       #   apply_routing_rules(event_data)
-      #   # => [:audit_encrypted] or [:loki] or [:s3_glacier]
+      #   # => [:audit_encrypted] or [:loki] or [:archive]
       def apply_routing_rules(event_data)
         matched_adapters = []
 
@@ -143,10 +161,12 @@ module E11y
           warn "E11y routing rule error: #{e.message}"
         end
 
-        # Return unique adapters or fallback
+        # Track whether fallback was used (for audit validation)
         if matched_adapters.any?
+          event_data[:routing_used_fallback] = false
           matched_adapters.uniq
         else
+          event_data[:routing_used_fallback] = true
           E11y.configuration.fallback_adapters || [:stdout]
         end
       end
@@ -175,9 +195,46 @@ module E11y
       # @param metric_name [String] Metric name
       # @param tags [Hash] Metric tags
       # @return [void]
-      def increment_metric(_metric_name, **_tags)
-        # TODO: Integrate with Yabeda/Prometheus
-        # Yabeda.e11y.middleware_routing_routed.increment(tags)
+      # Validate audit events have proper routing configuration.
+      #
+      # Audit events MUST be routed via explicit adapters OR routing rules.
+      # Relying on fallback routing (no rule matched) is a compliance configuration error.
+      #
+      # @param event_data [Hash] Event data
+      # @param target_adapters [Array<Symbol>] Target adapters
+      # @raise [E11y::Error] if audit event misconfigured
+      # @return [void]
+      def validate_audit_routing!(event_data, target_adapters)
+        return unless event_data[:audit_event]
+
+        # Audit events are valid if:
+        # 1. They have explicit adapters (non-empty), OR
+        # 2. They matched a routing rule (routing_used_fallback = false)
+
+        has_explicit_adapters = event_data[:adapters]&.any?
+        return if has_explicit_adapters # Explicit adapters → valid
+
+        # Check if fallback was used (set by apply_routing_rules)
+        used_fallback = event_data[:routing_used_fallback]
+        return unless used_fallback
+
+        # CRITICAL: Audit event using fallback routing (no rule matched!)
+        error_message = <<~ERROR
+          [E11y] CRITICAL: Audit event has no routing configuration!
+
+          Event: #{event_data[:event_name]}
+          Routed to: #{target_adapters.inspect} (fallback adapters)
+
+          Audit events MUST be explicitly routed to compliance-grade storage.
+
+          Fix options:
+          1. Add explicit adapters: `adapters :audit_encrypted`
+          2. Configure routing rule: `config.routing_rules = [->(e) { :audit_encrypted if e[:audit_event] }]`
+
+          See UC-012 Audit Trail documentation for details.
+        ERROR
+
+        raise E11y::Error, error_message
       end
     end
   end

data/lib/e11y/middleware/sampling.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "e11y/middleware/base"
+require "e11y/sampling/stratified_tracker"
 
 module E11y
   module Middleware
@@ -51,6 +52,8 @@ module E11y
     #         }
     #       }
     #   end
+    # rubocop:disable Metrics/ClassLength
+    # Class has 6 adaptive sampling strategies each requiring dedicated setup + private methods
     class Sampling < Base
       middleware_zone :routing
 
@@ -79,6 +82,9 @@ module E11y
       # @param event_data [Hash] The event payload
       # @return [Hash, nil] The event payload if sampled, nil if dropped
       def call(event_data)
+        # Handle nil from upstream middleware (e.g., rate limiting)
+        return nil unless event_data
+
         event_class = event_data[:event_class]
 
         # Track errors for error-based adaptive sampling (FEAT-4838)
@@ -87,13 +93,34 @@ module E11y
         # Track events for load-based adaptive sampling (FEAT-4842)
         @load_monitor&.record_event
 
+        # C11: Get sample rate and severity before decision (for StratifiedTracker)
+        sample_rate = determine_sample_rate(event_class, event_data)
+        severity = event_data[:severity] || (event_class.respond_to?(:severity) ? event_class.severity : :info)
+
         # Determine if event should be sampled
         # Drop event if not sampled
-        return nil unless should_sample?(event_data, event_class)
+        unless should_sample?(event_data, event_class)
+          # C11: Record dropped event to StratifiedTracker for sampling correction
+          E11y::Sampling.stratified_tracker.record_sample(severity: severity, sample_rate: sample_rate, sampled: false)
+          begin
+            if defined?(E11y::Metrics) && E11y::Metrics.respond_to?(:increment)
+              E11y::Metrics.increment(:e11y_events_dropped_total, {
+                                        reason: "sampled_out",
+                                        event_type: event_data[:event_name].to_s
+                                      })
+            end
+          rescue StandardError
+            # non-fatal
+          end
+          return nil
+        end
 
         # Mark as sampled for downstream middleware
         event_data[:sampled] = true
-        event_data[:sample_rate] = determine_sample_rate(event_class, event_data)
+        event_data[:sample_rate] = sample_rate
+
+        # C11: Record sampled event to StratifiedTracker for sampling correction
+        E11y::Sampling.stratified_tracker.record_sample(severity: severity, sample_rate: sample_rate, sampled: true)
 
         # Pass to next middleware
         @app.call(event_data)
@@ -121,6 +148,7 @@ module E11y
         @default_sample_rate = config.fetch(:default_sample_rate, 1.0)
         @trace_aware = config.fetch(:trace_aware, true)
         @severity_rates = config.fetch(:severity_rates, {})
+        @pattern_rates = config.fetch(:pattern_rates, []) # [[Regexp, Float], ...]
         @trace_decisions = {} # Cache for trace-level sampling decisions
         @trace_decisions_mutex = Mutex.new
       end
@@ -158,8 +186,10 @@ module E11y
         # 1. Check if audit event (never sample audit events!)
         return true if event_class.respond_to?(:audit_event?) && event_class.audit_event?
 
-        # 2. Check trace-aware sampling (C05)
+        # 2. Trace-consistent sampling (ADR-005 §7): prefer E11y::Current.sampled when trace_aware
         if @trace_aware && event_data[:trace_id]
+          return E11y::Current.sampled if E11y::Current.respond_to?(:sampled) && !E11y::Current.sampled.nil?
+
           return trace_sampling_decision(event_data[:trace_id], event_class, event_data)
         end
 
@@ -183,22 +213,32 @@ module E11y
       # @param event_class [Class] The event class
       # @param event_data [Hash] Event payload (for value-based sampling)
       # @return [Float] Sample rate (0.0-1.0)
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-      # Sample rate determination follows priority chain: error spike → value-based →
-      # load-based → severity → event-level → default
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # Sample rate determination follows a 6-step priority chain:
+      # error spike (0) → pattern-based (0.5) → value-based (1) →
+      # load-based (2) → severity (3) → event-level (4) → default (5)
       def determine_sample_rate(event_class, event_data = nil)
         # 0. Error-based adaptive sampling (FEAT-4838) - highest priority!
         if @error_based_adaptive && @error_spike_detector&.error_spike?
           return 1.0 # 100% sampling during error spike
         end
 
+        # 0.5. Pattern-based sampling (by event_name) - overrides event-level config
+        if event_data && !@pattern_rates.empty?
+          event_name = event_data[:event_name].to_s
+          @pattern_rates.each do |pattern, rate|
+            return rate if pattern.match?(event_name)
+          end
+        end
+
         # 1. Value-based sampling (FEAT-4849) - high-value events always sampled
         if event_data && event_class.respond_to?(:value_sampling_configs)
           configs = event_class.value_sampling_configs
           unless configs.empty?
             require "e11y/sampling/value_extractor"
             extractor = E11y::Sampling::ValueExtractor.new
-            if configs.any? { |config| config.matches?(event_data, extractor) }
+            payload = event_data[:payload] || event_data
+            if configs.any? { |config| config.matches?(payload, extractor) }
               return 1.0 # 100% sampling for high-value events
             end
           end
@@ -228,7 +268,7 @@ module E11y
         # 4. Default/load-based rate
         base_rate
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # Trace-aware sampling decision (C05 Resolution)
       #
@@ -241,15 +281,21 @@ module E11y
       # @return [Boolean] true if trace should be sampled
       def trace_sampling_decision(trace_id, event_class, event_data = nil)
         @trace_decisions_mutex.synchronize do
+          # Use monotonic clock (Float) to avoid Time object allocation — prevents memory leak in hot path
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
           # Check if decision already made for this trace
-          return @trace_decisions[trace_id] if @trace_decisions.key?(trace_id)
+          if (entry = @trace_decisions[trace_id])
+            entry[:last_access] = now # LRU touch
+            return entry[:decision]
+          end
 
           # Make new sampling decision
           sample_rate = determine_sample_rate(event_class, event_data)
           decision = rand < sample_rate
 
-          # Cache decision (TTL handled by periodic cleanup)
-          @trace_decisions[trace_id] = decision
+          # Cache decision with LRU metadata (evict oldest on cleanup)
+          @trace_decisions[trace_id] = { decision: decision, last_access: now }
 
           # Cleanup old decisions periodically (every 1000 traces)
           cleanup_trace_decisions if @trace_decisions.size > 1000
@@ -260,14 +306,17 @@ module E11y
 
       # Cleanup old trace decisions to prevent memory leaks
       #
-      # Removes random 50% of cached decisions when cache grows too large.
-      # This is a simple heuristic - traces typically complete in <10 seconds,
-      # so old decisions are likely stale.
+      # Evicts oldest 50% by last_access (LRU). Active traces stay in cache
+      # because they are touched on each lookup, preserving trace-level consistency.
       def cleanup_trace_decisions
-        # Remove random 50% of decisions
-        keys_to_remove = @trace_decisions.keys.sample(@trace_decisions.size / 2)
-        keys_to_remove.each { |key| @trace_decisions.delete(key) }
+        return if @trace_decisions.size <= 100
+
+        size_to_remove = @trace_decisions.size / 2
+        sorted = @trace_decisions.to_a.sort_by { |_, v| v[:last_access] }
+        keys_to_remove = sorted.first(size_to_remove).map(&:first)
+        keys_to_remove.each { |k| @trace_decisions.delete(k) }
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end