e11y 0.2.0 → 1.0.0

data/lib/e11y/buffers/{request_scoped_buffer.rb → ephemeral_buffer.rb}

@@ -2,7 +2,7 @@
 
 module E11y
   module Buffers
-    # Request-scoped buffer using thread-local storage for debug event buffering.
+    # Ephemeral buffer (request/job-scoped) using thread-local storage for debug event buffering.
     #
     # This buffer stores debug events in thread-local storage during request processing.
     # Events are flushed only when an error occurs, keeping logs clean during successful requests.
@@ -12,21 +12,21 @@ module E11y
     #
     # @example Basic usage
     #   # In Rails middleware
-    #   RequestScopedBuffer.initialize!
+    #   EphemeralBuffer.initialize!
     #
     #   # Track debug events (buffered)
-    #   RequestScopedBuffer.add_event({ event_name: "debug", severity: :debug })
+    #   EphemeralBuffer.add_event({ event_name: "debug", severity: :debug })
     #
     #   # On error - flush all buffered events
-    #   RequestScopedBuffer.flush_on_error
+    #   EphemeralBuffer.flush_on_error
     #
     #   # On success - discard buffered events
-    #   RequestScopedBuffer.discard
+    #   EphemeralBuffer.discard
     #
     # @see UC-001 Request-Scoped Debug Buffering
-    class RequestScopedBuffer
+    class EphemeralBuffer
       # Thread-local storage keys
-      THREAD_KEY_BUFFER = :e11y_request_buffer
+      THREAD_KEY_BUFFER = :e11y_ephemeral_buffer
       THREAD_KEY_REQUEST_ID = :e11y_request_id
       THREAD_KEY_ERROR_OCCURRED = :e11y_error_occurred
       THREAD_KEY_BUFFER_LIMIT = :e11y_buffer_limit
@@ -42,7 +42,7 @@ module E11y
         # @return [void]
         #
         # @example
-        #   RequestScopedBuffer.initialize!(request_id: "req-123", buffer_limit: 200)
+        #   EphemeralBuffer.initialize!(request_id: "req-123", buffer_limit: 200)
         def initialize!(request_id: nil, buffer_limit: DEFAULT_BUFFER_LIMIT)
           Thread.current[THREAD_KEY_BUFFER] = []
           Thread.current[THREAD_KEY_REQUEST_ID] = request_id || generate_request_id
@@ -60,42 +60,19 @@ module E11y
         #
         # @example
         #   # Debug event - buffered
-        #   RequestScopedBuffer.add_event({ event_name: "test", severity: :debug })
+        #   EphemeralBuffer.add_event({ event_name: "test", severity: :debug })
         #   # => true
         #
         #   # Error event - not buffered, triggers flush
-        #   RequestScopedBuffer.add_event({ event_name: "error", severity: :error })
+        #   EphemeralBuffer.add_event({ event_name: "error", severity: :error })
         #   # => false (and flushes buffer)
-        # rubocop:disable Metrics/MethodLength, Naming/PredicateMethod
         def add_event(event_data)
-          return false unless active? # Not in request scope
+          return false unless active?
+          return handle_error_event(event_data) if error_severity?(event_data[:severity])
+          return false unless event_data[:severity] == :debug
 
-          severity = event_data[:severity]
-
-          # Trigger flush on error severity
-          if error_severity?(severity)
-            Thread.current[THREAD_KEY_ERROR_OCCURRED] = true
-            flush_on_error
-            return false # Error events not buffered
-          end
-
-          # Only buffer debug events
-          return false unless severity == :debug
-
-          current_buffer = buffer
-          return false if current_buffer.nil?
-
-          # Check buffer limit
-          if current_buffer.size >= buffer_limit
-            increment_metric("e11y.request_buffer.overflow")
-            return false # Buffer full, drop event
-          end
-
-          current_buffer << event_data
-          increment_metric("e11y.request_buffer.events_buffered")
-          true
+          append_to_buffer(event_data)
         end
-        # rubocop:enable Metrics/MethodLength, Naming/PredicateMethod
 
         # Flush buffered events on error
         #
@@ -108,7 +85,7 @@ module E11y
         # @example
         #   # In rescue block
         #   rescue StandardError => e
-        #     RequestScopedBuffer.flush_on_error
+        #     EphemeralBuffer.flush_on_error
         #     raise
         #   end
         def flush_on_error(target: nil)
@@ -117,15 +94,18 @@ module E11y
 
           flushed_count = current_buffer.size
 
