e11y 0.1.0

data/lib/e11y/slo/event_driven.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "e11y/metrics"
+
+module E11y
+  module SLO
+    # Event-Driven SLO for business logic reliability (ADR-014).
+    #
+    # Provides DSL for Event classes to opt-in to SLO tracking, auto-calculate
+    # `slo_status` from payload, and emit metrics for custom business SLO.
+    #
+    # **Key Features:**
+    # - Explicit opt-in via `slo { enabled true }` in Event class
+    # - Auto-calculation of `slo_status` from payload (e.g., status == 'completed' → 'success')
+    # - Explicit override: `track(status: 'completed', slo_status: 'failure')`
+    # - Metrics export: `event_result_total{slo_status="success|failure"}`
+    # - Custom SLO configuration in `slo.yml` (optional)
+    #
+    # **ADR References:**
+    # - ADR-014 §3 (Event SLO DSL)
+    # - ADR-014 §4 (SLO Status Calculation)
+    # - ADR-014 §6 (Metrics Export)
+    #
+    # **Use Case:** UC-014 (Event-Driven SLO)
+    #
+    # @example Event with SLO enabled
+    #   module Events
+    #     class PaymentProcessed < E11y::Event::Base
+    #       schema do
+    #         required(:payment_id).filled(:string)
+    #         required(:status).filled(:string)
+    #         optional(:slo_status).filled(:string)  # Explicit override
+    #       end
+    #
+    #       slo do
+    #         enabled true
+    #         slo_status_from do |payload|
+    #           return payload[:slo_status] if payload[:slo_status]
+    #           case payload[:status]
+    #           when 'completed' then 'success'
+    #           when 'failed' then 'failure'
+    #           else nil  # Not counted in SLO
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @example Tracking with auto-calculated slo_status
+    #   Events::PaymentProcessed.track(
+    #     payment_id: 'p123',
+    #     status: 'completed'  # → slo_status = 'success'
+    #   )
+    #
+    # @example Tracking with explicit override
+    #   Events::PaymentProcessed.track(
+    #     payment_id: 'p456',
+    #     status: 'completed',
+    #     slo_status: 'failure'  # Explicit override (e.g., fraud detected)
+    #   )
+    #
+    # @see ADR-014 for complete architecture
+    module EventDriven
+      # SLO configuration for an Event class.
+      class SLOConfig
+        attr_reader :slo_status_proc, :contributes_to_value, :group_by_field
+
+        def initialize
+          @enabled = false
+          @slo_status_proc = nil
+          @contributes_to_value = nil
+          @group_by_field = nil
+        end
+
+        # DSL method: Enable or disable SLO tracking.
+        #
+        # @param value [Boolean] true to enable, false to disable
+        def enabled(value = nil)
+          return @enabled if value.nil?
+
+          @enabled = value
+        end
+
+        # Check if SLO is enabled.
+        #
+        # @return [Boolean]
+        def enabled?
+          @enabled
+        end
+
+        # DSL method: Define how to calculate slo_status from payload.
+        #
+        # @yieldparam payload [Hash] Event payload
+        # @yieldreturn [String, nil] 'success', 'failure', or nil (not counted)
+        def slo_status_from(&block)
+          @slo_status_proc = block
+        end
+
+        # DSL method: Define which custom SLO this event contributes to.
+        #
+        # @param slo_name [String] Name of custom SLO (from slo.yml)
+        def contributes_to(slo_name = nil)
+          return @contributes_to_value if slo_name.nil?
+
+          @contributes_to_value = slo_name
+        end
+
+        # DSL method: Group SLO metrics by a specific field.
+        #
+        # @param field [Symbol] Field name to group by (e.g., :payment_method)
+        def group_by(field = nil)
+          return @group_by_field if field.nil?
+
+          @group_by_field = field
+        end
+      end
+
+      # DSL methods for Event classes (extend with this module).
+      module DSL
+        # DSL method: Configure SLO for this Event class.
+        #
+        # @yieldparam config [SLOConfig] SLO configuration object
+        # @return [void]
+        #
+        # @example Enable SLO
+        #   slo do
+        #     enabled true
+        #     slo_status_from { |payload| payload[:status] == 'success' ? 'success' : 'failure' }
+        #   end
+        #
+        # @example Disable SLO (explicit)
+        #   slo do
+        #     enabled false
+        #   end
+        def slo(&)
+          @slo_config ||= SLOConfig.new
+          @slo_config.instance_eval(&) if block_given?
+          @slo_config
+        end
+
+        # Get SLO configuration for this Event class.
+        #
+        # @return [SLOConfig, nil] SLO config or nil if not defined
+        def slo_config
+          @slo_config
+        end
+      end
+    end
+  end
+end

