e11y 0.2.0 → 1.0.0

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

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# E11y Configuration
+# =============================================================================
+#
+# This file is generated by `rails g e11y:install`.
+# Options matching code defaults are commented out. Uncomment and modify to override.
+# "Default:" in comments = value from E11y::Configuration when option is not set.
+#
+# Docs: https://github.com/arturseletskiy/e11y
+
+E11y.configure do |config|
+  # =============================================================================
+  # BASIC
+  # =============================================================================
+
+  # Service name for traces and logs. Used in distributed tracing and log aggregation.
+  # Default: nil (Railtie sets from Rails.application.class.module_parent_name)
+  # config.service_name = ENV["SERVICE_NAME"] || Rails.application.class.module_parent_name.underscore
+
+  # Environment (development, test, production). Affects sampling and log levels.
+  # Default: nil (Railtie sets from Rails.env.to_s)
+  # config.environment = Rails.env.to_s
+
+  # Master switch. When false, E11y does not process events (adapters not called).
+  # Default: nil (Railtie sets !Rails.env.test?)
+  # config.enabled = !Rails.env.test?
+
+  # Default retention period for events routed to adapters. Used by retention-based routing.
+  # Default: 30.days
+  # config.default_retention_period = 30.days
+
+  # Internal E11y log level (:debug, :info, :warn, :error).
+  # Default: :info
+  # config.log_level = :info
+
+  # =============================================================================
+  # ADAPTERS
+  # =============================================================================
+  #
+  # Adapters receive events. Register by name (:logs, :errors_tracker, etc.).
+  # Severity mapping: error/fatal → logs + errors_tracker; others → logs only.
+  # Default: {} (empty; you must register at least one adapter)
+
+  config.adapters[:logs] = E11y::Adapters::Stdout.new(colorize: true)
+
+  # Uncomment for production:
+  # config.adapters[:logs] = E11y::Adapters::Loki.new(url: ENV.fetch("LOKI_URL", "http://localhost:3100"))
+  # config.adapters[:errors_tracker] = E11y::Adapters::Sentry.new(dsn: ENV["SENTRY_DSN"])
+
+  # =============================================================================
+  # RAILS INTEGRATION
+  # =============================================================================
+
+  # Subscribe to ActiveSupport::Notifications (process_action, sql, etc.) and emit E11y events.
+  # Default: false. Uncomment and set true for Rails ASN integration.
+  config.rails_instrumentation_enabled = true
+
+  # Override event class for specific ASN pattern. Hash: pattern => EventClass.
+  # Default: {}
+  # config.rails_instrumentation_custom_mappings["sql.active_record"] = MyCustomEvent
+
+  # Ignore specific ASN events. Array of pattern strings.
+  # Default: []
+  # config.rails_instrumentation_ignore_events = []
+
+  # Sidekiq client/server middleware for trace propagation and job context.
+  # Default: false. Uncomment to auto-enable when Sidekiq is loaded.
+  config.sidekiq_enabled = defined?(Sidekiq)
+
+  # ActiveJob callbacks for job lifecycle events (enqueued, started, completed, failed).
+  # Default: false. Uncomment and set true for Rails ActiveJob integration.
+  config.active_job_enabled = true
+
+  # Wrap Rails.logger and send log calls as E11y events. Useful for migrating to structured logging.
+  # Default: false
+  # config.logger_bridge_enabled = false
+
+  # Severities to track when logger_bridge is enabled. nil = all (:debug, :info, :warn, :error, :fatal).
+  # Default: nil
+  # config.logger_bridge_track_severities = nil
+
+  # Regex patterns to ignore in logger bridge messages.
+  # Default: []
+  # config.logger_bridge_ignore_patterns = [/Started GET/, /Completed \d+ OK/]
+
+  # =============================================================================
+  # EPHEMERAL BUFFER (request/job-scoped debug events)
+  # =============================================================================
+  #
+  # Debug events accumulate in memory per request/job. On success: discarded. On error: flushed to adapters.
+  # Reduces noise by ~90% when only failures need full context.
+
+  # Enable request-scoped and job-scoped debug buffering.
+  # Default: false
+  # config.ephemeral_buffer_enabled = false
+
+  # Flush buffer on 5xx server errors (HTTP) or job failures.
+  # Default: true
+  # config.ephemeral_buffer_flush_on_error = true
+
+  # Additional HTTP statuses that trigger a flush (e.g. [403] for Forbidden).
+  # Default: []
+  # config.ephemeral_buffer_flush_on_statuses = []
+
+  # Adapter names to receive flushed debug events. nil = use fallback_adapters.
+  # Default: nil
+  # config.ephemeral_buffer_debug_adapters = nil
+
+  # Max debug events per job buffer. nil = use default (100).
+  # Default: nil
+  # config.ephemeral_buffer_job_buffer_limit = nil
+
+  # =============================================================================
+  # ERROR HANDLING
+  # =============================================================================
+
+  # When true, event tracking failures raise exceptions. When false, errors are logged and swallowed.
+  # Default: true. Set false for background jobs to avoid failing business logic.
+  # config.error_handling_fail_on_error = true
+
+  # =============================================================================
+  # SLO TRACKING
+  # =============================================================================
+  #
+  # Zero-config SLO metrics for HTTP requests and background jobs (availability, latency, success rate).
+
+  # Enable SLO tracking.
+  # Default: true
+  # config.slo_tracking_enabled = true
+
+  # HTTP status codes to exclude from SLO calculations.
+  # Default: []
+  # config.slo_tracking_http_ignore_statuses = [404, 401]
+
+  # Latency percentiles to emit (e.g. p50, p95, p99).
+  # Default: [50, 95, 99]
+  # config.slo_tracking_latency_percentiles = [50, 95, 99]
+
+  # Per-controller SLO targets. Use add_slo_controller for per-action or per-controller config.
+  # config.add_slo_controller "OrdersController", action: "create" do
+  #   slo_target 0.999      # 99.9% availability
+  #   latency_target 200   # ms
+  # end
+
+  # Per-job SLO config. Use add_slo_job to exclude jobs from tracking.
+  # config.add_slo_job "ProcessPaymentJob" do
+  #   ignore true  # exclude from SLO tracking
+  # end
+
+  # =============================================================================
+  # RATE LIMITING
+  # =============================================================================
+  #
+  # Token-bucket rate limiting to protect adapters from event floods. Supports global and per-event limits.
+
+  # Enable rate limiting.
+  # Default: false
+  # config.rate_limiting_enabled = false
+
+  # Global max events per window (seconds).
+  # Default: 10_000
+  # config.rate_limiting_global_limit = 10_000
+  # Default: 1.0
+  # config.rate_limiting_global_window = 1.0
+
+  # Default per-event limit when no per-event rule matches.
+  # Default: 1_000
+  # config.rate_limiting_per_event_limit = 1_000
+
+  # Per-event or per-pattern limits. Use add_rate_limit_per_event.
+  # config.add_rate_limit_per_event "payment.*", limit: 500, window: 60
+  # config.add_rate_limit_per_event "user.login.failed", limit: 100, window: 60
+
+  # =============================================================================
+  # SECURITY (Baggage PII protection)
+  # =============================================================================
+  #
+  # Blocks PII from OpenTelemetry Baggage and E11y::Current.baggage. Prevents propagation via W3C headers.
+
+  # Enable baggage protection.
+  # Default: true
+  # config.security_baggage_protection_enabled = true
+
+  # Allowed keys in baggage. Only these propagate to downstream services.
+  # Default: %w[trace_id span_id environment version service_name deployment_id request_id experiment experiment_id tenant feature_flag]
+  # config.security_baggage_protection_allowed_keys = %w[trace_id span_id ...]
+
+  # Block mode when PII key is set: :silent (drop), :warn (log + drop), :raise (raise).
+  # Default: :silent
+  # config.security_baggage_protection_block_mode = :silent
+
+  # =============================================================================
+  # TRACING (OpenTelemetry)
+  # =============================================================================
+
+  # Trace context source: :e11y (internal) or :opentelemetry (OTel SDK).
+  # Default: :e11y
+  # config.tracing_source = :e11y
+
+  # Default sample rate for traces (0.0..1.0).
+  # Default: 0.1
+  # config.tracing_default_sample_rate = 0.1
+
+  # Respect parent span sampling decision when OTel SDK provides context.
+  # Default: true
+  # config.tracing_respect_parent_sampling = true
+
+  # Per-event sample rates. Hash: event_name => rate.
+  # Default: {}
+  # config.tracing_per_event_sample_rates = {}
+
+  # Proc to force 100% sampling. Receives E11y::Current.to_context. Return true to always sample.
+  # Default: nil
+  # config.tracing_always_sample_if = ->(ctx) { [123, 456].include?(ctx[:user_id]) }
+
+  # Event name patterns that create OpenTelemetry spans. Glob: "order.*", "payment.*".
+  # Default: []
+  # config.opentelemetry_span_creation_patterns = ["order.*", "payment.*"]
+
+  # =============================================================================
+  # CARDINALITY PROTECTION (metrics label limits)
+  # =============================================================================
+  #
+  # Limits unique label values to prevent metric explosion. Used by adapters that support it (e.g. Yabeda).
+
+  # Max unique values per label before overflow strategy applies.
+  # Default: 1000
+  # config.cardinality_protection_max_cardinality_limit = 1000
+
+  # Label keys to exclude from cardinality protection (e.g. high-cardinality IDs).
+  # Default: []
+  # config.cardinality_protection_denylist = []
+
+  # Overflow strategy: :relabel (aggregate) or :drop.
+  # Default: :relabel
+  # config.cardinality_protection_overflow_strategy = :relabel
+end