+          # Resolve flush targets once per flush (avoids N config lookups when flushing N events)
+          flush_targets = resolve_flush_targets
+
           # Flush events to main buffer/adapters
           current_buffer.each do |event_data|
             # TODO: Send to E11y::Collector.collect(event_data) when available
             # For now, placeholder
-            flush_event(event_data, target: target)
+            flush_event(event_data, target: target, flush_targets: flush_targets)
           end
 
           current_buffer.clear
-          increment_metric("e11y.request_buffer.flushed_on_error", tags: { events: flushed_count })
+          E11y::Metrics.increment(:e11y_ephemeral_buffer_total, event: "flushed_on_error", value: flushed_count)
           flushed_count
         end
 
@@ -135,8 +115,8 @@ module E11y
         #
         # @example
         #   # In middleware ensure block (success path)
-        #   unless RequestScopedBuffer.error_occurred?
-        #     RequestScopedBuffer.discard
+        #   unless EphemeralBuffer.error_occurred?
+        #     EphemeralBuffer.discard
         #   end
         def discard
           current_buffer = buffer
@@ -144,7 +124,7 @@ module E11y
 
           discarded_count = current_buffer.size
           current_buffer.clear
-          increment_metric("e11y.request_buffer.discarded", tags: { events: discarded_count })
+          E11y::Metrics.increment(:e11y_ephemeral_buffer_total, event: "discarded", value: discarded_count)
           discarded_count
         end
 
@@ -195,6 +175,28 @@ module E11y
 
         private
 
+        def handle_error_event(_event_data) # rubocop:disable Naming/PredicateMethod
+          Thread.current[THREAD_KEY_ERROR_OCCURRED] = true
+          flush_on_error
+          false
+        end
+
+        def append_to_buffer(event_data)
+          current_buffer = buffer
+          return false if current_buffer.nil?
+          return record_buffer_overflow if current_buffer.size >= buffer_limit
+
+          event_to_store = event_data.merge(request_id: request_id)
+          current_buffer << event_to_store
+          E11y::Metrics.increment(:e11y_ephemeral_buffer_total, event: "events_buffered")
+          true
+        end
+
+        def record_buffer_overflow # rubocop:disable Naming/PredicateMethod
+          E11y::Metrics.increment(:e11y_ephemeral_buffer_total, event: "overflow")
+          false
+        end
+
         # Get buffer limit (with fallback)
         #
         # @return [Integer] Buffer limit
@@ -218,27 +220,39 @@ module E11y
           SecureRandom.uuid
         end
 
-        # Flush single event to adapters
+        # Resolve flush targets: adapter instances (when debug_adapters set) or nil (use pipeline).
+        # Cached per flush to avoid repeated config lookups when flushing N events.
         #
-        # @param event_data [Hash] Event to flush
-        # @param target [Symbol, nil] Optional target adapter (not yet implemented)
-        # @return [void]
-        def flush_event(_event_data, target: nil) # rubocop:disable Lint/UnusedMethodArgument
-          # Placeholder for E11y::Collector integration
-          # Will be implemented when Collector/Adapter classes are available
+        # @return [Array<Object>, nil] Adapter instances to write to, or nil to use pipeline
+        def resolve_flush_targets
+          da = E11y.config.ephemeral_buffer_debug_adapters
+          return nil unless da&.any?
 
-          # For now, just increment metric
-          increment_metric("e11y.request_buffer.event_flushed")
+          da.filter_map { |name| E11y.configuration.adapters[name] }
         end
 
-        # Increment metric (placeholder)
+        # Flush single event to adapters via pipeline or debug_adapters
         #
-        # @param metric_name [String] Metric name
-        # @param tags [Hash] Optional tags
+        # When config.ephemeral_buffer_debug_adapters is set, sends directly to those
+        # adapters. Otherwise uses the full pipeline (fallback_adapters).
+        #
+        # @param event_data [Hash] Event to flush
+        # @param target [Symbol, nil] Optional target adapter (not yet implemented)
+        # @param flush_targets [Array<Object>, nil] Pre-resolved adapter instances (from flush_on_error)
         # @return [void]
