e11y 0.2.0 → 1.1.0

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

data/lib/e11y/debug/pipeline_inspector.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+
+module E11y
+  module Debug
+    # Debug utility to trace events through the pipeline with per-middleware logging.
+    #
+    # Runs the full pipeline including adapter writes. For debugging, use Stdout or
+    # InMemory adapter. Stub adapters in tests if needed.
+    #
+    # @see E11y.trace
+    class PipelineInspector
+      # Wraps a middleware to log enter/exit for pipeline tracing.
+      class TracingWrapper
+        def initialize(middleware_class, next_app, name, args: [], options: {})
+          @middleware_class = middleware_class
+          @next_app = next_app
+          @name = name
+          @args = args
+          @options = options
+        end
+
+        def call(event_data)
+          log_enter(@name)
+          result = @middleware_class.new(@next_app, *@args, **@options).call(event_data)
+          log_exit(@name)
+          result
+        end
+
+        private
+
+        def log_enter(name)
+          prefix = $stdout.tty? ? "\e[33m" : ""
+          suffix = $stdout.tty? ? "\e[0m" : ""
+          print "  #{prefix}#{name}#{suffix}... "
+        end
+
+        def log_exit(_name)
+          mark = $stdout.tty? ? "\e[32m✓\e[0m" : "✓"
+          puts mark
+        end
+      end
+
+      class << self
+        # Traces an event through the pipeline with per-middleware logging.
+        # Note: adapters WILL receive the event.
+        #
+        # @param event_class [Class] Event class
+        # @param payload [Hash] Event payload
+        # @return [Hash] event_data after pipeline
+        def trace_event(event_class, **payload)
+          event_name = event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name
+          puts "\n🔍 Tracing Event Pipeline: #{event_name}\n\n"
+          event_data = build_event_data(event_class, payload)
+          pipeline = build_tracing_pipeline
+          result = pipeline.call(event_data)
+          puts "\n✅ Pipeline trace complete\n"
+          result
+        end
+
+        private
+
+        def build_event_data(event_class, payload)
+          {
+            event_class: event_class,
+            event_name: event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name,
+            payload: payload,
+            severity: event_class.respond_to?(:severity) ? event_class.severity : :info,
+            version: event_class.respond_to?(:version) ? event_class.version : 1,
+            adapters: event_class.respond_to?(:adapters) ? event_class.adapters : nil,
+            timestamp: Time.now.utc,
+            retention_period: event_class.respond_to?(:retention_period) ? event_class.retention_period : 30.days,
+            context: {}
+          }
+        end
+
+        def build_tracing_pipeline
+          builder = E11y.configuration.pipeline
+          final_app = ->(event_data) { event_data }
+
+          builder.middlewares.reverse.reduce(final_app) do |next_app, entry|
+            name = entry.middleware_class.name.split("::").last
+            TracingWrapper.new(
+              entry.middleware_class,
+              next_app,
+              name,
+              args: entry.args,
+              options: entry.options
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/documentation/generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module E11y
+  module Documentation
+    # Generates Markdown documentation for registered E11y events.
+    class Generator
+      def self.generate(output_dir, criteria: {}, grep: nil)
+        classes = criteria.any? ? E11y::Registry.where(**criteria) : E11y::Registry.event_classes
+        classes = classes.select { |c| (c.respond_to?(:event_name) ? c.event_name : c.name).to_s.include?(grep) } if grep
+
+        FileUtils.mkdir_p(output_dir)
+        write_index(output_dir, classes)
+        classes.each { |klass| write_event_doc(output_dir, klass) }
+      end
+
+      def self.write_index(output_dir, classes)
+        lines = ["# E11y Events", "", "| Event | Class | Severity |", "|-------|-------|----------|"]
+        classes.each do |klass|
+          name = klass.respond_to?(:event_name) ? klass.event_name : klass.name
+          sev = klass.respond_to?(:severity) ? klass.severity : "—"
+          lines << "| #{name} | #{klass.name} | #{sev} |"
+        end
+        File.write(File.join(output_dir, "README.md"), "#{lines.join("\n")}\n")
+      end
+
+      def self.write_event_doc(output_dir, klass)
+        name = klass.respond_to?(:event_name) ? klass.event_name : klass.name
+        schema_keys = extract_schema_keys(klass)
+        sev = klass.respond_to?(:severity) ? klass.severity : "—"
+        lines = ["# #{name}", "", "- **Class:** #{klass.name}", "- **Severity:** #{sev}"]
+        lines << "- **Schema keys:** #{schema_keys.join(', ')}" if schema_keys&.any?
+        lines << ""
+        File.write(File.join(output_dir, "#{name.to_s.tr('.', '_')}.md"), "#{lines.join("\n")}\n")
+      end
+
+      def self.extract_schema_keys(klass)
+        return nil unless klass.respond_to?(:compiled_schema)
+
+        schema = klass.compiled_schema
+        return nil if schema.nil? || !schema.respond_to?(:key_map)
+
+        schema.key_map.keys.map(&:name)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end