e11y 0.1.0 → 0.2.0

data/lib/e11y/reliability/dlq/file_storage.rb

@@ -18,6 +18,8 @@ module E11y
       #
       # @see ADR-013 §4 (Dead Letter Queue)
       # @see UC-021 §3 (DLQ File Storage)
+      # rubocop:disable Metrics/ClassLength
+      # DLQ file storage is a cohesive unit handling event persistence, rotation, and querying
       class FileStorage
         # @param file_path [String] Path to DLQ file (default: log/e11y_dlq.jsonl)
         # @param max_file_size_mb [Integer] Maximum file size in MB before rotation (default: 100)
@@ -36,6 +38,8 @@ module E11y
         # @param event_data [Hash] Event data
         # @param metadata [Hash] Failure metadata (error, retry_count, adapter, etc.)
         # @return [String] Event ID (UUID)
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # DLQ save requires building entry, writing, rotation, cleanup, and metrics
         def save(event_data, metadata: {})
           event_id = SecureRandom.uuid
           timestamp = Time.now.utc
@@ -61,6 +65,7 @@ module E11y
 
           event_id
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
         # List DLQ entries with optional filters.
         #
@@ -68,6 +73,8 @@ module E11y
         # @param offset [Integer] Number of entries to skip
         # @param filters [Hash] Filter options (event_name, after, before)
         # @return [Array<Hash>] Array of DLQ entries
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # DLQ listing requires file iteration, pagination, multiple filters, and error handling
         def list(limit: 100, offset: 0, filters: {})
           entries = []
 
@@ -93,10 +100,13 @@ module E11y
           increment_metric("e11y.dlq.parse_error", error: e.class.name)
           entries
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         # Get DLQ statistics.
         #
         # @return [Hash] Statistics (total_entries, file_size_mb, oldest_entry, newest_entry)
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # DLQ stats requires reading file size, counting entries, extracting timestamps, and error handling
         def stats
           return default_stats unless File.exist?(@file_path)
 
@@ -124,6 +134,7 @@ module E11y
           increment_metric("e11y.dlq.stats_error", error: e.class.name)
           default_stats
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
         # Replay single event from DLQ.
         #
@@ -171,22 +182,21 @@ module E11y
         #
         # @param event_id [String] Event ID to delete
         # @return [Boolean] true if deleted
+        # rubocop:disable Naming/PredicateMethod
+        # delete is an action method returning boolean status, not a predicate query
         def delete(_event_id)
           # TODO: Implement deletion (requires rewriting file)
           # For JSONL, deletion is expensive (requires full file rewrite)
           # Consider marking as deleted instead or using database
           false
         end
+        # rubocop:enable Naming/PredicateMethod
 
         private
 
         # Get default file path (log/e11y_dlq.jsonl).
         def default_file_path
-          if defined?(Rails) && Rails.root
-            Rails.root.join("log", "e11y_dlq.jsonl").to_s
-          else
-            File.join("log", "e11y_dlq.jsonl")
-          end
+          ::Rails.root.join("log", "e11y_dlq.jsonl").to_s
         end
 
         # Ensure log directory exists.
@@ -272,6 +282,7 @@ module E11y
           # E11y::Metrics.increment(metric_name, tags)
         end
       end
+      # rubocop:enable Metrics/ClassLength
     end
   end
 end

data/lib/e11y/reliability/dlq/filter.rb

@@ -48,6 +48,8 @@ module E11y
         #
         # @param event_data [Hash] Event data
         # @return [Boolean] true if event should be saved to DLQ
+        # rubocop:disable Metrics/MethodLength
+        # DLQ filter requires 4-priority decision tree with metrics tracking for each branch
         def should_save?(event_data)
           event_name = event_data[:event_name].to_s
           severity = event_data[:severity]
@@ -79,6 +81,7 @@ module E11y
             false
           end
         end
+        # rubocop:enable Metrics/MethodLength
 
         # Get filter statistics.
         #

