e11y 0.2.0 → 1.1.0

data/lib/e11y/instruments/rails_instrumentation.rb

@@ -10,15 +10,14 @@ module E11y
     # **Unidirectional Flow:** ASN → E11y
     #
     # @example Basic usage
-    #   # Automatically enabled by E11y::Railtie if config.rails_instrumentation.enabled = true
+    #   # Automatically enabled by E11y::Railtie if config.rails_instrumentation_enabled = true
     #   E11y::Instruments::RailsInstrumentation.setup!
     #
     # @example Custom event mapping
     #   E11y.configure do |config|
-    #     config.rails_instrumentation do
-    #       event_class_for 'sql.active_record', MyApp::CustomQueryEvent
-    #       ignore_event 'cache_read.active_support'
-    #     end
+    #     config.rails_instrumentation_enabled = true
+    #     config.rails_instrumentation_custom_mappings['sql.active_record'] = MyApp::CustomQueryEvent
+    #     config.rails_instrumentation_ignore_events << 'cache_read.active_support'
     #   end
     #
     # @see ADR-008 §4.1 (Unidirectional Flow ASN → E11y)
@@ -41,6 +40,7 @@ module E11y
         "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: Completed on success, Failed on exception (routed in track_rails_event)
         "perform.active_job" => "E11y::Events::Rails::Job::Completed"
       }.freeze
 
@@ -50,7 +50,7 @@ module E11y
       #
       # @return [void]
       def self.setup!
-        return unless E11y.config.rails_instrumentation&.enabled
+        return unless E11y.config.rails_instrumentation_enabled
 
         # Subscribe to each configured event pattern
         event_mapping.each do |asn_pattern, e11y_event_class_name|
@@ -81,25 +81,50 @@ module E11y
       #   # 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|
-          # Convert ASN event → E11y event
-          duration = (finish - start) * 1000 # Convert to milliseconds
+          track_rails_event(name, start, finish, payload, e11y_event_class_name)
+        rescue StandardError => e
+          warn "[E11y] Failed to track Rails event #{name}: #{e.message}"
+        end
+      end
 
-          # Resolve event class (string → constant)
+      def self.track_rails_event(name, start, finish, payload, e11y_event_class_name)
+        duration = (finish - start) * 1000
+        extracted_payload = extract_job_info_from_object(payload)
+
+        # perform.active_job: route to Failed when job raised exception
+        if name == "perform.active_job" && job_failed?(payload)
+          e11y_event_class = resolve_event_class("E11y::Events::Rails::Job::Failed")
+          extracted_payload = extracted_payload.merge(extract_job_exception_info(payload))
+        else
           e11y_event_class = resolve_event_class(e11y_event_class_name)
-          next unless e11y_event_class
+          extracted_payload = extracted_payload.merge(severity: :error) if process_action_error?(name, payload)
+        end
 
-          # Extract job info from job object if present (ActiveJob events)
-          extracted_payload = extract_job_info_from_object(payload)
+        return unless e11y_event_class
 
-          # Track E11y event - schema will filter relevant fields
-          e11y_event_class.track(
-            event_name: name,
-            duration: duration,
-            **extracted_payload # Pass all payload, schema filters
-          )
-        rescue StandardError => e
-          # Don't crash the app if event tracking fails
-          warn "[E11y] Failed to track Rails event #{name}: #{e.message}"
+        e11y_event_class.track(event_name: name, duration: duration, **extracted_payload)
+      end
+
+      def self.process_action_error?(name, payload)
+        name == "process_action.action_controller" && (payload[:exception] || payload["exception"])
+      end
+
+      def self.job_failed?(payload)
+        payload[:exception].present? || payload["exception"].present?
+      end
+
+      # Extract error_class and error_message from ActiveJob exception payload.
+      # Rails passes exception as ["ErrorClass", "message"] or exception_object.
+      def self.extract_job_exception_info(payload)
+        ex = payload[:exception] || payload["exception"]
+        return {} unless ex
+
+        if ex.is_a?(Array) && ex.size >= 2
+          { error_class: ex[0].to_s, error_message: ex[1].to_s }
+        elsif ex.respond_to?(:class) && ex.respond_to?(:message)
+          { error_class: ex.class.name, error_message: ex.message.to_s }
+        else
+          {}
         end
       end
 
@@ -110,9 +135,9 @@ module E11y
           mapping = DEFAULT_RAILS_EVENT_MAPPING.dup
 
           # Apply custom mappings from config (Devise-style overrides)
-          custom_mappings = E11y.config.rails_instrumentation&.custom_mappings || {}
+          custom_mappings = E11y.config.rails_instrumentation_custom_mappings || {}
           custom_mappings.each do |pattern, event_class|