-        def increment_metric(metric_name, tags: {})
-          # Placeholder for Yabeda integration
-          # Will be implemented in Phase 1 L2.4 (Metrics)
+        def flush_event(event_data, target: nil, flush_targets: nil) # rubocop:disable Lint/UnusedMethodArgument
+          return unless event_data
+
+          event_to_send = event_data.merge(from_ephemeral_buffer_flush: true)
+          targets = flush_targets || resolve_flush_targets
+
+          if targets
+            targets.each { |adapter| adapter&.write(event_to_send) }
+          else
+            E11y.config.built_pipeline.call(event_to_send)
+          end
+
+          E11y::Metrics.increment(:e11y_ephemeral_buffer_total, event: "event_flushed")
         end
       end
     end

data/lib/e11y/buffers/ring_buffer.rb

@@ -165,7 +165,7 @@ module E11y
       # @return [Array<Hash>] All buffered events
       #
       # @example
-      #   all_events = buffer.flush_all
+      #   events = buffer.flush_all
       #   # => [event1, event2, ...]
       def flush_all
         pop(@size.value)
@@ -208,7 +208,6 @@ module E11y
       #
       # @param event [Hash] Event that caused overflow
       # @return [Boolean] true if event was eventually added, false if dropped
-      # rubocop:disable Metrics/MethodLength
       def handle_overflow(event)
         case @overflow_strategy
         when :drop_oldest
@@ -217,21 +216,20 @@ module E11y
           push(event) # Retry push (recursive, but will succeed)
         when :drop_newest
           # Drop new event, keep buffer unchanged
-          increment_metric("e11y.buffer.overflow.drop_newest")
+          E11y::Metrics.increment(:e11y_buffer_overflow_total, event: "drop_newest")
           false
         when :block
           # Wait for space, with timeout
           wait_for_space
           if full?
             # Timeout reached, drop event
-            increment_metric("e11y.buffer.overflow.block_timeout")
+            E11y::Metrics.increment(:e11y_buffer_overflow_total, event: "block_timeout")
             false
           else
             push(event) # Retry after space freed
           end
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Wait for buffer space (with timeout)
       #
@@ -251,17 +249,6 @@ module E11y
           sleep 0.001 # 1ms
         end
       end
-
-      # Increment metric (placeholder for Phase 3: Metrics)
-      #
-      # TODO Phase 3: Replace with actual Yabeda metrics
-      #
-      # @param metric_name [String] Metric to increment
-      # @return [void]
-      def increment_metric(metric_name)
-        # Placeholder - will be implemented in Phase 3
-        # Yabeda.e11y.buffer_overflow.increment(strategy: @overflow_strategy)
-      end
     end
   end
 end