data/lib/e11y/reliability/retry_handler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require "timeout"
 
 module E11y
   module Reliability
@@ -64,6 +65,8 @@ module E11y
       # @yield Block to execute (adapter send)
       # @return [Object] Result of block execution
       # @raise [RetryExhaustedError] if all retries fail and fail_on_error is true
+      # rubocop:disable Metrics/MethodLength
+      # Retry logic requires error handling, retriability check, backoff calculation, and callbacks
       def with_retry(adapter:, event:)
         attempt = 0
 
@@ -100,6 +103,7 @@ module E11y
           end
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       private
 

data/lib/e11y/sampling/error_spike_detector.rb

@@ -29,6 +29,8 @@ module E11y
     #   end
     #
     #   detector.record_event(event_name: "payment.processed", severity: :error)
+    # rubocop:disable Metrics/ClassLength
+    # Error spike detector is a cohesive sliding window algorithm with state management
     class ErrorSpikeDetector
       # Default configuration
       DEFAULT_WINDOW = 60              # 60 seconds sliding window
@@ -64,6 +66,8 @@ module E11y
       # Check if currently in error spike state
       #
       # @return [Boolean] true if error spike detected
+      # rubocop:disable Metrics/MethodLength
+      # Error spike detection requires checking active spike, expiration, and new spike detection
       def error_spike?
         @mutex.synchronize do
           # Check if spike is still active (within spike_duration)
@@ -90,6 +94,7 @@ module E11y
           false
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Record an event for error rate tracking
       #
@@ -107,8 +112,9 @@ module E11y
           @error_events[event_name] << now
           @all_errors << now
 
-          # Cleanup old events (outside window)
-          cleanup_old_events(now)
+          # Cleanup old events periodically (every 50 errors) instead of on every error
+          # This reduces O(n²) overhead significantly while keeping memory bounded
+          cleanup_old_events(now) if (@all_errors.size % 50).zero?
 
           # Update baseline (if not in spike)
           update_baseline(event_name) unless @spike_started_at
@@ -122,10 +128,12 @@ module E11y
       def current_error_rate(event_name = nil)
         @mutex.synchronize do
           now = Time.now
-          cleanup_old_events(now)
+          cutoff = now - @window
 
           events = event_name ? @error_events[event_name] : @all_errors
-          count = events.count { |ts| (now - ts) <= @window }
+          # Count events within window without cleanup
+          # Cleanup is handled periodically in record_event
+          count = events.count { |ts| ts >= cutoff }
 
           # Convert to per-minute rate
           (count.to_f / @window) * 60
@@ -186,8 +194,10 @@ module E11y
       # @return [Float] Errors per minute
       def current_error_rate_unsafe(event_name = nil)
         now = Time.now
+        cutoff = now - @window
         events = event_name ? @error_events[event_name] : @all_errors
-        count = events.count { |ts| (now - ts) <= @window }
+        # Count within window without cleanup
+        count = events.count { |ts| ts >= cutoff }
         (count.to_f / @window) * 60
       end
 
@@ -221,5 +231,6 @@ module E11y
         @all_errors.reject! { |ts| ts < cutoff }
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/sampling/load_monitor.rb

@@ -65,8 +65,9 @@ module E11y
           now = Time.now
           @events << now
 
-          # Cleanup old events (outside window)
-          cleanup_old_events(now)
+          # Cleanup old events periodically (every 100 events) instead of on every event
+          # This reduces O(n²) overhead significantly while keeping memory bounded
+          cleanup_old_events(now) if (@events.size % 100).zero?
         end
       end
 
@@ -76,9 +77,11 @@ module E11y
       def current_rate
         @mutex.synchronize do
           now = Time.now
-          cleanup_old_events(now)
+          cutoff = now - @window
 
-          count = @events.count { |ts| (now - ts) <= @window }
+          # Count events within window without cleanup
+          # Cleanup is handled periodically in record_event
+          count = @events.count { |ts| ts >= cutoff }
           count.to_f / @window
         end
       end