-            mapping[pattern] = event_class.name
+            mapping[pattern] = event_class.respond_to?(:name) ? event_class.name : event_class.to_s
           end
 
           mapping
@@ -123,7 +148,7 @@ module E11y
       # @param pattern [String] ASN event pattern
       # @return [Boolean] true if should be ignored
       def self.ignored?(pattern)
-        ignore_list = E11y.config.rails_instrumentation&.ignore_events || []
+        ignore_list = E11y.config.rails_instrumentation_ignore_events || []
         ignore_list.include?(pattern)
       end
 

data/lib/e11y/instruments/sidekiq.rb

@@ -23,62 +23,151 @@ module E11y
     #
     # @see ADR-008 §9 (Sidekiq Integration)
     module Sidekiq
+      # Shared helper: detect raw Sidekiq jobs (not ActiveJob-wrapped)
+      module RawSidekiqJob
+        def raw_sidekiq_job?(job)
+          job_class = job["class"].to_s
+          return false if job_class.include?("ActiveJob::QueueAdapters::SidekiqAdapter")
+          return false if job["wrapped"].present?
+
+          true
+        end
+      end
+
+      # Emits job lifecycle events (Started, Completed, Failed) for ServerMiddleware
+      module JobEventEmitter
+        def emit_job_started(job, queue)
+          Events::Rails::Job::Started.track(
+            event_name: "sidekiq.perform_start",
+            duration: 0,
+            job_class: job["class"],
+            job_id: job["jid"],
+            queue: queue
+          )
+        rescue StandardError => e
+          warn "[E11y] Failed to emit job Started: #{e.message}"
+        end
+
+        def emit_job_completed(job, queue, start_time)
+          duration_ms = ((Time.now - start_time) * 1000).round(2)
+          Events::Rails::Job::Completed.track(
+            event_name: "sidekiq.perform",
+            duration: duration_ms,
+            job_class: job["class"],
+            job_id: job["jid"],
+            queue: queue
+          )
+        rescue StandardError => e
+          warn "[E11y] Failed to emit job Completed: #{e.message}"
+        end
+
+        def emit_job_failed(job, queue, start_time, error)
+          duration_ms = ((Time.now - start_time) * 1000).round(2)
+          Events::Rails::Job::Failed.track(
+            event_name: "sidekiq.perform",
+            duration: duration_ms,
+            job_class: job["class"],
+            job_id: job["jid"],
+            queue: queue,
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        rescue StandardError => e
+          warn "[E11y] Failed to emit job Failed: #{e.message}"
+        end
+      end
+
       # Client-side middleware: Inject trace context when enqueueing job
       #
       # **C17 Hybrid Tracing**: Propagates parent_trace_id to job metadata.
       # Job will create NEW trace_id but keep link to parent.
+      #
+      # **Job lifecycle events**: Emits Events::Rails::Job::Enqueued for raw Sidekiq jobs only.
+      # ActiveJob jobs are handled by RailsInstrumentation (ASN).
       class ClientMiddleware
-        def call(_worker_class, job, _queue, _redis_pool)
+        include RawSidekiqJob
+
+        def call(worker_class, job, queue, _redis_pool)
           # Inject current trace context into job metadata as parent trace
           # Job will generate NEW trace_id but keep parent link (C17)
           job["e11y_parent_trace_id"] = E11y::Current.trace_id if E11y::Current.trace_id
           job["e11y_parent_span_id"] = E11y::Current.span_id if E11y::Current.span_id
+          job["e11y_sampled"] = E11y::Current.sampled if E11y::Current.respond_to?(:sampled) && !E11y::Current.sampled.nil?
+          baggage = E11y::Tracing::Propagator.baggage_for_propagation_from_current
+          job["e11y_baggage"] = baggage if baggage.any?
+
+          # Emit Enqueued for raw Sidekiq jobs only (ActiveJob emits via ASN)
+          emit_job_enqueued(worker_class, job, queue) if raw_sidekiq_job?(job)
 
           yield
         end
+
+        private
+
+        def emit_job_enqueued(worker_class, job, queue)
+          Events::Rails::Job::Enqueued.track(
+            event_name: "sidekiq.enqueue",
+            duration: 0,
+            job_class: worker_class.to_s,
+            job_id: job["jid"],
+            queue: queue
+          )
+        rescue StandardError => e
+          warn "[E11y] Failed to emit job Enqueued: #{e.message}"
+        end
       end
 
       # Server-side middleware: Set up job-scoped context when executing job
       #
       # **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).
+      #
+      # **Job lifecycle events**: Emits Events::Rails::Job::Started/Completed/Failed for raw Sidekiq jobs only.
+      # ActiveJob jobs (when Sidekiq is the queue adapter) are handled by RailsInstrumentation (ASN).
       class ServerMiddleware
-        # 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
-          E11y.config.error_handling.fail_on_error = false
-
-          setup_job_context(job)
-          setup_job_buffer
+        include RawSidekiqJob
+        include JobEventEmitter
 
-          # Track job start time for SLO
+        def call(_worker, job, queue)
+          original_fail_on_error = disable_fail_on_error
           start_time = Time.now
           job_status = :success
 
-          # Execute job (business logic)
+          setup_job_context(job, queue)
+          setup_job_buffer
+
+          emit_job_started(job, queue) if raw_sidekiq_job?(job)
           yield
         rescue StandardError => e
           job_status = :failed
-          # Check if this is E11y error (circuit breaker, retry exhausted, etc.)
-          handle_job_error(e)
-
-          raise # Always re-raise original exception
+          on_job_exception(job, queue, start_time, e)
+          raise
         ensure
-          # Track SLO metrics
-          track_job_slo(job, queue, job_status, start_time)
+          finalize_job(job, queue, start_time, job_status, original_fail_on_error)
+        end
 
-          cleanup_job_context
+        private
 
-          # Restore original setting
-          E11y.config.error_handling.fail_on_error = original_fail_on_error
+        def disable_fail_on_error
+          original = E11y.config.error_handling_fail_on_error
+          E11y.config.error_handling_fail_on_error = false
+          original
         end
-        # rubocop:enable Metrics/AbcSize
 
-        private
+        def on_job_exception(job, queue, start_time, error)
+          emit_job_failed(job, queue, start_time, error) if raw_sidekiq_job?(job)
+          handle_job_error(error)
+        end
+
+        def finalize_job(job, queue, start_time, job_status, original_fail_on_error)
+          emit_job_completed(job, queue, start_time) if raw_sidekiq_job?(job) && job_status == :success
+          track_job_slo(job, queue, job_status, start_time)
+          cleanup_job_context
+          E11y.config.error_handling_fail_on_error = original_fail_on_error
+        end
 
         # Setup job-scoped context (C17 Hybrid Tracing)
-        def setup_job_context(job)
+        def setup_job_context(job, queue = nil)
           # Extract parent trace context from job metadata
           parent_trace_id = job["e11y_parent_trace_id"]
 
@@ -91,13 +180,28 @@ module E11y
           E11y::Current.span_id = span_id
           E11y::Current.parent_trace_id = parent_trace_id
           E11y::Current.request_id = job["jid"]
+          E11y::Tracing::Propagator.hydrate_current_from_job_baggage!(job["e11y_baggage"]) if job.key?("e11y_baggage")
+
+          # Restore or compute sampling decision (ADR-005 §7)
+          if job.key?("e11y_sampled")
+            E11y::Current.sampled = job["e11y_sampled"]
+          else
+            require "e11y/trace_context/sampler"
+            ctx = E11y::Current.to_context.merge(
+              job_class: job["class"],
+              queue: queue
+            ).compact
+            E11y::Current.sampled = E11y::TraceContext::Sampler.should_sample?(ctx)
+          end
         end
 
-        # Setup job-scoped buffer
+        # Setup request-scoped buffer (same as HTTP; optional job_buffer_limit)
         def setup_job_buffer
-          return unless E11y.config.request_buffer&.enabled
+          return unless E11y.config.ephemeral_buffer_enabled
 
-          E11y::Buffers::RequestScopedBuffer.initialize!
+          limit = E11y.config.ephemeral_buffer_job_buffer_limit ||
+                  E11y::Buffers::EphemeralBuffer::DEFAULT_BUFFER_LIMIT
+          E11y::Buffers::EphemeralBuffer.initialize!(buffer_limit: limit)
         rescue StandardError => e
           # C18: Don't fail job if buffer setup fails
           warn "[E11y] Failed to start job buffer: #{e.message}"
@@ -106,9 +210,9 @@ module E11y
         # Handle job error (C18: Non-Failing Event Tracking)
         def handle_job_error(_error)
           # Flush buffer on error (includes debug events)
-          return unless E11y.config.request_buffer&.enabled
+          return unless E11y.config.ephemeral_buffer_enabled
 
-          E11y::Buffers::RequestScopedBuffer.flush_on_error
+          E11y::Buffers::EphemeralBuffer.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}"
@@ -117,9 +221,9 @@ module E11y
         # Cleanup job-scoped context
         def cleanup_job_context
           # Discard buffer on success (not on error, already flushed in rescue)
