e11y 0.2.0 → 1.1.0

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

data/lib/e11y/middleware/self_monitoring_emit.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "e11y/middleware/base"
+require "e11y/slo/config_loader"
+
+module E11y
+  module Middleware
+    # SelfMonitoringEmit middleware — emits e11y_events_tracked_total at pipeline end.
+    #
+    # When e11y_self_monitoring.enabled is true in slo.yml, increments the counter
+    # for each event that reaches the end of the pipeline (after EventSlo).
+    #
+    # **Middleware Zone:** `:post_processing` (last in pipeline)
+    #
+    # @example slo.yml
+    #   e11y_self_monitoring:
+    #     enabled: true
+    #     targets:
+    #       reliability: 0.999
+    #
+    # @see docs/plans/2026-03-13-slo-linters-self-monitoring-plan.md
+    class SelfMonitoringEmit < Base
+      middleware_zone :post_processing
+
+      # Process event and optionally emit self-monitoring metric.
+      #
+      # @param event_data [Hash, nil] Event payload (nil passes through)
+      # @return [Hash, nil] Unchanged event_data (passthrough)
+      def call(event_data)
+        if event_data && E11y::SLO::ConfigLoader.self_monitoring_enabled?
+          event_name = event_data[:event_name].to_s.presence || "unknown"
+          E11y::Metrics.increment(:e11y_events_tracked_total, result: "success", event_name: event_name)
+        end
+
+        @app&.call(event_data) || event_data
+      end
+    end
+  end
+end

data/lib/e11y/middleware/trace_context.rb

@@ -56,19 +56,19 @@ module E11y
       def call(event_data)
         enrich_trace_context(event_data)
         enrich_service_context(event_data)
-        increment_metric("e11y.middleware.trace_context.processed")
+        E11y::Metrics.increment("e11y.middleware.trace_context.processed")
         @app.call(event_data)
       end
 
       private
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize
       # Add distributed tracing fields to event data
       # @param event_data [Hash] Event data to enrich
       # @return [void]
       def enrich_trace_context(event_data)
         event_data[:trace_id] ||= current_trace_id || generate_trace_id
-        event_data[:span_id] ||= generate_span_id
+        event_data[:span_id] ||= current_span_id || generate_span_id
         event_data[:parent_trace_id] ||= current_parent_trace_id if current_parent_trace_id
 
         # Format timestamp if it's a Time object
@@ -93,7 +93,7 @@ module E11y
 
         event_data[:audit_event] = event_class.audit_event?
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize
 
       # Add service context fields to event data
       # @param event_data [Hash] Event data to enrich
@@ -103,15 +103,54 @@ module E11y
         event_data[:environment] ||= E11y.config.environment
       end
 
-      # Get current trace ID from E11y::Current or thread-local storage (request context).
+      # Get current trace ID from configured source (ADR-007 §8).
       #
-      # Priority: E11y::Current > Thread.current
+      # When config.tracing_source is :opentelemetry and OTel SDK has an active span,
+      # uses trace_id from OpenTelemetry::Trace.current_span.
+      # Otherwise: E11y::Current > Thread.current
       #
       # @return [String, nil] Current trace ID if set, nil otherwise
       def current_trace_id
+        if tracing_source_opentelemetry?
+          otel = otel_trace_context
+          return otel[:trace_id] if otel[:trace_id]
+        end
         E11y::Current.trace_id || Thread.current[:e11y_trace_id]
       end
 
+      # Get current span ID (for event correlation).
+      # When using OTel source and span exists, returns OTel span_id; otherwise nil (caller generates).
+      #
+      # @return [String, nil]
+      def current_span_id
+        return nil unless tracing_source_opentelemetry?
+
+        otel = otel_trace_context
+        otel[:span_id]
+      end
+
+      def tracing_source_opentelemetry?
+        E11y.config&.tracing_source == :opentelemetry
+      end
+
+      def otel_trace_context
+        return {} unless defined?(OpenTelemetry::Trace)
+
+        span = OpenTelemetry::Trace.current_span
+        ctx = span.context
+        return {} unless ctx.respond_to?(:valid?) && ctx.valid?
+
+        trace_id = ctx.respond_to?(:hex_trace_id) ? ctx.hex_trace_id : nil
+        span_id = ctx.respond_to?(:hex_span_id) ? ctx.hex_span_id : nil
+        return {} if trace_id.to_s.empty?
+
+        # Sync to E11y::Current so downstream uses same context
+        E11y::Current.trace_id = trace_id
+        E11y::Current.span_id = span_id
+
+        { trace_id: trace_id, span_id: span_id }
+      end
+
       # Get current parent trace ID from E11y::Current (background job context).
       #
       # Only set for background jobs that have a parent request trace.
@@ -151,10 +190,6 @@ module E11y
       #
       # @param metric_name [String] Metric name
       # @return [void]
-      def increment_metric(_metric_name)
-        # TODO: Integrate with Yabeda/Prometheus in Phase 2
-        # Yabeda.e11y.middleware_trace_context_processed.increment
-      end
     end
   end
 end