e11y 0.1.0 → 0.2.0

data/lib/e11y/event/base.rb

@@ -78,6 +78,7 @@ module E11y
         # - Cached severity/adapters (avoid repeated method calls)
         # - Inline timestamp generation
         # - Configurable validation mode (:always, :sampled, :never)
+        # - Auto-calculated retention_until from retention_period
         #
         # @param payload [Hash] Event data matching the schema
         # @return [Hash] Event hash (includes metadata)
@@ -88,28 +89,57 @@ module E11y
         #
         # @raise [E11y::ValidationError] if payload doesn't match schema (when validation runs)
         def track(**payload)
-          # 1. Validate payload against schema (respects validation_mode)
-          validate_payload!(payload) if should_validate?
+          return unless E11y.config.enabled
 
-          # 2. Build event hash with metadata (use pre-allocated template, reduce GC)
-          # Cache frequently accessed values to avoid method call overhead
-          event_severity = severity
-          event_adapters = adapters
+          # Build event data hash for pipeline processing
+          event_data = {
+            event_class: self,
+            event_name: event_name,
+            payload: payload,
+            severity: severity,
+            version: version,
+            adapters: adapters,
+            timestamp: Time.now.utc,
+            retention_period: retention_period,
+            context: build_context
+          }
 
-          # 3. TODO Phase 2: Send to pipeline
-          # E11y::Pipeline.process(event_hash)
+          # Pass through middleware pipeline (ADR-001 §3.2)
+          # Pipeline handles: validation, PII filtering, rate limiting, sampling, routing
+          # Routing middleware is the LAST middleware and it writes to adapters directly
+          E11y.config.built_pipeline.call(event_data)
 
-          # 4. Return event hash (pre-allocated structure for performance)
+          # Return event data for testing/debugging
+          event_data
+        end
+
+        # Build event hash
+        # @api private
+        def build_event_hash(event_severity, event_adapters, event_timestamp, event_retention_period, payload)
           {
             event_name: event_name,
             payload: payload,
             severity: event_severity,
             version: version,
             adapters: event_adapters,
-            timestamp: Time.now.utc.iso8601(3) # ISO8601 with milliseconds
+            timestamp: event_timestamp.iso8601(3), # ISO8601 with milliseconds
+            retention_until: (event_timestamp + event_retention_period).iso8601, # Auto-calculated
+            audit_event: audit_event? # For routing rules
           }
         end
 
+        # Build current context for event
+        # @api private
+        def build_context
+          {
+            trace_id: E11y::Current.trace_id,
+            span_id: E11y::Current.span_id,
+            parent_trace_id: E11y::Current.parent_trace_id,
+            request_id: E11y::Current.request_id,
+            user_id: E11y::Current.user_id
+          }.compact
+        end
+
         # Configure validation mode for performance tuning
         #
         # Modes:
@@ -242,6 +272,41 @@ module E11y
           1
         end
 
+        # Set or get retention period for this event
+        #
+        # Retention period determines how long events should be kept in storage.
+        # Used by routing middleware to select appropriate adapters (hot/warm/cold storage).
+        #
+        # @param value [ActiveSupport::Duration, nil] Retention period (e.g., 30.days, 7.years)
+        # @return [ActiveSupport::Duration] Current retention period
+        #
+        # @example Short retention (debug logs)
+        #   class DebugEvent < E11y::Event::Base
+        #     retention_period 7.days
+        #   end
+        #
+        # @example Long retention (audit events)
+        #   class UserDeletedEvent < E11y::Event::Base
+        #     audit_event true
+        #     retention_period 7.years  # GDPR compliance
+        #   end
+        #
+        # @example Default retention (from config)
+        #   class OrderEvent < E11y::Event::Base
+        #     # No retention_period specified → uses config default (30 days)
+        #   end
+        def retention_period(value = nil)
+          @retention_period = value if value
+          # Return explicitly set retention_period OR inherit from parent (if set) OR config default OR final fallback
+          return @retention_period if @retention_period
+          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@retention_period)
+            return superclass.retention_period
+          end
+
+          # Fallback to configuration or 30 days
+          E11y.configuration&.default_retention_period || 30.days
+        end
+
         # Set or get adapters for this event
         #
         # Adapters are referenced by NAME (e.g., :logs, :errors_tracker).

data/lib/e11y/event/value_sampling_config.rb

@@ -62,23 +62,29 @@ module E11y
         end
       end
 
