e11y 0.2.0 → 1.0.0

data/lib/e11y.rb

@@ -7,14 +7,27 @@ require "active_support/core_ext/numeric/time" # For 30.days, 7.years, etc.
 loader = Zeitwerk::Loader.for_gem
 # Configure inflector for acronyms
 loader.inflector.inflect(
+  "documentation" => "Documentation",
+  "debug" => "Debug",
+  "opentelemetry_collector" => "OpenTelemetryCollector",
+  "otel_span" => "OtelSpan",
   "pii" => "PII",
   "pii_filter" => "PIIFilter",
   "otel_logs" => "OTelLogs",
   "slo" => "SLO",
-  "dlq" => "DLQ"
+  "dlq" => "DLQ",
+  "net_http_patch" => "NetHTTPPatch",
+  "rspec_matchers" => "RSpecMatchers",
+  "have_tracked_event_matcher" => "HaveTrackedEventMatcher",
+  "snapshot_matcher" => "SnapshotMatcher"
 )
 # Don't autoload railtie - it will be required manually when Rails is available
 loader.do_not_eager_load("#{__dir__}/e11y/railtie.rb")
+# Generators live under lib/generators/ — not part of the autoloaded tree
+loader.ignore("#{__dir__}/generators")
+# Optional HTTP tracing files require external gems (faraday, net/http) — loaded on demand only
+loader.ignore("#{__dir__}/e11y/tracing/faraday_middleware.rb")
+loader.ignore("#{__dir__}/e11y/tracing/net_http_patch.rb")
 loader.setup
 
 # E11y - Event-Driven Observability for Ruby on Rails
@@ -24,8 +37,6 @@ loader.setup
 #     config.adapters = [:loki, :sentry]
 #   end
 #
-#   E11y.track(Events::UserSignup.new(user_id: 123))
-#
 # @see https://e11y.dev Documentation
 module E11y
   class Error < StandardError; end
@@ -33,6 +44,9 @@ module E11y
   class ZoneViolationError < Error; end
   class InvalidPipelineError < Error; end
 
+  # Raised when PII key is blocked in baggage (ADR-006 §5.5). Used by BaggageProtection and E11y::Current.add_baggage.
+  class BaggagePiiError < Error; end
+
   class << self
     # Configure E11y
     #
@@ -56,301 +70,163 @@ module E11y
     end
     alias config configuration
 
-    # Track an event
+    # Test adapter for specs (InMemoryTest in unit tests, InMemory in integration).
+    # Returns :test adapter (unit tests) or :memory adapter (integration tests from dummy config).
     #
-    # @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"
+    # @return [E11y::Adapters::InMemory, E11y::Adapters::InMemoryTest, nil]
+    def test_adapter
+      configuration.adapters[:test] || configuration.adapters[:memory]
     end
 
-    # Get logger instance
+    # Trace an event through the pipeline (debug utility).
+    # Delegates to PipelineInspector.trace_event. Loads the inspector on demand.
     #
-    # @return [Logger] logger instance
-    def logger
-      require "logger"
-      @logger ||= ::Logger.new($stdout)
+    # @param event_class [Class] event class (e.g., Events::OrderCreated)
+    # @param payload [Hash] keyword arguments for the event payload
+    # @return [Hash] event_data after pipeline
+    #
+    # @example
+    #   E11y.trace(Events::OrderCreated, order_id: "123", amount: 99.99)
+    def trace(event_class, **payload)
+      require "e11y/debug/pipeline_inspector"
+      E11y::Debug::PipelineInspector.trace_event(event_class, **payload)
     end
 
-    # Reset configuration (primarily for testing)
+    # Track an event
+    #
+    # Accepts either an event instance or an event class with an optional payload.
+    # Delegates to the event class's `.track` method.
     #
+    # @param event_or_class [E11y::Event::Base, Class] event instance or event class
+    # @param payload [Hash] keyword arguments forwarded to EventClass.track (used with class form)
     # @return [void]
-    # @api private
-    def reset!
-      @configuration = nil
-      @logger = nil
+    #
+    # @example Pass an event instance
+    #   E11y.track(Events::UserSignup.new)
+    #
+    # @example Pass an event class with payload
+    #   E11y.track(Events::UserSignup, user_id: 123)
+    def track(event_or_class, **payload)
+      event_class = event_or_class.is_a?(Class) ? event_or_class : event_or_class.class
+      event_class.track(**payload)
     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, :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
+    # Get logger instance.
+    # Priority: config.logger > Rails.logger (when in Rails) > $stdout.
+    # Set config.logger = Logger.new(nil) in tests to suppress output.
+    #
+    # @return [Logger] logger instance
+    def logger
+      return configuration.logger if configuration&.logger
 
-    private
+      return @logger if defined?(@logger) && !@logger.nil?
 