data/lib/generators/e11y/prometheus_alerts/prometheus_alerts_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module E11y
+  module Generators
+    # Generates Prometheus alerting rules for E11y metrics.
+    #
+    # @example
+    #   rails g e11y:prometheus_alerts
+    #   # => creates config/prometheus/e11y_alerts.yml
+    class PrometheusAlertsGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates Prometheus alerting rules for E11y in config/prometheus/."
+
+      def create_alerts
+        empty_directory "config/prometheus"
+        template "e11y_alerts.yml", "config/prometheus/e11y_alerts.yml"
+      end
+
+      def show_readme
+        say "\n✅ Prometheus alerts created: config/prometheus/e11y_alerts.yml", :green
+        say "   Load via prometheus.yml rule_files section:\n"
+        say "     rule_files:\n       - config/prometheus/e11y_alerts.yml\n"
+      end
+    end
+  end
+end

data/lib/generators/e11y/prometheus_alerts/templates/e11y_alerts.yml

@@ -0,0 +1,28 @@
+groups:
+  - name: e11y
+    rules:
+      # ── High adapter error rate ─────────────────────────────────────────
+      - alert: E11yHighAdapterErrorRate
+        expr: |
+          sum(rate(e11y_adapter_writes_total{status="failure"}[5m]))
+          / sum(rate(e11y_adapter_writes_total[5m])) > 0.05
+        for: 2m
+        labels:
+          severity: warning
+        annotations:
+          summary: "E11y adapter write error rate above 5%"
+          description: "Adapter error rate is {{ $value | humanizePercentage }} over the last 5 minutes."
+
+      # ── High validation failure rate ────────────────────────────────────
+      - alert: E11yHighValidationFailureRate
+        expr: |
+          rate(e11y_middleware_validation_total{result="failed"}[5m])
+          / (rate(e11y_middleware_validation_total{result="passed"}[5m]) + rate(e11y_middleware_validation_total{result="failed"}[5m])) > 0.1
+        for: 2m
+        labels:
+          severity: warning
+        annotations:
+          summary: "E11y validation failure rate above 10%"
+
+      # Note: E11yRateLimitDrops, E11yCircuitBreakerOpen, E11yDLQGrowing, E11yAdapterUnhealthy
+      # require metrics not yet implemented. Add when rate_limiting, circuit_breaker, DLQ metrics are wired.