@@ -90,6 +93,8 @@ module E11y
         rate = current_rate
 
         # Check thresholds in descending order
+        # rubocop:disable Lint/DuplicateBranch
+        # Values between normal and high thresholds intentionally mapped to :high
         if rate >= @thresholds[:overload]
           :overload
         elsif rate >= @thresholds[:very_high]
@@ -101,11 +106,14 @@ module E11y
         else
           :normal
         end
+        # rubocop:enable Lint/DuplicateBranch
       end
 
       # Get recommended sample rate for current load
       #
       # @return [Float] Sample rate (0.0-1.0)
+      # rubocop:disable Style/HashLikeCase
+      # Case/when more readable for load level mapping with inline comments
       def recommended_sample_rate
         case load_level
         when :normal
@@ -118,6 +126,7 @@ module E11y
           0.01  # 1% sampling
         end
       end
+      # rubocop:enable Style/HashLikeCase
 
       # Check if system is overloaded
       #

data/lib/e11y/self_monitoring/reliability_monitor.rb

@@ -131,6 +131,8 @@ module E11y
       # @param state [String] Circuit state
       # @return [Integer] Numeric representation (0=closed, 1=half_open, 2=open)
       # @api private
+      # rubocop:disable Lint/DuplicateBranch
+      # Unknown states intentionally fallback to closed (0), same as "closed"
       def self.state_to_value(state)
         case state
         when "closed" then 0
@@ -139,6 +141,7 @@ module E11y
         else 0
         end
       end
+      # rubocop:enable Lint/DuplicateBranch
 
       private_class_method :state_to_value
     end

data/lib/e11y/version.rb

@@ -5,5 +5,5 @@ module E11y
   # - MAJOR: Breaking changes (incompatible API changes)
   # - MINOR: New features (backwards-compatible)
   # - PATCH: Bug fixes (backwards-compatible)
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/e11y.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
+require "active_support/core_ext/numeric/time" # For 30.days, 7.years, etc.
 
 # Zeitwerk autoloader setup
 loader = Zeitwerk::Loader.for_gem
 # Configure inflector for acronyms
 loader.inflector.inflect(
   "pii" => "PII",
-  "pii_filter" => "PIIFilter"
+  "pii_filter" => "PIIFilter",
+  "otel_logs" => "OTelLogs",
+  "slo" => "SLO",
+  "dlq" => "DLQ"
 )
+# Don't autoload railtie - it will be required manually when Rails is available
+loader.do_not_eager_load("#{__dir__}/e11y/railtie.rb")
 loader.setup
 
 # E11y - Event-Driven Observability for Ruby on Rails
@@ -103,29 +109,51 @@ module E11y
   #     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
+    attr_accessor :adapters, :log_level, :enabled, :environment, :service_name, :default_retention_period,
+                  :routing_rules, :fallback_adapters
+    attr_reader :adapter_mapping, :pipeline, :rails_instrumentation, :logger_bridge, :request_buffer, :active_job,
+                :sidekiq, :error_handling, :dlq_storage, :dlq_filter, :rate_limiting, :slo_tracking
 
     def initialize
+      initialize_basic_config
+      initialize_routing_config
+      initialize_feature_configs
+      configure_default_pipeline
+    end
+
+    private
+
+    def initialize_basic_config
       @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
+    end
+
+    def initialize_routing_config
+      @adapter_mapping = default_adapter_mapping
+      @default_retention_period = 30.days # Default: 30 days retention
+      @routing_rules = [] # Array of lambdas for retention-based routing
+      @fallback_adapters = [:stdout] # Fallback if no routing rule matches
+    end
+
+    def initialize_feature_configs
       @rails_instrumentation = RailsInstrumentationConfig.new
       @logger_bridge = LoggerBridgeConfig.new
       @request_buffer = RequestBufferConfig.new
+      @active_job = ActiveJobConfig.new
+      @sidekiq = SidekiqConfig.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
 