data/lib/e11y/configuration.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module E11y
+  # Configuration class for E11y.
+  #
+  # Adapters are referenced by name (e.g., :logs, :errors_tracker).
+  # The actual implementation (Loki, Sentry, etc.) is configured separately.
+  #
+  # @example Configure adapters
+  #   E11y.configure do |config|
+  #     config.adapters[:logs] = E11y::Adapters::Loki.new(url: "...")
+  #     config.adapters[:errors_tracker] = E11y::Adapters::Sentry.new(dsn: "...")
+  #   end
+  #
+  # @example Configure severity => adapter mapping
+  #   E11y.configure do |config|
+  #     config.adapter_mapping[:error] = [:logs, :errors_tracker]
+  #     config.adapter_mapping[:info] = [:logs]
+  #   end
+  #
+  # @example Configure middleware pipeline
+  #   E11y.configure do |config|
+  #     config.pipeline.use E11y::Middleware::Sampling, default_sample_rate: 0.1
+  #   end
+  class Configuration
+    attr_accessor :adapters, :log_level, :logger, :enabled, :environment, :service_name, :default_retention_period,
+                  :routing_rules, :fallback_adapters, :enable_http_tracing,
+                  :rails_instrumentation_enabled, :rails_instrumentation_custom_mappings, :rails_instrumentation_ignore_events,
+                  :logger_bridge_enabled, :logger_bridge_track_severities, :logger_bridge_ignore_patterns,
+                  :sidekiq_enabled, :active_job_enabled,
+                  :ephemeral_buffer_enabled, :ephemeral_buffer_flush_on_error, :ephemeral_buffer_flush_on_statuses,
+                  :ephemeral_buffer_debug_adapters, :ephemeral_buffer_job_buffer_limit,
+                  :error_handling_fail_on_error,
+                  :rate_limiting_enabled, :rate_limiting_global_limit, :rate_limiting_global_window,
+                  :rate_limiting_per_event_limit, :rate_limiting_per_event_limits,
+                  :slo_tracking_enabled, :slo_tracking_http_ignore_statuses, :slo_tracking_latency_percentiles,
+                  :slo_tracking_controller_configs, :slo_tracking_job_configs,
+                  :security_baggage_protection_enabled, :security_baggage_protection_allowed_keys, :security_baggage_protection_block_mode,
+                  :tracing_source, :tracing_default_sample_rate, :tracing_respect_parent_sampling,
+                  :tracing_per_event_sample_rates, :tracing_always_sample_if,
+                  :opentelemetry_span_creation_patterns,
+                  :cardinality_protection_max_cardinality_limit, :cardinality_protection_denylist, :cardinality_protection_overflow_strategy,
+                  :dlq_storage, :dlq_filter
+    attr_reader :adapter_mapping, :pipeline
+
+    def initialize
+      initialize_basic_config
+      initialize_routing_config
+      initialize_feature_configs
+      configure_default_pipeline
+    end
+
+    # Get adapters for given severity
+    #
+    # @param severity [Symbol] Severity level
+    # @return [Array<Symbol>] Adapter names (e.g., [:logs, :errors_tracker])
+    def adapters_for_severity(severity)
+      @adapter_mapping[severity] || @adapter_mapping[:default] || []
+    end
+
+    # Get built pipeline (cached after first call)
+    #
+    # @return [#call] Built middleware pipeline
+    def built_pipeline
+      @built_pipeline ||= @pipeline.build(->(_event_data) {})
+    end
+
+    # Add per-event rate limit rule.
+    #
+    # @param pattern [String] Event name or glob pattern (e.g. "payment.*")
+    # @param limit [Integer] Max events per window for this pattern
+    # @param window [Numeric] Window size in seconds
+    def add_rate_limit_per_event(pattern, limit:, window: 1.0)
+      (@rate_limiting_per_event_limits ||= []) << {
+        pattern: pattern.to_s,
+        limit: limit,
+        window: window.to_f
+      }
+    end
+
+    # Find the most specific rate limit config for a given event name.
+    #
+    # @param event_name [String] Event name to look up
+    # @return [Hash] { limit:, window: }
+    def rate_limit_for(event_name)
+      limits = @rate_limiting_per_event_limits || []
+      match = limits.find do |rule|
+        pattern = rule[:pattern].gsub(".", "\\.").gsub("*", ".*")
+        Regexp.new("^#{pattern}$").match?(event_name.to_s)
+      end
+      m = match || { limit: @rate_limiting_per_event_limit, window: @rate_limiting_global_window }
+      { limit: m[:limit], window: m[:window] }
+    end
+
+    # Add per-controller SLO config.
+    def add_slo_controller(name, action: nil, &)
+      key = action ? "#{name}##{action}" : name
+      cfg = ControllerSLOConfig.new
+      cfg.instance_eval(&) if block_given?
+      (@slo_tracking_controller_configs ||= {})[key] = cfg
+    end
+
+    # Add per-job SLO config.
+    def add_slo_job(name, &)
+      cfg = JobSLOConfig.new
+      cfg.instance_eval(&) if block_given?
+      (@slo_tracking_job_configs ||= {})[name] = cfg
+    end
+
+    # Set slo_tracking enabled — accepts Boolean.
+    def slo_tracking=(value)
+      @slo_tracking_enabled = value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+    end
+
+    # Filter baggage hash to only allowed keys (for tracestate/job propagation).
+    def filter_baggage_for_propagation(hash)
+      return {} if hash.nil? || !hash.is_a?(Hash)
+      return hash unless @security_baggage_protection_enabled
+
+      allowed = (@security_baggage_protection_allowed_keys || E11y::BAGGAGE_PROTECTION_DEFAULT_ALLOWED_KEYS).map(&:to_s)
+      hash.select { |k, _| allowed.include?(k.to_s) }
+    end
+
+    # Register an adapter instance by name.
+    def register_adapter(name, instance)
+      @adapters[name.to_sym] = instance
+    end
+
+    # Set the default adapter(s) used when no severity-specific mapping matches.
+    def default_adapters=(names)
+      @adapter_mapping[:default] = Array(names).map(&:to_sym)
+    end
+
+    # @return [Array<Symbol>] Default adapter names
+    def default_adapters
+      @adapter_mapping[:default]
+    end
+
+    private
+
+    def initialize_basic_config
+      @adapters = {}
+      @log_level = :info
+      @pipeline = E11y::Pipeline::Builder.new
+      @enabled = nil
+      @environment = nil
+      @service_name = nil
+      @enable_http_tracing = false
+    end
+
+    def initialize_routing_config
+      @adapter_mapping = default_adapter_mapping
+      @default_retention_period = 30.days
+      @routing_rules = []
+      @fallback_adapters = [:stdout]
+    end
+
+    def initialize_feature_configs
+      init_instrumentation_configs
+      init_ephemeral_buffer_configs
+      init_error_handling_configs
+      init_rate_limiting_configs
+      init_slo_configs
+      init_security_configs
+      init_tracing_configs
+      init_cardinality_configs
+    end
+
+    def init_instrumentation_configs
+      @rails_instrumentation_enabled = false
+      @rails_instrumentation_custom_mappings = {}
+      @rails_instrumentation_ignore_events = []
+      @logger_bridge_enabled = false
+      @logger_bridge_track_severities = nil
+      @logger_bridge_ignore_patterns = []
+      @sidekiq_enabled = false
+      @active_job_enabled = false
+    end
+
+    def init_ephemeral_buffer_configs
+      @ephemeral_buffer_enabled = false
+      @ephemeral_buffer_flush_on_error = true
+      @ephemeral_buffer_flush_on_statuses = []
+      @ephemeral_buffer_debug_adapters = nil
+      @ephemeral_buffer_job_buffer_limit = nil
+    end
+
+    def init_error_handling_configs
+      @error_handling_fail_on_error = true
+      @dlq_storage = nil
+      @dlq_filter = nil
+    end
+
+    def init_rate_limiting_configs
+      @rate_limiting_enabled = false
+      @rate_limiting_global_limit = 10_000
+      @rate_limiting_global_window = 1.0
+      @rate_limiting_per_event_limit = 1_000
+      @rate_limiting_per_event_limits = []
+    end
+
+    def init_slo_configs
+      @slo_tracking_enabled = true
+      @slo_tracking_http_ignore_statuses = []
+      @slo_tracking_latency_percentiles = [50, 95, 99]
+      @slo_tracking_controller_configs = {}
+      @slo_tracking_job_configs = {}
+    end
+
+    def init_security_configs
+      @security_baggage_protection_enabled = true
+      @security_baggage_protection_allowed_keys = E11y::BAGGAGE_PROTECTION_DEFAULT_ALLOWED_KEYS.dup
+      @security_baggage_protection_block_mode = :silent
+    end
+
+    def init_tracing_configs
+      @tracing_source = :e11y
+      @tracing_default_sample_rate = 0.1
+      @tracing_respect_parent_sampling = true
+      @tracing_per_event_sample_rates = {}
+      @tracing_always_sample_if = nil
+      @opentelemetry_span_creation_patterns = []
+    end
+
+    def init_cardinality_configs
+      @cardinality_protection_max_cardinality_limit = 1000
+      @cardinality_protection_denylist = []
+      @cardinality_protection_overflow_strategy = :relabel
+    end
+
+    def default_adapter_mapping
+      {
+        error: %i[logs errors_tracker],
+        fatal: %i[logs errors_tracker],
+        default: [:logs]
+      }
+    end
+
+    def configure_default_pipeline
+      @pipeline.use E11y::Middleware::TrackLatency
+      @pipeline.use E11y::Middleware::TraceContext
+      @pipeline.use E11y::Middleware::Validation
+      @pipeline.use E11y::Middleware::BaggageProtection
+      @pipeline.use E11y::Middleware::AuditSigning
+      @pipeline.use E11y::Middleware::PIIFilter
+      @pipeline.use E11y::Middleware::RateLimiting
+      @pipeline.use E11y::Middleware::Sampling
+      @pipeline.use E11y::Middleware::Versioning
+      @pipeline.use E11y::Middleware::Routing
+      @pipeline.use E11y::Middleware::EventSlo
+      @pipeline.use E11y::Middleware::SelfMonitoringEmit
+    end
+  end
+
+  # Per-controller SLO config (used by add_slo_controller).
+  class ControllerSLOConfig
+    def slo_target(value = nil)
+      value ? @slo_target = value : @slo_target
+    end
+
+    def latency_target(value = nil)
+      value ? @latency_target = value : @latency_target
+    end
+  end
+
+  # Per-job SLO config (used by add_slo_job).
+  class JobSLOConfig
+    def ignore(value = nil)
+      value.nil? ? @ignore : @ignore = value
+    end
+  end
+end

