e11y 0.1.0

data/lib/e11y/instruments/active_job.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module E11y
+  module Instruments
+    # ActiveJob integration for job-scoped context and trace propagation.
+    #
+    # Provides callbacks to:
+    # 1. Inject trace context when job is enqueued (before_enqueue)
+    # 2. Set up job-scoped context when job executes (around_perform)
+    #
+    # @example Setup (automatic via Railtie)
+    #   class ApplicationJob < ActiveJob::Base
+    #     include E11y::Instruments::ActiveJob::Callbacks
+    #   end
+    #
+    # @see ADR-008 §10 (ActiveJob Integration)
+    module ActiveJob
+      # Callbacks module to be included into ActiveJob classes.
+      # Provides before_enqueue and around_perform callbacks for trace propagation.
+      module Callbacks
+        extend ActiveSupport::Concern
+
+        included do
+          # Inject trace context before enqueueing (C17 Hybrid Tracing)
+          # Store parent trace context for job to link back to originating request
+          before_enqueue do |job|
+            # Store current trace as parent (job will create NEW trace)
+            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
+          end
+
+          # Set up job-scoped context around job execution (C17 Hybrid Tracing + C18 Non-Failing)
+          around_perform do |job, block|
+            # 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_active_job(job)
+            setup_job_buffer_active_job
+
+            # Track job start time for SLO
+            start_time = Time.now
+            job_status = :success
+
+            # Execute job (business logic)
+            block.call
+          rescue StandardError => e
+            job_status = :failed
+            # Handle error (C18: Non-Failing Event Tracking)
+            handle_job_error_active_job(e)
+
+            raise # Always re-raise original exception
+          ensure
+            # Track SLO metrics
+            track_job_slo_active_job(job, job_status, start_time)
+
+            cleanup_job_context_active_job
+
+            # Restore original setting
+            E11y.config.error_handling.fail_on_error = original_fail_on_error
+          end
+        end
+
+        private
+
+        # Setup job-scoped context (C17 Hybrid Tracing)
+        def setup_job_context_active_job(job)
+          # Extract parent trace context from job metadata
+          parent_trace_id = job.e11y_parent_trace_id
+
+          # Generate NEW trace_id for this job (not reuse parent!)
+          trace_id = generate_trace_id
+          span_id = generate_span_id
+
+          # Set job-scoped context
+          E11y::Current.trace_id = trace_id
+          E11y::Current.span_id = span_id
+          E11y::Current.parent_trace_id = parent_trace_id
+          E11y::Current.request_id = job.job_id
+        end
+
+        # Setup job-scoped buffer
+        def setup_job_buffer_active_job
+          return unless E11y.config.request_buffer&.enabled
+
+          E11y::Buffers::RequestScopedBuffer.start!
+        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_active_job(_error)
+          return unless E11y.config.request_buffer&.enabled
+
+          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}"
+        end
+
+        # Cleanup job-scoped context
+        def cleanup_job_context_active_job
+          # Flush buffer on success (not on error, already flushed in rescue)
+          if !$ERROR_INFO && E11y.config.request_buffer&.enabled
+            begin
+              E11y::Buffers::RequestScopedBuffer.flush!
+            rescue StandardError => e
+              # C18: Don't fail job if buffer flush fails
+              warn "[E11y] Failed to flush job buffer: #{e.message}"
+            end
+          end
+
+          # Reset context (always, even if flush failed)
+          E11y::Current.reset
+        rescue StandardError => e
+          # C18: Absolutely don't fail job on context cleanup
+          warn "[E11y] Failed to reset job context: #{e.message}"
+        end
+
+        # Generate new trace_id (32-character hex)
+        # @return [String]
+        def generate_trace_id
+          SecureRandom.hex(16)
+        end
+
+        # Generate new span_id (16-character hex)
+        # @return [String]
+        def generate_span_id
+          SecureRandom.hex(8)
+        end
+
+        # Track ActiveJob for SLO metrics (if enabled).
+        #
+        # @param job [ActiveJob::Base] Job instance
+        # @param status [Symbol] Job status (:success or :failed)
+        # @param start_time [Time] Job start time
+        # @return [void]
+        # @api private
+        def track_job_slo_active_job(job, status, start_time)
+          return unless E11y.config.slo_tracking&.enabled
+
+          duration_ms = ((Time.now - start_time) * 1000).round(2)
+
+          require "e11y/slo/tracker"
+          E11y::SLO::Tracker.track_background_job(
+            job_class: job.class.name,
+            status: status,
+            duration_ms: duration_ms,
+            queue: job.queue_name
+          )
+        rescue StandardError => e
+          # C18: Don't fail if SLO tracking fails
+          E11y.logger.warn("[E11y] SLO tracking error: #{e.message}", error: e.class.name)
+        end
+      end
+
+      # Custom attribute accessors for trace context (C17 Hybrid Tracing)
+      module TraceAttributes
+        def e11y_parent_trace_id
+          @e11y_parent_trace_id
+        end
+
+        def e11y_parent_trace_id=(value)
+          @e11y_parent_trace_id = value
+        end
+
+        def e11y_parent_span_id
+          @e11y_parent_span_id
+        end
+
+        def e11y_parent_span_id=(value)
+          @e11y_parent_span_id = value
+        end
+
+        # Deprecated: Jobs should create NEW trace_id (C17)
+        # These are kept for backward compatibility but should not be used.
+        def e11y_trace_id
+          @e11y_trace_id
+        end
+
+        def e11y_trace_id=(value)
+          @e11y_trace_id = value
+        end
+
+        def e11y_span_id
+          @e11y_span_id
+        end
+
+        def e11y_span_id=(value)
+          @e11y_span_id = value
+        end
+      end
+    end
+  end
+end
+
+# Extend ActiveJob::Base with trace attributes
+ActiveJob::Base.include(E11y::Instruments::ActiveJob::TraceAttributes) if defined?(ActiveJob::Base)