+      # Valid comparison types for value-based sampling
+      VALID_COMPARISON_TYPES = %i[greater_than less_than equals in_range].freeze
+      # Comparison types that require numeric thresholds
+      NUMERIC_COMPARISON_TYPES = %i[greater_than less_than].freeze
+
       private
 
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # Validation requires checking multiple comparison types and threshold types
       def validate_comparisons!
         raise ArgumentError, "At least one comparison required" if comparisons.empty?
 
         comparisons.each do |type, threshold|
-          unless %i[greater_than less_than equals in_range].include?(type)
-            raise ArgumentError, "Invalid comparison type: #{type}"
-          end
+          raise ArgumentError, "Invalid comparison type: #{type}" unless VALID_COMPARISON_TYPES.include?(type)
 
           raise ArgumentError, "in_range requires a Range" if type == :in_range && !threshold.is_a?(Range)
 
-          if %i[greater_than less_than].include?(type) && !threshold.is_a?(Numeric)
+          if NUMERIC_COMPARISON_TYPES.include?(type) && !threshold.is_a?(Numeric)
             raise ArgumentError, "#{type} requires a Numeric threshold"
           end
         end
       end
+      # rubocop:enable Metrics/CyclomaticComplexity
     end
   end
 end

data/lib/e11y/events/rails/http/request.rb

@@ -11,7 +11,7 @@ module E11y
             required(:duration).filled(:float)
             optional(:controller).maybe(:string)
             optional(:action).maybe(:string)
-            optional(:format).maybe(:string)
+            optional(:format) # Rails passes Symbol (e.g., :html, :json)
             optional(:status).maybe(:integer)
             optional(:view_runtime).maybe(:float)
             optional(:db_runtime).maybe(:float)

data/lib/e11y/instruments/active_job.rb

@@ -85,7 +85,7 @@ module E11y
         def setup_job_buffer_active_job
           return unless E11y.config.request_buffer&.enabled
 
-          E11y::Buffers::RequestScopedBuffer.start!
+          E11y::Buffers::RequestScopedBuffer.initialize!
         rescue StandardError => e
           # C18: Don't fail job if buffer setup fails
           warn "[E11y] Failed to start job buffer: #{e.message}"
@@ -95,7 +95,7 @@ module E11y
         def handle_job_error_active_job(_error)
           return unless E11y.config.request_buffer&.enabled
 
-          E11y::Buffers::RequestScopedBuffer.flush_on_error!
+          E11y::Buffers::RequestScopedBuffer.flush_on_error
         rescue StandardError => e
           # C18: Don't fail job if buffer flush fails
           warn "[E11y] Failed to flush job buffer on error: #{e.message}"
@@ -106,7 +106,7 @@ module E11y
           # Flush buffer on success (not on error, already flushed in rescue)
           if !$ERROR_INFO && E11y.config.request_buffer&.enabled
             begin
-              E11y::Buffers::RequestScopedBuffer.flush!
+              E11y::Buffers::RequestScopedBuffer.discard
             rescue StandardError => e
               # C18: Don't fail job if buffer flush fails
               warn "[E11y] Failed to flush job buffer: #{e.message}"
@@ -139,6 +139,8 @@ module E11y
         # @param start_time [Time] Job start time
         # @return [void]
         # @api private
+        # rubocop:disable Metrics/AbcSize
+        # SLO tracking requires config check, duration calculation, method call, and error handling
         def track_job_slo_active_job(job, status, start_time)
           return unless E11y.config.slo_tracking&.enabled
 
@@ -155,6 +157,7 @@ module E11y
           # C18: Don't fail if SLO tracking fails
           E11y.logger.warn("[E11y] SLO tracking error: #{e.message}", error: e.class.name)
         end
+        # rubocop:enable Metrics/AbcSize
       end
 
       # Custom attribute accessors for trace context (C17 Hybrid Tracing)

data/lib/e11y/instruments/rails_instrumentation.rb