-          if !$ERROR_INFO && E11y.config.request_buffer&.enabled
+          if !$ERROR_INFO && E11y.config.ephemeral_buffer_enabled
             begin
-              E11y::Buffers::RequestScopedBuffer.discard
+              E11y::Buffers::EphemeralBuffer.discard
             rescue StandardError => e
               # C18: Don't fail job if buffer flush fails
               warn "[E11y] Failed to flush job buffer: #{e.message}"
@@ -154,7 +258,7 @@ module E11y
         # @return [void]
         # @api private
         def track_job_slo(job, queue, 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)
 

data/lib/e11y/linters/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module E11y
+  module Linters
+    # Namespace for linter base infrastructure (satisfies Zeitwerk for base.rb).
+    module Base
+    end
+
+    class LinterError < StandardError; end
+  end
+end

data/lib/e11y/linters/pii/pii_declaration_linter.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/registry"
+
+module E11y
+  module Linters
+    module PII
+      # Linter for explicit PII declaration on Event classes.
+      #
+      # When an event declares `contains_pii true`, every schema field must have
+      # an explicit PII strategy in the pii_filtering block.
+      #
+      # @see ADR-006 §3.0.5 PII Declaration Linter
+      # @see UC-007 PII Filtering
+      class PiiDeclarationLinter
+        VALID_STRATEGIES = %i[allow skip mask hash redact partial truncate encrypt].freeze
+
+        class << self
+          # Validate all registered event classes.
+          #
+          # @raise [E11y::Linters::PiiDeclarationError] when any event with contains_pii true has missing/invalid declarations
+          def validate_all!
+            errors = []
+
+            E11y::Registry.event_classes.each do |event_class|
+              validate!(event_class)
+            rescue PiiDeclarationError => e
+              errors << e.message
+            end
+
+            raise PiiDeclarationError, errors.join("\n\n") if errors.any?
+          end
+
+          # Validate a single event class.
+          #
+          # @param event_class [Class] Event class to validate
+          # @raise [E11y::Linters::PiiDeclarationError] when validation fails
+          def validate!(event_class)
+            return unless event_class.contains_pii == true
+
+            schema_fields = extract_schema_keys(event_class)
+            return if schema_fields.nil? || schema_fields.empty?
+
+            pii_config = event_class.pii_filtering_config
+            declared_fields = pii_config&.dig(:fields)&.keys&.map(&:to_s) || []
+
+            missing = schema_fields.map(&:to_s) - declared_fields
+            raise PiiDeclarationError, build_missing_message(event_class, missing) if missing.any?
+
+            # Validate each declared field has valid strategy
+            pii_config[:fields].each do |field, config|
+              validate_field_config!(event_class, field, config)
+            end
+          end
+
+          private
+
+          def extract_schema_keys(klass)
+            return nil unless klass.respond_to?(:compiled_schema)
+
+            schema = klass.compiled_schema
+            return nil unless schema.respond_to?(:key_map)
+
+            schema.key_map.keys.map(&:name)
+          rescue StandardError
+            nil
+          end
+
+          def build_missing_message(event_class, missing_fields)
+            fields_snippet = missing_fields.map do |f|
+              "    field :#{f} do\n      strategy :mask  # or :hash, :allow, :redact\n    end"
+            end.join("\n  ")
+
+            <<~ERROR
+              PII Declaration Error: #{event_class.name}
+
+              Event declared `contains_pii true` but missing field declarations:
+
+              Missing fields: #{missing_fields.map { |x| ":#{x}" }.join(', ')}
+
+              Fix: Add explicit PII strategy for each field in pii_filtering block:
+
+              class #{event_class.name} < E11y::Event::Base
+                contains_pii true
+
+                pii_filtering do
+                  #{fields_snippet}
+                end
+              end
+
+              Available strategies: #{VALID_STRATEGIES.map { |s| ":#{s}" }.join(', ')}
+            ERROR
+          end
+
+          def validate_field_config!(event_class, field, config)
+            strategy = config[:strategy]
+            unless VALID_STRATEGIES.include?(strategy)
+              raise PiiDeclarationError, <<~ERROR
+                Invalid PII strategy for #{event_class.name}##{field}
+
+                Strategy: #{strategy.inspect}
+                Valid strategies: #{VALID_STRATEGIES.map { |s| ":#{s}" }.join(', ')}
+              ERROR
+            end
+
+            return unless config.key?(:exclude_adapters)
+
+            return if config[:exclude_adapters].is_a?(Array)
+
+            raise PiiDeclarationError, "exclude_adapters must be an Array for #{event_class.name}##{field}"
+          end
+        end
+      end
+
+      # Raised when PII declaration validation fails.
+      class PiiDeclarationError < LinterError; end
+    end
+  end
+end