-    def initialize_basic_config
-      @adapters = {} # Hash of adapter_name => adapter_instance
-      @log_level = :info
-      @pipeline = E11y::Pipeline::Builder.new
-      @enabled = true
-      @environment = nil
-      @service_name = nil
+      require "logger"
+      @logger = if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+                  Rails.logger
+                else
+                  ::Logger.new($stdout)
+                end
     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
+    # Initialize E11y and all configured adapters.
+    # Call after the configure block at application startup.
+    #
+    # @return [void]
+    def start!
+      return unless configuration.enabled
 
-    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
+      configuration.adapters.each_value do |adapter|
+        adapter.start! if adapter.respond_to?(:start!)
+      end
+      logger.info("[E11y] Started (#{configuration.adapters.size} adapters)")
     end
 
-    public
-
-    # Get adapters for given severity
+    # Gracefully shut down E11y, flushing pending events.
     #
-    # @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] || []
+    # @param timeout [Integer] Seconds to wait for each adapter flush (default: 5)
+    # @return [void]
+    def stop!(timeout: 5)
+      require "timeout"
+      configuration.adapters.each_value do |adapter|
+        if adapter.respond_to?(:stop!)
+          adapter.stop!(timeout: timeout)
+        elsif adapter.respond_to?(:flush!)
+          Timeout.timeout(timeout) { adapter.flush! }
+        end
+      rescue StandardError => e
+        logger.warn("[E11y] Adapter stop error: #{e.message}")
+      end
+      logger.info("[E11y] Stopped")
+    end
+
+    # Check whether E11y will process events with the given severity.
+    # Returns false if no healthy adapter is registered for that severity.
+    #
+    # @param severity [Symbol] e.g. :debug, :info, :error
+    # @return [Boolean]
+    def enabled_for?(severity)
+      return false unless configuration.enabled
+
+      configuration.adapters_for_severity(severity).any? do |name|
+        configuration.adapters[name]&.healthy?
+      end
+    rescue StandardError
+      false
     end
 
-    # Get built pipeline (cached after first call)
+    # Current size of the request-scoped debug buffer for this thread.
     #
-    # @return [#call] Built middleware pipeline
-    def built_pipeline
-      @built_pipeline ||= @pipeline.build(->(_event_data) {})
+    # @return [Integer]
+    def buffer_size
+      buffer = Thread.current[:e11y_ephemeral_buffer]
+      buffer.respond_to?(:size) ? buffer.size : 0
     end
 
-    private
-
-    # Default adapter mapping (convention-based)
+    # Circuit breaker states for all adapters.
     #
-    # 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 => Symbol}] adapter_name => :closed / :open / :half_open
+    def circuit_breaker_state
+      configuration.adapters.transform_values do |adapter|
+        if adapter.respond_to?(:circuit_breaker_state)
+          adapter.circuit_breaker_state
+        else
+          :closed
+        end
+      end
+    end
+
+    # Access the global Event Registry singleton.
     #
-    # @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
+    # The registry auto-populates as event classes are defined (via the `event_name` DSL setter).
+    # Useful for introspection, documentation generation, and admin dashboards.
     #
-    # 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 [E11y::Registry]
     #
-    # @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
+    # @example
+    #   E11y.registry.event_classes
+    #   E11y.registry.find("order.created")
+    def registry
+      Registry.instance
     end
 
-    # Ignore specific ASN event
-    # @param pattern [String] ActiveSupport::Notifications pattern
+    # Reset configuration (primarily for testing)
+    #
     # @return [void]
-    def ignore_event(pattern)
-      @ignore_events << pattern
-    end
-  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
-
-    def initialize
-      @enabled = false # Opt-in: disabled by default
-    end
-  end
-
-  # Request Buffer configuration
-  class RequestBufferConfig
-    attr_accessor :enabled
-
-    def initialize
-      @enabled = false # Disabled by default
-    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.
-  # 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
+    # @api private
+    def reset!
+      @configuration = nil
+      @logger = nil
+      E11y::Metrics.reset_backend!
     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
+  # Default allowed keys for baggage protection (ADR-006 §5.5).
+  # Used when security_baggage_protection_allowed_keys is not set.
+  BAGGAGE_PROTECTION_DEFAULT_ALLOWED_KEYS = %w[
+    trace_id span_id environment version service_name deployment_id request_id
+    experiment experiment_id tenant feature_flag
+  ].freeze
 end
 
 # Load Railtie if Rails is present

data/lib/generators/e11y/event/event_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module E11y
+  module Generators
+    # Generates an event class under app/events/.
+    #
+    # @example
+    #   rails g e11y:event OrderPaid
+    #   # => creates app/events/events/order_paid.rb
+    class EventGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an E11y event class in app/events/."
+
+      def create_event_file
+        template "event.rb.tt", File.join("app/events/events", "#{file_name}.rb")
+      end
+    end
+  end
+end