data/lib/tasks/e11y_docs.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :e11y do
+  namespace :docs do
+    desc "Generate event docs (Markdown). Filter: SEVERITY=error ADAPTER=logs GREP=order"
+    task generate: :environment do
+      require "e11y/documentation/generator"
+
+      begin
+        Rails.application.eager_load! if defined?(Rails) && Rails.application.respond_to?(:eager_load!)
+      rescue Zeitwerk::SetupRequired
+        # Zeitwerk not ready (e.g. dummy app with eager_load=false); use already-loaded events
+      end
+
+      criteria = {}
+      criteria[:severity] = ENV["SEVERITY"]&.to_sym if ENV["SEVERITY"]
+      criteria[:adapter] = ENV["ADAPTER"]&.to_sym if ENV["ADAPTER"]
+      grep = ENV.fetch("GREP", nil)
+
+      out = if defined?(Rails) && Rails.respond_to?(:root)
+              Rails.root.join("docs", "events")
+            else
+              Pathname.new(File.join(Dir.pwd, "docs", "events"))
+            end
+
+      E11y::Documentation::Generator.generate(out.to_s, criteria: criteria, grep: grep)
+      puts "✅ Documentation generated in #{out}"
+    end
+  end
+end

data/lib/tasks/e11y_events.rake

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+namespace :e11y do
+  desc "List registered events (like rake routes). Filter: SEVERITY=error ADAPTER=logs GREP=order"
+  task events: :environment do
+    require "e11y/registry"
+
+    begin
+      Rails.application.eager_load! if defined?(Rails) && Rails.application.respond_to?(:eager_load!)
+    rescue Zeitwerk::SetupRequired
+      # Zeitwerk not ready (e.g. dummy app with eager_load=false); use already-loaded events
+    end
+
+    criteria = {}
+    criteria[:severity] = ENV["SEVERITY"]&.to_sym if ENV["SEVERITY"]
+    criteria[:adapter] = ENV["ADAPTER"]&.to_sym if ENV["ADAPTER"]
+    grep = ENV.fetch("GREP", nil)
+
+    classes = criteria.any? ? E11y::Registry.where(**criteria) : E11y::Registry.event_classes
+    classes = classes.select { |c| (c.respond_to?(:event_name) ? c.event_name : c.name).to_s.include?(grep) } if grep
+
+    # Column widths (rake routes style)
+    name_width = [classes.map { |c| (c.respond_to?(:event_name) ? c.event_name : c.name).to_s.length }.max || 20, 24].max
+    class_width = [classes.map { |c| c.name.to_s.length }.max || 30, 36].max
+    schema_max = 40
+    schema_width = [classes.map { |c| schema_str(c).length }.max || 20, schema_max].min
+
+    header = "#{'Event Name'.ljust(name_width)} #{'Class'.ljust(class_width)} Ver  Sev   Adapters #{'Schema'.ljust(schema_width)} PII   Audit"
+    sep_len = header.length
+
+    puts header
+    puts "-" * sep_len
+
+    classes.each do |klass|
+      name = (klass.respond_to?(:event_name) ? klass.event_name : klass.name).to_s
+      version = klass.respond_to?(:version) ? "v#{klass.version}" : "—"
+      severity = (klass.respond_to?(:severity) ? klass.severity : "—").to_s
+      adapters = (klass.respond_to?(:adapters) && Array(klass.adapters).any? ? Array(klass.adapters).join(",") : "—").to_s
+      schema = schema_str(klass)
+      schema = "#{schema[0...(schema_max - 3)]}..." if schema.length > schema_max
+      pii = pii_str(klass)
+      audit = klass.respond_to?(:audit_event?) && klass.audit_event? ? "✓" : "—"
+      row = [name.ljust(name_width), klass.name.to_s.ljust(class_width), version.ljust(4),
+             severity.ljust(5), adapters.ljust(12), schema.ljust(schema_width), pii.ljust(6), audit]
+      puts row.join(" ")
+    end
+
+    puts "-" * sep_len
+    puts "#{classes.size} events"
+  end
+end
+
+# Helpers for e11y:events (rake routes style)
+def schema_str(klass)
+  return "—" unless klass.respond_to?(:compiled_schema)
+
+  schema = klass.compiled_schema
+  return "—" if schema.nil? || !schema.respond_to?(:key_map)
+
+  schema.key_map.keys.map(&:name).join(", ")
+rescue StandardError
+  "—"
+end
+
+def pii_str(klass)
+  return "—" unless klass.respond_to?(:pii_filtering_mode)
+
+  klass.pii_filtering_mode.to_s.tr("_", " ")
+rescue StandardError
+  "—"
+end