@@ -30,18 +30,18 @@ module E11y
       #
       # @return [Hash<String, Class>] Event mappings
       DEFAULT_RAILS_EVENT_MAPPING = {
-        "sql.active_record" => "Events::Rails::Database::Query",
-        "process_action.action_controller" => "Events::Rails::Http::Request",
-        "render_template.action_view" => "Events::Rails::View::Render",
-        "send_file.action_controller" => "Events::Rails::Http::SendFile",
-        "redirect_to.action_controller" => "Events::Rails::Http::Redirect",
-        "cache_read.active_support" => "Events::Rails::Cache::Read",
-        "cache_write.active_support" => "Events::Rails::Cache::Write",
-        "cache_delete.active_support" => "Events::Rails::Cache::Delete",
-        "enqueue.active_job" => "Events::Rails::Job::Enqueued",
-        "enqueue_at.active_job" => "Events::Rails::Job::Scheduled",
-        "perform_start.active_job" => "Events::Rails::Job::Started",
-        "perform.active_job" => "Events::Rails::Job::Completed"
+        "sql.active_record" => "E11y::Events::Rails::Database::Query",
+        "process_action.action_controller" => "E11y::Events::Rails::Http::Request",
+        "render_template.action_view" => "E11y::Events::Rails::View::Render",
+        "send_file.action_controller" => "E11y::Events::Rails::Http::SendFile",
+        "redirect_to.action_controller" => "E11y::Events::Rails::Http::Redirect",
+        "cache_read.active_support" => "E11y::Events::Rails::Cache::Read",
+        "cache_write.active_support" => "E11y::Events::Rails::Cache::Write",
+        "cache_delete.active_support" => "E11y::Events::Rails::Cache::Delete",
+        "enqueue.active_job" => "E11y::Events::Rails::Job::Enqueued",
+        "enqueue_at.active_job" => "E11y::Events::Rails::Job::Scheduled",
+        "perform_start.active_job" => "E11y::Events::Rails::Job::Started",
+        "perform.active_job" => "E11y::Events::Rails::Job::Completed"
       }.freeze
 
       # Setup Rails instrumentation
@@ -61,11 +61,26 @@ module E11y
       end
 
       # Subscribe to a specific ASN event
+      #
+      # **Architecture Note**: We pass the entire payload to the event class.
+      # Each event class defines its own schema (via dry-schema), which:
+      # 1. **Type-checks** fields automatically
+      # 2. **Filters** only relevant fields (unknown fields ignored)
+      # 3. **Validates** payload structure
+      #
+      # This eliminates the need for manual whitelisting (DRY principle).
+      # PII filtering happens in the middleware pipeline, not here.
+      #
       # @param asn_pattern [String] ActiveSupport::Notifications pattern
       # @param e11y_event_class_name [String] E11y event class name
       # @return [void]
+      #
+      # @example
+      #   # ASN payload: { controller: "Users", action: "index", password: "secret" }
+      #   # Event schema: schema { required(:controller).string; required(:action).string }
+      #   # Result: { controller: "Users", action: "index" } - password filtered by schema
       def self.subscribe_to_event(asn_pattern, e11y_event_class_name)
-        ActiveSupport::Notifications.subscribe(asn_pattern) do |name, start, finish, id, payload|
+        ActiveSupport::Notifications.subscribe(asn_pattern) do |name, start, finish, _id, payload|
           # Convert ASN event → E11y event
           duration = (finish - start) * 1000 # Convert to milliseconds
 
@@ -73,11 +88,14 @@ module E11y
           e11y_event_class = resolve_event_class(e11y_event_class_name)
           next unless e11y_event_class
 
-          # Track E11y event with extracted payload
+          # Extract job info from job object if present (ActiveJob events)
+          extracted_payload = extract_job_info_from_object(payload)
+
+          # Track E11y event - schema will filter relevant fields
           e11y_event_class.track(
             event_name: name,
             duration: duration,
-            **extract_relevant_payload(payload)
+            **extracted_payload # Pass all payload, schema filters
           )
         rescue StandardError => e
           # Don't crash the app if event tracking fails
@@ -109,22 +127,27 @@ module E11y
         ignore_list.include?(pattern)
       end
 
-      # Extract relevant payload fields from ASN event
+      # Extract job info from job object (ActiveJob events)
       #
-      # Filters out PII and noisy fields, keeping only relevant data.
+      # ActiveJob events pass job object, not flattened fields.
+      # This method extracts relevant fields from job object.
       #
       # @param payload [Hash] ASN event payload
-      # @return [Hash] Filtered payload
-      def self.extract_relevant_payload(payload)
-        # Extract only relevant fields (avoid PII, reduce noise)
-        # This is a basic implementation - specific event classes can override
-        payload.slice(
-          :controller, :action, :format, :status,
-          :allocations, :db_runtime, :view_runtime,
-          :name, :sql, :connection_id,
-          :key, :hit,
-          :job_class, :job_id, :queue
-        )
+      # @return [Hash] Payload with extracted job info
+      def self.extract_job_info_from_object(payload)
+        # Return early if no job object
+        return payload unless payload[:job]
+
+        # Clone payload to avoid mutation
+        result = payload.dup
+        job = result.delete(:job)
+
+        # Extract job fields if not already present
+        result[:job_class] ||= job.class.name
+        result[:job_id] ||= job.job_id
+        result[:queue] ||= job.queue_name
+
+        result
       end
 
       # Resolve event class from string name

data/lib/e11y/instruments/sidekiq.rb