data/lib/e11y/console.rb

@@ -51,19 +51,17 @@ module E11y
 
       # List all registered event classes
       def events
-        puts "📋 E11y events list"
-        puts "   (Waiting for Event registry implementation)"
-        []
+        Registry.event_classes.map { |e| e.respond_to?(:event_name) ? e.event_name : e.name }
       end
 
-      # List all registered adapters
+      # List all registered adapters (from config.adapters)
       def adapters
-        Adapters::Registry.all.map do |adapter|
+        config.adapters.map do |name, adapter|
           {
-            name: adapter.name,
+            name: name,
             class: adapter.class.name,
-            healthy: adapter.healthy?,
-            capabilities: adapter.capabilities
+            healthy: adapter.respond_to?(:healthy?) ? adapter.healthy? : true,
+            capabilities: adapter.respond_to?(:capabilities) ? adapter.capabilities : {}
           }
         end
       end
@@ -77,8 +75,8 @@ module E11y
       private
 
       def adapters_info
-        Adapters::Registry.all.map do |a|
-          { name: a.name, class: a.class.name, healthy: a.healthy? }
+        config.adapters.map do |name, adapter|
+          { name: name, class: adapter.class.name, healthy: adapter.respond_to?(:healthy?) ? adapter.healthy? : true }
         end
       end
 