data/lib/e11y/slo/tracker.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "e11y/metrics"
+
+module E11y
+  module SLO
+    # Zero-Config SLO Tracker for HTTP requests and background jobs.
+    #
+    # Automatically tracks Service Level Indicators (SLIs):
+    # - HTTP request success rate (availability)
+    # - HTTP request latency (p95, p99)
+    # - Background job success rate
+    # - Background job duration
+    #
+    # @see UC-004 (Zero-Config SLO Tracking)
+    # @see ADR-003 §3 (Multi-Level SLO Strategy)
+    #
+    # @example Enable SLO tracking
+    #   E11y.configure do |config|
+    #     config.slo_tracking.enabled = true
+    #   end
+    #
+    # @example Track HTTP request
+    #   E11y::SLO::Tracker.track_http_request(
+    #     controller: 'OrdersController',
+    #     action: 'create',
+    #     status: 200,
+    #     duration_ms: 42.5
+    #   )
+    #
+    # @note C11 Resolution (Sampling Correction): Not yet implemented.
+    #   Requires Phase 2.8 (Stratified Sampling) for accurate SLO with sampling.
+    module Tracker
+      class << self
+        # Track HTTP request for SLO metrics.
+        #
+        # @param controller [String] Controller name
+        # @param action [String] Action name
+        # @param status [Integer] HTTP status code
+        # @param duration_ms [Numeric] Request duration in milliseconds
+        # @return [void]
+        def track_http_request(controller:, action:, status:, duration_ms:)
+          return unless enabled?
+
+          labels = {
+            controller: controller,
+            action: action,
+            status: normalize_status(status)
+          }
+
+          # Track request count
+          E11y::Metrics.increment(:slo_http_requests_total, labels)
+
+          # Track request duration
+          E11y::Metrics.histogram(
+            :slo_http_request_duration_seconds,
+            duration_ms / 1000.0,
+            labels.except(:status),
+            buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+          )
+        end
+
+        # Track background job for SLO metrics.
+        #
+        # @param job_class [String] Job class name
+        # @param status [Symbol] Job status (:success or :failed)
+        # @param duration_ms [Numeric] Job duration in milliseconds
+        # @param queue [String, nil] Queue name (optional)
+        # @return [void]
+        def track_background_job(job_class:, status:, duration_ms:, queue: nil)
+          return unless enabled?
+
+          labels = {
+            job_class: job_class,
+            status: status.to_s
+          }
+          labels[:queue] = queue if queue
+
+          # Track job count
+          E11y::Metrics.increment(:slo_background_jobs_total, labels)
+
+          # Track job duration (only for successful jobs)
+          return unless status == :success
+
+          E11y::Metrics.histogram(
+            :slo_background_job_duration_seconds,
+            duration_ms / 1000.0,
+            labels.except(:status),
+            buckets: [0.1, 0.5, 1, 5, 10, 30, 60, 300, 600]
+          )
+        end
+
+        # Check if SLO tracking is enabled.
+        #
+        # @return [Boolean] true if enabled
+        def enabled?
+          E11y.config.respond_to?(:slo_tracking) && E11y.config.slo_tracking&.enabled
+        end
+
+        # Normalize HTTP status code to category (2xx, 3xx, 4xx, 5xx).
+        #
+        # @param status [Integer] HTTP status code
+        # @return [String] Status category
+        # @api private
+        def normalize_status(status)
+          case status
+          when 200..299 then "2xx"
+          when 300..399 then "3xx"
+          when 400..499 then "4xx"
+          when 500..599 then "5xx"
+          else "unknown"
+          end
+        end
+
+        private :normalize_status
+      end
+    end
+  end
+end

data/lib/e11y/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module E11y
+  # Semantic versioning: MAJOR.MINOR.PATCH
+  # - MAJOR: Breaking changes (incompatible API changes)
+  # - MINOR: New features (backwards-compatible)
+  # - PATCH: Bug fixes (backwards-compatible)
+  VERSION = "0.1.0"
+end