+    public
+
     # Get adapters for given severity
     #
     # @param severity [Symbol] Severity level
@@ -134,6 +162,13 @@ module E11y
       @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
+
     private
 
     # Default adapter mapping (convention-based)
@@ -207,12 +242,22 @@ module E11y
   end
 
   # Logger Bridge configuration
+  #
+  # Controls Rails.logger integration:
+  # - When enabled = true: wraps Rails.logger and sends logs to E11y
+  # - When enabled = false: no integration (default)
+  #
+  # @example Enable logger bridge
+  #   E11y.configure do |config|
+  #     config.logger_bridge.enabled = true  # Wrap Rails.logger + send to E11y
+  #   end
+  #
+  # @see lib/e11y/logger/bridge.rb
   class LoggerBridgeConfig
-    attr_accessor :enabled, :dual_logging
+    attr_accessor :enabled
 
     def initialize
-      @enabled = false # Opt-in
-      @dual_logging = true # Keep writing to original Rails.logger
+      @enabled = false # Opt-in: disabled by default
     end
   end
 
@@ -225,6 +270,38 @@ module E11y
     end
   end
 
+  # ActiveJob configuration
+  #
+  # Controls ActiveJob integration (callbacks for event tracking).
+  # When enabled, E11y will automatically track job lifecycle events:
+  # - job.enqueued
+  # - job.started
+  # - job.completed
+  # - job.failed
+  #
+  # @see lib/e11y/instruments/active_job.rb
+  class ActiveJobConfig
+    attr_accessor :enabled
+
+    def initialize
+      @enabled = false # Disabled by default, enabled by Railtie
+    end
+  end
+
+  # Sidekiq configuration
+  #
+  # Controls Sidekiq middleware integration for trace propagation and context setup.
+  # Automatically enabled by Railtie when Sidekiq is detected.
+  #
+  # @see ADR-008 §9 (Sidekiq Integration)
+  class SidekiqConfig
+    attr_accessor :enabled
+
+    def initialize
+      @enabled = false # Disabled by default, enabled by Railtie when Sidekiq is present
+    end
+  end
+
   # Error Handling configuration (C18 Resolution)
   #
   # Controls whether event tracking failures should raise exceptions.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: e11y
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Artur Seletskiy
@@ -9,20 +9,6 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -80,19 +80,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.6'
 - !ruby/object:Gem::Dependency
-  name: rack
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: memory_profiler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.4
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -247,21 +275,32 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.15'
-description: "E11y (Easy Telemetry) - production-ready observability gem for Ruby
-  on Rails applications.\n\nKEY FEATURES:\n• \U0001F4CA Zero-Config SLO Tracking -
-  automatic Service Level Objectives for HTTP endpoints and background jobs\n• \U0001F3AF
-  Request-Scoped Debug Buffering - buffer debug logs in memory, flush only on errors
-  (reduce log noise by 90%)\n• \U0001F4C8 Pattern-Based Metrics - auto-generate Prometheus/Yabeda
-  metrics from business events\n• \U0001F512 GDPR/SOC2 Compliance - built-in PII filtering
-  and audit trails\n• \U0001F50C Pluggable Adapters - send events to Loki, Sentry,
-  OpenTelemetry, Elasticsearch, or custom backends\n• \U0001F680 High Performance
-  - zero-allocation event tracking, lock-free ring buffers, adaptive memory limits\n•
-  \U0001F9F5 Thread-Safe - designed for multi-threaded Rails apps and Sidekiq workers\n•
-  \U0001F3AD Multi-Tenant Ready - trace context propagation across services with OpenTelemetry
-  integration\n• \U0001F4DD Type-Safe Events - declarative event schemas with dry-schema
-  validation\n• ⚡ Rate Limiting & Sampling - protect production from metric storms
-  and cost overruns\n\nPerfect for SuperApp architectures, microservices, and high-scale
-  Rails applications.\nBattle-tested patterns from Devise, Sidekiq, Sentry, and Yabeda.\n"
+description: |
+  E11y (Easy Telemetry) - Observability for Rails developers who hate noise.
+
+  UNIQUE FEATURES:
+  • Request-scoped debug buffering - buffers debug logs in memory, flushes ONLY on errors
+  • Zero-config SLO tracking - automatic Service Level Objectives for HTTP endpoints and jobs
+  • Schema-validated events - catch bugs before production with dry-schema
+
+  DEVELOPER EXPERIENCE:
+  • 5-minute setup (not 2-week migration)
+  • Auto-metrics from events (no manual Yabeda.increment)
+  • Rails-first design (follows Rails conventions)
+  • Pluggable adapters (Loki, Sentry, OpenTelemetry, custom backends)
+
+  COST SAVINGS:
+  • Reduce log storage costs by 90% (request-scoped buffering)
+  • Replace expensive APM SaaS ($500-5k/month → infra costs only)
+  • Own your observability data (no vendor lock-in)
+
+  PRODUCTION-READY:
+  • Thread-safe for multi-threaded Rails + Sidekiq
+  • Adaptive sampling (error-based, load-based, value-based)
+  • PII filtering (GDPR-compliant masking/hashing)
+  • Performance optimized (hash-based events, minimal allocations)
+
+  Perfect for Rails 7.0+ teams who need observability without complexity or high costs.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -272,7 +311,13 @@ files:
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
+- RELEASE.md
 - Rakefile