@@ -95,13 +93,8 @@ module E11y
     # @return [void]
     def self.configure_for_console
       E11y.configure do |config|
-        # Console-friendly output
-        config.adapters&.clear
-
-        # Use stdout adapter with pretty printing
-        config.adapters&.register :stdout, E11y::Adapters::Stdout.new(
-          colorize: true
-        )
+        config.adapters.clear
+        config.adapters[:stdout] = E11y::Adapters::Stdout.new(colorize: true, format: :rich)
 
         # Show all severities
         # TODO: Implement severity_threshold config

data/lib/e11y/current.rb

@@ -37,12 +37,64 @@ module E11y
   class Current < ActiveSupport::CurrentAttributes
     attribute :trace_id
     attribute :span_id
-    attribute :parent_trace_id # ✅ NEW: Link to parent trace (C17 Resolution)
+    attribute :parent_trace_id # Link to parent trace (C17 Resolution)
+    attribute :sampled # Trace-consistent sampling (ADR-005 §7)
+    attribute :baggage # Key-value metadata for cross-service propagation (ADR-005 §3)
     attribute :request_id
     attribute :user_id
     attribute :ip_address
     attribute :user_agent
     attribute :request_method
     attribute :request_path
+
+    # Add baggage key-value (propagated via tracestate / job metadata).
+    # Respects config.security_baggage_protection_*: blocks PII keys per allowed_keys (ADR-006 §5.5).
+    #
+    # @param key [String, Symbol]
+    # @param value [Object] Converted to string
+    # @raise [E11y::BaggagePiiError] when block_mode is :raise and key not allowed
+    def self.add_baggage(key, value)
+      cfg = E11y.config
+      if cfg&.security_baggage_protection_enabled
+        allowed = (cfg.security_baggage_protection_allowed_keys || E11y::BAGGAGE_PROTECTION_DEFAULT_ALLOWED_KEYS).map(&:to_s)
+        unless allowed.include?(key.to_s)
+          message = "[E11y] Blocked PII from E11y baggage: key=#{key.inspect}"
+          case cfg.security_baggage_protection_block_mode || :silent
+          when :silent then E11y.logger&.debug(message)
+          when :warn then E11y.logger&.warn(message)
+          when :raise then raise E11y::BaggagePiiError, "#{message}. Only allowed keys: #{allowed.join(', ')}"
+          end
+          return
+        end
+      end
+      self.baggage = (baggage || {}).merge(key.to_s => value.to_s)
+    end
+
+    # Get baggage value by key.
+    # @param key [String, Symbol]
+    # @return [String, nil]
+    def self.get_baggage(key)
+      baggage&.[](key.to_s)
+    end
+
+    # Returns current attributes as a hash for sampling context (symbol keys, nil values omitted).
+    # Callers may merge job-specific keys (job_class, queue) when in job context.
+    #
+    # @return [Hash{Symbol=>Object}]
+    def self.to_context
+      {
+        trace_id: trace_id,
+        span_id: span_id,
+        parent_trace_id: parent_trace_id,
+        sampled: sampled,
+        baggage: baggage,
+        request_id: request_id,
+        user_id: user_id,
+        ip_address: ip_address,
+        user_agent: user_agent,
+        request_method: request_method,
+        request_path: request_path
+      }.compact
+    end
   end
 end