data/lib/e11y.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+# Zeitwerk autoloader setup
+loader = Zeitwerk::Loader.for_gem
+# Configure inflector for acronyms
+loader.inflector.inflect(
+  "pii" => "PII",
+  "pii_filter" => "PIIFilter"
+)
+loader.setup
+
+# E11y - Event-Driven Observability for Ruby on Rails
+#
+# @example Basic usage
+#   E11y.configure do |config|
+#     config.adapters = [:loki, :sentry]
+#   end
+#
+#   E11y.track(Events::UserSignup.new(user_id: 123))
+#
+# @see https://e11y.dev Documentation
+module E11y
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class ZoneViolationError < Error; end
+  class InvalidPipelineError < Error; end
+
+  class << self
+    # Configure E11y
+    #
+    # @yield [Configuration] configuration object
+    # @return [void]
+    #
+    # @example
+    #   E11y.configure do |config|
+    #     config.adapters = [:loki, :stdout]
+    #     config.log_level = :debug
+    #   end
+    def configure
+      yield configuration if block_given?
+    end
+
+    # Get current configuration
+    #
+    # @return [Configuration] current configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias config configuration
+
+    # Track an event
+    #
+    # @param event [Event] event instance to track
+    # @return [void]
+    #
+    # @example
+    #   E11y.track(Events::UserSignup.new(user_id: 123))
+    def track(event)
+      # TODO: Implement in Phase 1
+      raise NotImplementedError, "E11y.track will be implemented in Phase 1"
+    end
+
+    # Get logger instance
+    #
+    # @return [Logger] logger instance
+    def logger
+      require "logger"
+      @logger ||= ::Logger.new($stdout)
+    end
+
+    # Reset configuration (primarily for testing)
+    #
+    # @return [void]
+    # @api private
+    def reset!
+      @configuration = nil
+      @logger = nil
+    end
+  end
+
+  # 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|
+  #     # Register adapter instances
+  #     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, :enabled, :environment, :service_name
+    attr_reader :adapter_mapping, :pipeline, :rails_instrumentation, :logger_bridge, :request_buffer, :error_handling,
+                :dlq_storage, :dlq_filter, :rate_limiting, :slo_tracking
+
+    def initialize
+      @adapters = {} # Hash of adapter_name => adapter_instance
+      @log_level = :info
+      @adapter_mapping = default_adapter_mapping
+      @pipeline = E11y::Pipeline::Builder.new
+      @enabled = true
+      @environment = nil
+      @service_name = nil
+      @rails_instrumentation = RailsInstrumentationConfig.new
+      @logger_bridge = LoggerBridgeConfig.new
+      @request_buffer = RequestBufferConfig.new
+      @error_handling = ErrorHandlingConfig.new # ✅ C18 Resolution
+      @dlq_storage = nil # Set by user (e.g., DLQ::FileStorage instance)
+      @dlq_filter = nil # Set by user (e.g., DLQ::Filter instance)
+      @rate_limiting = RateLimitingConfig.new
+      @slo_tracking = SLOTrackingConfig.new # ✅ L3.14.1
+      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
+
+    private
+
+    # Default adapter mapping (convention-based)
+    #
+    # Adapter names represent PURPOSE, not implementation:
+    # - :logs → centralized logging (implementation: Loki, Elasticsearch, CloudWatch, etc.)
+    # - :errors_tracker → error tracking with alerting (implementation: Sentry, Rollbar, Bugsnag, etc.)
+    #
+    # @return [Hash{Symbol => Array<Symbol>}] Default mapping (severity => adapter names)
+    def default_adapter_mapping
+      {
+        error: %i[logs errors_tracker],  # Errors: both logging + alerting
+        fatal: %i[logs errors_tracker],  # Fatal: both logging + alerting
+        default: [:logs]                 # Others: logging only
+      }
+    end
+
+    # Setup default middleware pipeline
+    #
+    # Default pipeline order (per ADR-015):
+    # 1. TraceContext - Add trace_id, span_id, timestamp (zone: :pre_processing)
+    # 2. Validation - Schema validation (zone: :pre_processing)
+    # 3. PIIFilter - PII filtering (zone: :security)
+    # 4. AuditSigning - Audit event signing (zone: :security)
+    # 5. Sampling - Adaptive sampling (zone: :routing)
+    # 6. Routing - Buffer routing (zone: :adapters)
+    #
+    # @return [void]
+    # @see ADR-015 Middleware Execution Order
+    def configure_default_pipeline
+      # Zone: :pre_processing
+      @pipeline.use E11y::Middleware::TraceContext
+      @pipeline.use E11y::Middleware::Validation
+
+      # Zone: :security
+      @pipeline.use E11y::Middleware::PIIFilter
+      @pipeline.use E11y::Middleware::AuditSigning
+
+      # Zone: :routing
+      @pipeline.use E11y::Middleware::Sampling
+
+      # Zone: :adapters
+      @pipeline.use E11y::Middleware::Routing
+    end
+  end
+
+  # Rails Instrumentation configuration
+  class RailsInstrumentationConfig
+    attr_accessor :enabled, :custom_mappings, :ignore_events
+
+    def initialize
+      @enabled = false # Disabled by default, enabled by Railtie
+      @custom_mappings = {}
+      @ignore_events = []
+    end
+
+    # Override event class for specific ASN pattern (Devise-style)
+    # @param pattern [String] ActiveSupport::Notifications pattern
+    # @param event_class [Class] E11y event class
+    # @return [void]
+    def event_class_for(pattern, event_class)
+      @custom_mappings[pattern] = event_class
+    end
+
+    # Ignore specific ASN event
+    # @param pattern [String] ActiveSupport::Notifications pattern
+    # @return [void]
+    def ignore_event(pattern)
+      @ignore_events << pattern
+    end
+  end
+
+  # Logger Bridge configuration
+  class LoggerBridgeConfig
+    attr_accessor :enabled, :dual_logging
+
+    def initialize
+      @enabled = false # Opt-in
+      @dual_logging = true # Keep writing to original Rails.logger
+    end
+  end
+
+  # Request Buffer configuration
+  class RequestBufferConfig
+    attr_accessor :enabled
+
+    def initialize
+      @enabled = false # Disabled by default
+    end
+  end
+
+  # Error Handling configuration (C18 Resolution)
+  #
+  # Controls whether event tracking failures should raise exceptions.
+  # Default: true (for web requests - fast feedback)
+  # Exception: false (for background jobs - don't fail business logic)
+  #
+  # @see ADR-013 §3.6 (Event Tracking in Background Jobs)
+  class ErrorHandlingConfig
+    attr_accessor :fail_on_error
+
+    def initialize
+      @fail_on_error = true # Default: raise errors (fast feedback for web requests)
+    end
+  end
+
+  # Rate Limiting configuration (UC-011, C02 Resolution)
+  #
+  # Protects adapters from event floods using token bucket algorithm.
+  #
+  # @see UC-011 (Rate Limiting - DoS Protection)
+  # @see ADR-013 §4.6 (C02 Resolution)
+  class RateLimitingConfig
+    attr_accessor :enabled, :global_limit, :per_event_limit, :window
+
+    def initialize
+      @enabled = false # Opt-in (enable explicitly)
+      @global_limit = 10_000 # Max 10K events/sec globally
+      @per_event_limit = 1_000 # Max 1K events/sec per event type
+      @window = 1.0 # 1 second window
+    end
+  end
+
+  # SLO Tracking configuration (UC-004, ADR-003)
+  #
+  # Zero-config SLO tracking for HTTP requests and background jobs.
+  # Automatically emits SLO metrics (availability, latency, success rate).
+  #
+  # @see UC-004 (Zero-Config SLO Tracking)
+  # @see ADR-003 (SLO & Observability)
+  #
+  # @note C11 Resolution (Sampling Correction): Requires Phase 2.8 (Stratified Sampling).
+  #   Without stratified sampling, SLO metrics may be inaccurate when adaptive sampling is enabled.
+  class SLOTrackingConfig
+    attr_accessor :enabled
+
+    def initialize
+      @enabled = false # Opt-in (enable explicitly)
+    end
+  end
+end
+
+# Load Railtie if Rails is present
+require "e11y/railtie" if defined?(Rails::Railtie)
+
+# Eager load for production (optional - uncomment if needed)
+# loader.eager_load if ENV["RAILS_ENV"] == "production"