@@ -43,7 +43,7 @@ module E11y
       # **C17 Hybrid Tracing**: Creates NEW trace_id for job, but preserves parent link.
       # **C18 Non-Failing**: E11y errors don't fail jobs (observability is secondary to business logic).
       class ServerMiddleware
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        # rubocop:disable Metrics/AbcSize
         def call(_worker, job, queue)
           # C18: Disable fail_on_error for jobs (observability should not block business logic)
           original_fail_on_error = E11y.config.error_handling.fail_on_error
@@ -73,7 +73,7 @@ module E11y
           # Restore original setting
           E11y.config.error_handling.fail_on_error = original_fail_on_error
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        # rubocop:enable Metrics/AbcSize
 
         private
 
@@ -97,18 +97,18 @@ module E11y
         def setup_job_buffer
           return unless E11y.config.request_buffer&.enabled
 
-          E11y::Buffers::RequestScopedBuffer.start!
+          E11y::Buffers::RequestScopedBuffer.initialize!
         rescue StandardError => e
           # C18: Don't fail job if buffer setup fails
           warn "[E11y] Failed to start job buffer: #{e.message}"
         end
 
         # Handle job error (C18: Non-Failing Event Tracking)
-        def handle_job_error(error)
+        def handle_job_error(_error)
           # Flush buffer on error (includes debug events)
           return unless E11y.config.request_buffer&.enabled
 
-          E11y::Buffers::RequestScopedBuffer.flush_on_error!
+          E11y::Buffers::RequestScopedBuffer.flush_on_error
         rescue StandardError => e
           # C18: Don't fail job if buffer flush fails
           warn "[E11y] Failed to flush job buffer on error: #{e.message}"
@@ -116,10 +116,10 @@ module E11y
 
         # Cleanup job-scoped context
         def cleanup_job_context
-          # Flush buffer on success (not on error, already flushed in rescue)
+          # Discard buffer on success (not on error, already flushed in rescue)
           if !$ERROR_INFO && E11y.config.request_buffer&.enabled
             begin
-              E11y::Buffers::RequestScopedBuffer.flush!
+              E11y::Buffers::RequestScopedBuffer.discard
             rescue StandardError => e
               # C18: Don't fail job if buffer flush fails
               warn "[E11y] Failed to flush job buffer: #{e.message}"

data/lib/e11y/logger/bridge.rb

@@ -8,7 +8,7 @@ module E11y
     #
     # Transparent wrapper around Rails.logger that:
     # 1. Delegates all calls to the original logger (preserves Rails behavior)
-    # 2. Optionally tracks log calls as E11y events (when enabled)
+    # 2. Tracks log calls as E11y events (when logger_bridge.enabled = true)
     #
     # **Why SimpleDelegator instead of full replacement:**
     # - ✅ Simpler: No need to reimplement entire Logger API
@@ -22,8 +22,7 @@ module E11y
     #
     # @example Manual setup
     #   E11y.configure do |config|
-    #     config.logger_bridge.enabled = true
-    #     config.logger_bridge.track_to_e11y = true  # Send logs to E11y events (optional)
+    #     config.logger_bridge.enabled = true  # Wrap Rails.logger and send logs to E11y
     #   end
     #
     # @see ADR-008 §7 (Rails.logger Migration)
@@ -36,10 +35,10 @@ module E11y
       # @return [void]
       def self.setup!
         return unless E11y.config.logger_bridge&.enabled
-        return unless defined?(Rails)
+        return unless defined?(::Rails)
 
         # Wrap Rails.logger (preserves original behavior)
-        Rails.logger = Bridge.new(Rails.logger)
+        ::Rails.logger = Bridge.new(::Rails.logger)
       end
 
       # Initialize bridge wrapper
@@ -56,7 +55,7 @@ module E11y
         }
       end
 
-      # Intercept logger methods to optionally track to E11y
+      # Intercept logger methods to track to E11y
       # All calls are delegated to the original logger via SimpleDelegator
 
       # Log debug message
@@ -64,7 +63,7 @@ module E11y
       # @yield Block that returns log message
       # @return [true] Always returns true (Logger API)
       def debug(message = nil, &)
-        track_to_e11y(:debug, message, &) if should_track_severity?(:debug)
+        track_to_e11y(:debug, message, &)
         super # Delegate to original logger
       end
 
@@ -73,7 +72,7 @@ module E11y
       # @yield Block that returns log message
       # @return [true] Always returns true (Logger API)
       def info(message = nil, &)
-        track_to_e11y(:info, message, &) if should_track_severity?(:info)
+        track_to_e11y(:info, message, &)
         super # Delegate to original logger
       end
 