data/lib/e11y/linters/slo/config_consistency_linter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/slo/config_loader"
+
+module E11y
+  module Linters
+    module SLO
+      # Linter for slo.yml custom_slos consistency with Event class definitions.
+      #
+      # Ensures every event referenced in slo.yml custom_slos:
+      # - Exists (constantize succeeds)
+      # - Has slo enabled (slo_enabled?)
+      # - Has contributes_to matching the slo_name in config
+      class ConfigConsistencyLinter
+        class << self
+          # Validate slo.yml custom_slos against Event class definitions.
+          #
+          # @param search_paths [Array<String>, nil] Optional search paths for ConfigLoader.
+          #   When nil, ConfigLoader uses default paths.
+          # @raise [E11y::Linters::LinterError] when any event fails validation
+          def validate!(search_paths: nil)
+            config = if search_paths
+                       E11y::SLO::ConfigLoader.load(search_paths: search_paths)
+                     else
+                       E11y::SLO::ConfigLoader.load
+                     end
+
+            return if config.nil?
+            return if config["custom_slos"].nil? || config["custom_slos"].empty?
+
+            errors = []
+
+            config["custom_slos"].each do |slo|
+              slo_name = slo["name"]
+              events = slo["events"] || []
+
+              events.each do |event_class_name|
+                error = validate_event(slo_name, event_class_name)
+                errors << error if error
+              end
+            end
+
+            return if errors.empty?
+
+            raise LinterError, errors.join("\n")
+          end
+
+          private
+
+          def validate_event(slo_name, event_class_name)
+            event_class = constantize_event(event_class_name)
+            return "Event class '#{event_class_name}' does not exist (constantize failed)" if event_class.nil?
+
+            unless event_class.respond_to?(:slo_enabled?) && event_class.slo_enabled?
+              return "Event #{event_class_name} is referenced in slo.yml (SLO '#{slo_name}') but has slo disabled"
+            end
+
+            contributes_to = event_class.slo_config&.contributes_to_value
+            unless contributes_to == slo_name
+              return "Event #{event_class_name} contributes_to '#{contributes_to}' but slo.yml defines SLO '#{slo_name}'"
+            end
+
+            nil
+          end
+
+          def constantize_event(event_class_name)
+            Object.const_get(event_class_name)
+          rescue NameError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/linters/slo/explicit_declaration_linter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/registry"
+
+module E11y
+  module Linters
+    module SLO
+      # Linter for explicit SLO declaration on Event classes.
+      #
+      # Ensures every registered event class has either `slo do ... end` or
+      # `slo false` — i.e. slo_enabled? or slo_disabled? must be true.
+      class ExplicitDeclarationLinter
+        class << self
+          # Validate all registered event classes have explicit SLO declaration.
+          #
+          # @raise [E11y::Linters::LinterError] when any event has neither slo_enabled? nor slo_disabled?
+          def validate!
+            errors = []
+
+            E11y::Registry.event_classes.each do |event_class|
+              next if event_class.slo_enabled? || event_class.slo_disabled?
+
+              name = event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name
+              errors << "Event #{name} missing explicit SLO declaration! Add `slo do ... end` or `slo false`"
+            end
+
+            return if errors.empty?
+
+            raise LinterError, errors.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/linters/slo/slo_status_from_linter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/registry"
+
+module E11y
+  module Linters
+    module SLO
+      # Linter for SLO-enabled events: requires slo_status_from and contributes_to.
+      #
+      # When an event has slo_enabled?, it must define:
+      # - slo_status_from (slo_config.slo_status_proc) — how to compute slo_status from payload
+      # - contributes_to (slo_config.contributes_to_value) — which custom SLO this event feeds
+      class SloStatusFromLinter
+        class << self
+          # Validate all SLO-enabled event classes have slo_status_from and contributes_to.
+          #
+          # @raise [E11y::Linters::LinterError] when any slo-enabled event is missing either
+          def validate!
+            errors = []
+
+            E11y::Registry.event_classes.each do |event_class|
+              next unless event_class.slo_enabled?
+
+              config = event_class.slo_config
+              name = event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name
+
+              errors << "Event #{name} has slo enabled but missing slo_status_from" unless config&.slo_status_proc
+
+              errors << "Event #{name} has slo enabled but missing contributes_to" unless config&.contributes_to_value
+            end
+
+            return if errors.empty?
+
+            raise LinterError, errors.join("\n")
+          end
+        end
+      end
+    end
+  end
+end