data/lib/generators/e11y/event/templates/event.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Events
+  class <%= class_name %> < E11y::Event::Base
+    # severity :info   # auto-inferred from class name; override if needed
+
+    schema do
+      # required(:field_name).filled(:string)
+      # optional(:other_field).maybe(:integer)
+    end
+
+    # metrics do
+    #   counter :<%= file_name.gsub("/", "_") %>_total
+    # end
+  end
+end

data/lib/generators/e11y/grafana_dashboard/grafana_dashboard_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module E11y
+  module Generators
+    # Generates a Grafana dashboard JSON for E11y metrics.
+    #
+    # Requires Yabeda/Prometheus integration.
+    #
+    # @example
+    #   rails g e11y:grafana_dashboard
+    #   # => creates config/grafana/e11y_dashboard.json
+    class GrafanaDashboardGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Grafana dashboard JSON for E11y metrics in config/grafana/."
+
+      def create_dashboard
+        empty_directory "config/grafana"
+        template "e11y_dashboard.json", "config/grafana/e11y_dashboard.json"
+      end
+
+      def show_readme
+        say "\n✅ Grafana dashboard created: config/grafana/e11y_dashboard.json", :green
+        say "   Import it via Grafana → Dashboards → Import → Upload JSON file\n"
+      end
+    end
+  end
+end

data/lib/generators/e11y/grafana_dashboard/templates/e11y_dashboard.json

@@ -0,0 +1,81 @@
+{
+  "title": "E11y Observability",
+  "uid": "e11y-overview",
+  "version": 1,
+  "schemaVersion": 36,
+  "tags": ["e11y", "ruby", "observability"],
+  "panels": [
+    {
+      "id": 1,
+      "type": "stat",
+      "title": "Events / sec",
+      "targets": [
+        {
+          "expr": "rate(e11y_events_total[1m])",
+          "legendFormat": "{{event_name}}"
+        }
+      ],
+      "gridPos": { "x": 0, "y": 0, "w": 6, "h": 4 }
+    },
+    {
+      "id": 2,
+      "type": "stat",
+      "title": "Error rate",
+      "targets": [
+        {
+          "expr": "rate(e11y_events_total{severity=\"error\"}[1m]) / rate(e11y_events_total[1m])",
+          "legendFormat": "error rate"
+        }
+      ],
+      "gridPos": { "x": 6, "y": 0, "w": 6, "h": 4 }
+    },
+    {
+      "id": 3,
+      "type": "timeseries",
+      "title": "Events by severity",
+      "targets": [
+        {
+          "expr": "rate(e11y_events_total[1m])",
+          "legendFormat": "{{severity}}"
+        }
+      ],
+      "gridPos": { "x": 0, "y": 4, "w": 12, "h": 8 }
+    },
+    {
+      "id": 4,
+      "type": "stat",
+      "title": "Rate limit drops",
+      "targets": [
+        {
+          "expr": "rate(e11y_rate_limit_dropped_total[1m])",
+          "legendFormat": "dropped"
+        }
+      ],
+      "gridPos": { "x": 12, "y": 0, "w": 6, "h": 4 }
+    },
+    {
+      "id": 5,
+      "type": "stat",
+      "title": "Circuit breaker trips",
+      "targets": [
+        {
+          "expr": "e11y_circuit_breaker_transitions_total{event=\"opened\"}",
+          "legendFormat": "{{adapter}}"
+        }
+      ],
+      "gridPos": { "x": 18, "y": 0, "w": 6, "h": 4 }
+    },
+    {
+      "id": 6,
+      "type": "timeseries",
+      "title": "DLQ queue depth",
+      "targets": [
+        {
+          "expr": "e11y_dlq_size",
+          "legendFormat": "DLQ"
+        }
+      ],
+      "gridPos": { "x": 12, "y": 4, "w": 12, "h": 8 }
+    }
+  ]
+}

data/lib/generators/e11y/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module E11y
+  module Generators
+    # Creates config/initializers/e11y.rb and app/events/ directory scaffold.
+    #
+    # @example
+    #   rails g e11y:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an E11y initializer and the app/events/ directory."
+
+      def create_initializer
+        template "e11y.rb", "config/initializers/e11y.rb"
+      end
+
+      def create_events_directory
+        empty_directory "app/events"
+      end
+
+      def show_readme
+        say "\n✅ E11y installed!", :green
+        say "   • config/initializers/e11y.rb — configure adapters here"
+        say "   • app/events/               — put your event classes here"
+        say "\nNext steps:"
+        say "   rails g e11y:event OrderPaid   # generate an event class"
+        say "   E11y.start!                    # call after configure in production\n"
+      end
+    end
+  end
+end