+- benchmarks/OPTIMIZATION.md
+- benchmarks/README.md
+- benchmarks/allocation_profiling.rb
+- benchmarks/e11y_benchmarks.rb
+- benchmarks/ruby_baseline_allocations.rb
 - benchmarks/run_all.rb
 - config/README.md
 - config/loki-local-config.yaml
@@ -296,8 +341,11 @@ files:
 - docs/ADR-014-event-driven-slo.md
 - docs/ADR-015-middleware-order.md
 - docs/ADR-016-self-monitoring-slo.md
+- docs/ADR-017-multi-rails-compatibility.md
+- docs/ADR-INDEX.md
 - docs/API-REFERENCE-L28.md
 - docs/COMPREHENSIVE-CONFIGURATION.md
+- docs/CONTRIBUTING.md
 - docs/IMPLEMENTATION_NOTES.md
 - docs/IMPLEMENTATION_PLAN.md
 - docs/IMPLEMENTATION_PLAN_ARCHITECTURE.md
@@ -328,7 +376,7 @@ files:
 - docs/use_cases/UC-016-rails-logger-migration.md
 - docs/use_cases/UC-017-local-development.md
 - docs/use_cases/UC-018-testing-events.md
-- docs/use_cases/UC-019-tiered-storage-migration.md
+- docs/use_cases/UC-019-retention-based-routing.md
 - docs/use_cases/UC-020-event-versioning.md
 - docs/use_cases/UC-021-error-handling-retry-dlq.md
 - docs/use_cases/UC-022-event-registry.md
@@ -387,12 +435,10 @@ files:
 - lib/e11y/middleware/base.rb
 - lib/e11y/middleware/event_slo.rb
 - lib/e11y/middleware/pii_filter.rb
-- lib/e11y/middleware/pii_filtering.rb
 - lib/e11y/middleware/rate_limiting.rb
 - lib/e11y/middleware/request.rb
 - lib/e11y/middleware/routing.rb
 - lib/e11y/middleware/sampling.rb
-- lib/e11y/middleware/slo.rb
 - lib/e11y/middleware/trace_context.rb
 - lib/e11y/middleware/validation.rb
 - lib/e11y/middleware/versioning.rb
@@ -447,6 +493,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.2
 specification_version: 4
-summary: 'E11y - Easy Telemetry: Production-grade observability for Rails with zero-config
-  SLO tracking'
+summary: 'E11y - Easy Telemetry: Observability for Rails developers who hate noise'
 test_files: []