data/lib/tasks/e11y_lint.rake

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+namespace :e11y do
+  desc "Validate slo.yml, SLO linters, and PII declarations (all-in-one)"
+  task lint: :environment do
+    all_ok = true
+
+    # 1. SLO config validation + SLO linters
+    begin
+      require "e11y/slo/config_loader"
+      require "e11y/slo/config_validator"
+
+      config = E11y::SLO::ConfigLoader.load
+      if config.nil?
+        puts "⚠️  slo.yml not found (optional, skipping SLO checks)"
+      else
+        errors = E11y::SLO::ConfigValidator.validate(config)
+        if errors.any?
+          puts "❌ slo.yml validation failed:"
+          errors.each { |e| puts "  #{e}" }
+          all_ok = false
+        else
+          require "e11y/linters/slo/explicit_declaration_linter"
+          require "e11y/linters/slo/slo_status_from_linter"
+          require "e11y/linters/slo/config_consistency_linter"
+
+          E11y::Linters::SLO::ExplicitDeclarationLinter.validate!
+          E11y::Linters::SLO::SloStatusFromLinter.validate!
+          E11y::Linters::SLO::ConfigConsistencyLinter.validate!
+          puts "✅ SLO config and linters OK"
+        end
+      end
+    rescue E11y::Linters::LinterError => e
+      puts "❌ SLO linter failed: #{e.message}"
+      all_ok = false
+    end
+
+    # 2. PII linter
+    begin
+      require "e11y/linters/pii/pii_declaration_linter"
+
+      E11y::Linters::PII::PiiDeclarationLinter.validate_all!
+      puts "✅ PII declarations OK"
+    rescue E11y::Linters::PII::PiiDeclarationError => e
+      puts "❌ PII linter failed:\n\n#{e.message}"
+      all_ok = false
+    end
+
+    # 3. Schema check (each event has compiled_schema)
+    begin
+      require "e11y/registry"
+      begin
+        Rails.application.eager_load! if defined?(Rails) && Rails.application.respond_to?(:eager_load!)
+      rescue Zeitwerk::SetupRequired
+        # Zeitwerk not ready (e.g. dummy app with eager_load=false); use already-loaded events
+      end
+      schema_errors = []
+      E11y::Registry.event_classes.each do |klass|
+        next if klass.respond_to?(:compiled_schema) && klass.compiled_schema
+
+        name = klass.respond_to?(:event_name) ? klass.event_name : klass.name
+        schema_errors << "#{klass.name} (#{name}): missing schema"
+      end
+      if schema_errors.any?
+        puts "❌ Schema check failed:"
+        schema_errors.each { |e| puts "  #{e}" }
+        all_ok = false
+      else
+        puts "✅ Schema check OK"
+      end
+    rescue StandardError => e
+      puts "❌ Schema check failed: #{e.message}"
+      all_ok = false
+    end
+
+    exit 1 unless all_ok
+  end
+end
+
+# Backwards compatibility: old tasks invoke e11y:lint
+task "e11y:slo:validate" do
+  Rake::Task["e11y:lint"].invoke
+end
+
+namespace :e11y do
+  namespace :lint do
+    task pii: :environment do
+      Rake::Task["e11y:lint"].invoke
+    end
+  end
+end

data/lib/tasks/e11y_slo.rake

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+namespace :e11y do
+  namespace :slo do
+    desc "Generate Grafana dashboard from slo.yml"
+    task dashboard: :environment do
+      require "e11y/slo/config_loader"
+      require "e11y/slo/dashboard_generator"
+
+      config = E11y::SLO::ConfigLoader.load
+      if config.nil?
+        puts "⚠️  slo.yml not found, generating empty dashboard"
+        config = {}
+      end
+
+      json = E11y::SLO::DashboardGenerator.generate(config)
+      out = if defined?(Rails) && Rails.respond_to?(:root)
+              Rails.root.join("config", "grafana",
+                              "e11y_slo_dashboard.json")
+            else
+              Pathname.new(File.join(Dir.pwd, "config",
+                                     "grafana", "e11y_slo_dashboard.json"))
+            end
+      FileUtils.mkdir_p(out.dirname)
+      File.write(out, json)
+      puts "✅ Dashboard written to #{out}"
+    end
+  end
+end