data/lib/e11y/instruments/rails_instrumentation.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module E11y
+  module Instruments
+    # Rails Instrumentation (ActiveSupport::Notifications → E11y)
+    #
+    # Subscribes to Rails internal events (ActiveSupport::Notifications)
+    # and converts them to E11y events for unified observability.
+    #
+    # **Unidirectional Flow:** ASN → E11y
+    #
+    # @example Basic usage
+    #   # 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
+    #   end
+    #
+    # @see ADR-008 §4.1 (Unidirectional Flow ASN → E11y)
+    # @see UC-016 (Rails Logger Migration)
+    class RailsInstrumentation
+      # Built-in event mappings (ASN pattern → E11y Event class)
+      #
+      # These are defaults that can be overridden via config.event_class_for
+      #
+      # @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"
+      }.freeze
+
+      # Setup Rails instrumentation
+      #
+      # Subscribes to ActiveSupport::Notifications events and converts them to E11y events.
+      #
+      # @return [void]
+      def self.setup!
+        return unless E11y.config.rails_instrumentation&.enabled
+
+        # Subscribe to each configured event pattern
+        event_mapping.each do |asn_pattern, e11y_event_class_name|
+          next if ignored?(asn_pattern)
+
+          subscribe_to_event(asn_pattern, e11y_event_class_name)
+        end
+      end
+
+      # Subscribe to a specific ASN event
+      # @param asn_pattern [String] ActiveSupport::Notifications pattern
+      # @param e11y_event_class_name [String] E11y event class name
+      # @return [void]
+      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
+
+          # Resolve event class (string → constant)
+          e11y_event_class = resolve_event_class(e11y_event_class_name)
+          next unless e11y_event_class
+
+          # Track E11y event with extracted payload
+          e11y_event_class.track(
+            event_name: name,
+            duration: duration,
+            **extract_relevant_payload(payload)
+          )
+        rescue StandardError => e
+          # Don't crash the app if event tracking fails
+          warn "[E11y] Failed to track Rails event #{name}: #{e.message}"
+        end
+      end
+
+      # Get final event mapping (after config overrides)
+      # @return [Hash<String, String>] Event mappings
+      def self.event_mapping
+        @event_mapping ||= begin
+          mapping = DEFAULT_RAILS_EVENT_MAPPING.dup
+
+          # Apply custom mappings from config (Devise-style overrides)
+          custom_mappings = E11y.config.rails_instrumentation&.custom_mappings || {}
+          custom_mappings.each do |pattern, event_class|
+            mapping[pattern] = event_class.name
+          end
+
+          mapping
+        end
+      end
+
+      # Check if event pattern should be ignored
+      # @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.include?(pattern)
+      end
+
+      # Extract relevant payload fields from ASN event
+      #
+      # Filters out PII and noisy fields, keeping only relevant data.
+      #
+      # @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
+        )
+      end
+
+      # Resolve event class from string name
+      # @param class_name [String] Event class name
+      # @return [Class, nil] Event class or nil if not found
+      def self.resolve_event_class(class_name)
+        class_name.constantize
+      rescue NameError => e
+        warn "[E11y] Event class not found: #{class_name} (#{e.message})"
+        nil
+      end
+    end
+  end
+end