@@ -82,7 +81,7 @@ module E11y
       # @yield Block that returns log message
       # @return [true] Always returns true (Logger API)
       def warn(message = nil, &)
-        track_to_e11y(:warn, message, &) if should_track_severity?(:warn)
+        track_to_e11y(:warn, message, &)
         super # Delegate to original logger
       end
 
@@ -91,7 +90,7 @@ module E11y
       # @yield Block that returns log message
       # @return [true] Always returns true (Logger API)
       def error(message = nil, &)
-        track_to_e11y(:error, message, &) if should_track_severity?(:error)
+        track_to_e11y(:error, message, &)
         super # Delegate to original logger
       end
 
@@ -100,7 +99,7 @@ module E11y
       # @yield Block that returns log message
       # @return [true] Always returns true (Logger API)
       def fatal(message = nil, &)
-        track_to_e11y(:fatal, message, &) if should_track_severity?(:fatal)
+        track_to_e11y(:fatal, message, &)
         super # Delegate to original logger
       end
 
@@ -112,7 +111,7 @@ module E11y
       # @return [true] Always returns true (Logger API)
       def add(severity, message = nil, progname = nil, &)
         e11y_severity = @severity_mapping[severity] || :info
-        track_to_e11y(e11y_severity, message || progname, &) if should_track_severity?(e11y_severity)
+        track_to_e11y(e11y_severity, message || progname, &)
         super # Delegate to original logger
       end
 
@@ -120,48 +119,16 @@ module E11y
 
       private
 
-      # Check if E11y tracking is enabled for specific severity
-      # Supports both boolean and per-severity Hash configuration
-      #
-      # @param severity [Symbol] E11y severity (:debug, :info, :warn, :error, :fatal)
-      # @return [Boolean]
-      #
-      # @example Boolean config (all or nothing)
-      #   config.logger_bridge.track_to_e11y = true  # Track all
-      #   config.logger_bridge.track_to_e11y = false # Track none
-      #
-      # @example Per-severity config (granular control)
-      #   config.logger_bridge.track_to_e11y = {
-      #     debug: false,
-      #     info: true,
-      #     warn: true,
-      #     error: true,
-      #     fatal: true
-      #   }
-      def should_track_severity?(severity)
-        config = E11y.config.logger_bridge&.track_to_e11y
-        return false unless config
-
-        case config
-        when TrueClass
-          true # Track all severities
-        when FalseClass
-          false # Track none
-        when Hash
-          config[severity] || false # Check per-severity config
-        else
-          false # Unknown config type
-        end
-      end
-
       # Track log message as E11y event
       # @param severity [Symbol] E11y severity
       # @param message [String, nil] Log message
       # @yield Block that returns log message
       # @return [void]
-      def track_to_e11y(severity, message = nil, &block)
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # Logger tracking requires message extraction, validation, event class lookup, and error handling
+      def track_to_e11y(severity, message = nil)
         # Extract message
-        msg = message || (block_given? ? block.call : nil)
+        msg = message || (block_given? ? yield : nil)
         return if msg.nil? || (msg.respond_to?(:empty?) && msg.empty?)
 
         # Track to E11y using severity-specific class
@@ -174,12 +141,15 @@ module E11y
       rescue StandardError => e
         # Silently ignore E11y tracking errors (don't break logging!)
         # In development/test, you might want to log this
-        warn "E11y logger tracking failed: #{e.message}" if defined?(Rails) && Rails.env.development?
+        warn "E11y logger tracking failed: #{e.message}" if defined?(::Rails) && ::Rails.env.development?
       end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # Get event class for severity
       # @param severity [Symbol] E11y severity
       # @return [Class] Event class
+      # rubocop:disable Lint/DuplicateBranch
+      # Unknown severities intentionally fallback to Info (same as :info)
       def event_class_for_severity(severity)
         case severity
         when :debug then E11y::Events::Rails::Log::Debug
@@ -190,15 +160,15 @@ module E11y
         else E11y::Events::Rails::Log::Info # Fallback
         end
       end
+      # rubocop:enable Lint/DuplicateBranch
 
       # Extract caller location (first caller outside E11y)
       # @return [String, nil] Caller location string
       def extract_caller_location
-        caller_locations.find do |loc|
-          !loc.path.include?("e11y")
-        end&.then do |loc|
-          "#{loc.path}:#{loc.lineno}:in `#{loc.label}'"
-        end
+        loc = caller_locations.find { |l| !l.path.include?("e11y") }
+        return nil unless loc
+
+        "#{loc.path}:#{loc.lineno}:in `#{loc.label}'"
       end
     end
   end