data/lib/e11y/instruments/sidekiq.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module E11y
+  module Instruments
+    # Sidekiq integration for job-scoped context and trace propagation.
+    #
+    # Provides two middleware:
+    # 1. ClientMiddleware - Injects trace context when job is enqueued
+    # 2. ServerMiddleware - Sets up job-scoped context when job executes
+    #
+    # @example Setup (automatic via Railtie)
+    #   Sidekiq.configure_server do |config|
+    #     config.server_middleware do |chain|
+    #       chain.add E11y::Instruments::Sidekiq::ServerMiddleware
+    #     end
+    #   end
+    #
+    #   Sidekiq.configure_client do |config|
+    #     config.client_middleware do |chain|
+    #       chain.add E11y::Instruments::Sidekiq::ClientMiddleware
+    #     end
+    #   end
+    #
+    # @see ADR-008 §9 (Sidekiq Integration)
+    module Sidekiq
+      # 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.
+      class ClientMiddleware
+        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
+
+          yield
+        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).
+      class ServerMiddleware
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        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
+
+          # Track job start time for SLO
+          start_time = Time.now
+          job_status = :success
+
+          # Execute job (business logic)
+          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
+        ensure
+          # Track SLO metrics
+          track_job_slo(job, queue, job_status, start_time)
+
+          cleanup_job_context
+
+          # 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
+
+        private
+
+        # Setup job-scoped context (C17 Hybrid Tracing)
+        def setup_job_context(job)
+          # Extract parent trace context from job metadata
+          parent_trace_id = job["e11y_parent_trace_id"]
+
+          # Generate NEW trace_id for this job (not reuse parent!)
+          trace_id = generate_trace_id
+          span_id = generate_span_id
+
+          # Set job-scoped context
+          E11y::Current.trace_id = trace_id
+          E11y::Current.span_id = span_id
+          E11y::Current.parent_trace_id = parent_trace_id
+          E11y::Current.request_id = job["jid"]
+        end
+
+        # Setup job-scoped buffer
+        def setup_job_buffer
+          return unless E11y.config.request_buffer&.enabled
+
+          E11y::Buffers::RequestScopedBuffer.start!
+        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)
+          # Flush buffer on error (includes debug events)
+          return unless E11y.config.request_buffer&.enabled
+
+          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}"
+        end
+
+        # Cleanup job-scoped context
+        def cleanup_job_context
+          # Flush buffer on success (not on error, already flushed in rescue)
+          if !$ERROR_INFO && E11y.config.request_buffer&.enabled
+            begin
+              E11y::Buffers::RequestScopedBuffer.flush!
+            rescue StandardError => e
+              # C18: Don't fail job if buffer flush fails
+              warn "[E11y] Failed to flush job buffer: #{e.message}"
+            end
+          end
+
+          # Reset context (always, even if flush failed)
+          E11y::Current.reset
+        rescue StandardError => e
+          # C18: Absolutely don't fail job on context cleanup
+          warn "[E11y] Failed to reset job context: #{e.message}"
+        end
+
+        # Generate new trace_id (32-character hex)
+        # @return [String]
+        def generate_trace_id
+          SecureRandom.hex(16)
+        end
+
+        # Generate new span_id (16-character hex)
+        # @return [String]
+        def generate_span_id
+          SecureRandom.hex(8)
+        end
+
+        # Track Sidekiq job for SLO metrics (if enabled).
+        #
+        # @param job [Hash] Sidekiq job hash
+        # @param queue [String] Queue name
+        # @param status [Symbol] Job status (:success or :failed)
+        # @param start_time [Time] Job start time
+        # @return [void]
+        # @api private
+        def track_job_slo(job, queue, status, start_time)
+          return unless E11y.config.slo_tracking&.enabled
+
+          duration_ms = ((Time.now - start_time) * 1000).round(2)
+
+          require "e11y/slo/tracker"
+          E11y::SLO::Tracker.track_background_job(
+            job_class: job["class"],
+            status: status,
+            duration_ms: duration_ms,
+            queue: queue
+          )
+        rescue StandardError => e
+          # C18: Don't fail if SLO tracking fails
+          warn "[E11y] SLO tracking error: #{e.message}"
+        end
+      end
+    end
+  end
+end