e11y 0.1.0

data/lib/e11y/adapters/sentry.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+# Check if Sentry SDK is available
+begin
+  require "sentry-ruby"
+rescue LoadError
+  raise LoadError, <<~ERROR
+    Sentry SDK not available!
+
+    To use E11y::Adapters::Sentry, add to your Gemfile:
+
+      gem 'sentry-ruby'
+
+    Then run: bundle install
+  ERROR
+end
+
+module E11y
+  module Adapters
+    # Sentry adapter for error tracking and breadcrumbs.
+    #
+    # Features:
+    # - Automatic error reporting to Sentry
+    # - Breadcrumb tracking for context
+    # - Severity-based filtering
+    # - Trace context propagation
+    # - User context support
+    #
+    # @example Basic usage
+    #   adapter = E11y::Adapters::Sentry.new(
+    #     dsn: ENV["SENTRY_DSN"],
+    #     environment: "production",
+    #     severity_threshold: :warn
+    #   )
+    #
+    # @example With Registry
+    #   E11y::Adapters::Registry.register(
+    #     :error_tracker,
+    #     E11y::Adapters::Sentry.new(dsn: ENV["SENTRY_DSN"])
+    #   )
+    #
+    # @see https://docs.sentry.io/platforms/ruby/
+    class Sentry < Base
+      # Severity levels in order
+      SEVERITY_LEVELS = %i[debug info success warn error fatal].freeze
+
+      # Default severity threshold for Sentry
+      DEFAULT_SEVERITY_THRESHOLD = :warn
+
+      attr_reader :dsn, :environment, :severity_threshold, :send_breadcrumbs
+
+      # Initialize Sentry adapter
+      #
+      # @param config [Hash] Configuration options
+      # @option config [String] :dsn (required) Sentry DSN
+      # @option config [String] :environment ("production") Environment name
+      # @option config [Symbol] :severity_threshold (:warn) Minimum severity to send to Sentry
+      # @option config [Boolean] :breadcrumbs (true) Enable breadcrumb tracking
+      def initialize(config = {})
+        @dsn = config[:dsn]
+        @environment = config.fetch(:environment, "production")
+        @severity_threshold = config.fetch(:severity_threshold, DEFAULT_SEVERITY_THRESHOLD)
+        @send_breadcrumbs = config.fetch(:breadcrumbs, true)
+
+        super
+
+        initialize_sentry!
+      end
+
+      # Write event to Sentry
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] Success status
+      def write(event_data)
+        severity = event_data[:severity]
+
+        # Only send events above threshold
+        return true unless should_send_to_sentry?(severity)
+
+        if error_severity?(severity)
+          send_error_to_sentry(event_data)
+        elsif @send_breadcrumbs
+          send_breadcrumb_to_sentry(event_data)
+        end
+
+        true
+      rescue StandardError => e
+        warn "E11y Sentry adapter error: #{e.message}"
+        false
+      end
+
+      # Adapter capabilities
+      #
+      # @return [Hash] Capability flags
+      def capabilities
+        super.merge(
+          batching: false, # Sentry SDK handles batching
+          compression: false, # Sentry SDK handles compression
+          async: true, # Sentry SDK is async
+          streaming: false
+        )
+      end
+
+      # Check if adapter is healthy
+      #
+      # @return [Boolean] True if Sentry is configured
+      def healthy?
+        ::Sentry.initialized?
+      end
+
+      private
+
+      # Validate configuration
+      def validate_config!
+        raise ArgumentError, "Sentry adapter requires :dsn" unless @dsn
+
+        return if SEVERITY_LEVELS.include?(@severity_threshold)
+
+        raise ArgumentError,
+              "Invalid severity_threshold: #{@severity_threshold}"
+      end
+
+      # Initialize Sentry SDK
+      def initialize_sentry!
+        ::Sentry.init do |config|
+          config.dsn = @dsn
+          config.environment = @environment
+          config.breadcrumbs_logger = [] # We manage breadcrumbs manually
+        end
+      end
+
+      # Check if severity should be sent to Sentry
+      #
+      # @param severity [Symbol] Event severity
+      # @return [Boolean] True if severity >= threshold
+      def should_send_to_sentry?(severity)
+        threshold_index = SEVERITY_LEVELS.index(@severity_threshold)
+        current_index = SEVERITY_LEVELS.index(severity)
+
+        return false unless threshold_index && current_index
+
+        current_index >= threshold_index
+      end
+
+      # Check if severity is error-level
+      #
+      # @param severity [Symbol] Event severity
+      # @return [Boolean] True if error or fatal
+      def error_severity?(severity)
+        %i[error fatal].include?(severity)
+      end
+
+      # Send error to Sentry
+      #
+      # @param event_data [Hash] Event data
+      def send_error_to_sentry(event_data)
+        ::Sentry.with_scope do |scope|
+          # Set tags
+          scope.set_tags(extract_tags(event_data))
+
+          # Set extras
+          scope.set_extras(event_data[:payload] || {})
+
+          # Set user context
+          scope.set_user(event_data[:user] || {}) if event_data[:user]
+
+          # Set trace context
+          if event_data[:trace_id]
+            scope.set_context("trace", {
+                                trace_id: event_data[:trace_id],
+                                span_id: event_data[:span_id]
+                              })
+          end
+
+          # Capture exception or message
+          if event_data[:exception]
+            ::Sentry.capture_exception(event_data[:exception])
+          else
+            ::Sentry.capture_message(
+              event_data[:message] || event_data[:event_name].to_s,
+              level: sentry_level(event_data[:severity])
+            )
+          end
+        end
+      end
+
+      # Send breadcrumb to Sentry
+      #
+      # @param event_data [Hash] Event data
+      def send_breadcrumb_to_sentry(event_data)
+        ::Sentry.add_breadcrumb(
+          ::Sentry::Breadcrumb.new(
+            category: event_data[:event_name].to_s,
+            message: event_data[:message]&.to_s,
+            level: sentry_level(event_data[:severity]),
+            data: event_data[:payload] || {},
+            timestamp: event_data[:timestamp]&.to_i
+          )
+        )
+      end
+
+      # Extract tags from event
+      #
+      # @param event_data [Hash] Event data
+      # @return [Hash] Tags for Sentry
+      def extract_tags(event_data)
+        {
+          event_name: event_data[:event_name].to_s,
+          severity: event_data[:severity].to_s,
+          environment: @environment
+        }
+      end
+
+      # Map E11y severity to Sentry level
+      #
+      # @param severity [Symbol] E11y severity
+      # @return [Symbol] Sentry level
+      def sentry_level(severity)
+        case severity
+        when :debug then :debug
+        when :info, :success then :info
+        when :warn then :warning
+        when :error then :error
+        when :fatal then :fatal
+        else :info
+        end
+      end
+    end
+  end
+end

data/lib/e11y/adapters/stdout.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+
+module E11y
+  module Adapters
+    # Stdout Adapter - Console output for development and debugging
+    #
+    # Outputs events to STDOUT with optional colorization and pretty printing.
+    # Primarily for development use.
+    #
+    # **Features:**
+    # - Colorized output based on severity
+    # - Pretty-print JSON (optional)
+    # - Streaming output
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     config.register_adapter :stdout, E11y::Adapters::Stdout.new(
+    #       colorize: true,
+    #       pretty_print: true
+    #     )
+    #   end
+    #
+    # @see ADR-004 §4.1 (Stdout Adapter)
+    class Stdout < Base
+      # ANSI color codes for severity levels
+      SEVERITY_COLORS = {
+        debug: "\e[37m",      # Gray
+        info: "\e[36m",       # Cyan
+        success: "\e[32m",    # Green
+        warn: "\e[33m",       # Yellow
+        error: "\e[31m",      # Red
+        fatal: "\e[35m"       # Magenta
+      }.freeze
+
+      # Color reset
+      COLOR_RESET = "\e[0m"
+
+      # Initialize adapter
+      #
+      # @param config [Hash] Configuration options
+      # @option config [Boolean] :colorize (true) Enable colored output
+      # @option config [Boolean] :pretty_print (true) Enable pretty-printed JSON
+      def initialize(config = {})
+        @colorize = config.fetch(:colorize, true)
+        @pretty_print = config.fetch(:pretty_print, true)
+
+        super
+      end
+
+      # Write event to STDOUT
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] true on success, false on failure
+      def write(event_data)
+        output = format_event(event_data)
+
+        if @colorize
+          puts colorize_output(output, event_data[:severity])
+        else
+          puts output
+        end
+
+        true
+      rescue StandardError => e
+        warn "Stdout adapter error: #{e.message}"
+        false
+      end
+
+      # Adapter capabilities
+      #
+      # @return [Hash] Capability flags
+      def capabilities
+        {
+          batching: false,
+          compression: false,
+          async: false,
+          streaming: true
+        }
+      end
+
+      private
+
+      # Format event for console output
+      #
+      # @param event_data [Hash] Event data
+      # @return [String] Formatted output
+      def format_event(event_data)
+        if @pretty_print
+          JSON.pretty_generate(event_data)
+        else
+          event_data.to_json
+        end
+      end
+
+      # Colorize output based on severity
+      #
+      # @param output [String] Formatted output
+      # @param severity [Symbol] Event severity
+      # @return [String] Colorized output
+      def colorize_output(output, severity)
+        color_code = SEVERITY_COLORS[severity] || ""
+        "#{color_code}#{output}#{COLOR_RESET}"
+      end
+    end
+  end
+end

data/lib/e11y/adapters/yabeda.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+require "e11y/adapters/base"
+require "e11y/metrics/cardinality_protection"
+require "e11y/metrics/registry"
+
+# Check if Yabeda is available
+begin
+  require "yabeda"
+rescue LoadError
+  raise LoadError, <<~ERROR
+    Yabeda not available!
+
+    To use E11y::Adapters::Yabeda, add to your Gemfile:
+
+      gem 'yabeda'
+      gem 'yabeda-prometheus'  # For Prometheus exporter
+
+    Then run: bundle install
+  ERROR
+end
+
+module E11y
+  module Adapters
+    # Yabeda adapter for E11y metrics.
+    #
+    # This adapter integrates with Yabeda to expose metrics to Prometheus.
+    # It includes built-in cardinality protection to prevent metric explosions.
+    #
+    # Features:
+    # - Automatic metric registration from E11y::Metrics::Registry
+    # - 3-layer cardinality protection (denylist, per-metric limits, monitoring)
+    # - Counter, Histogram, and Gauge support
+    # - Thread-safe metric updates
+    #
+    # @example Basic usage
+    #   adapter = E11y::Adapters::Yabeda.new(
+    #     cardinality_limit: 1000,
+    #     forbidden_labels: [:custom_id]
+    #   )
+    #
+    #   # Metrics are automatically registered from Registry
+    #   # Events automatically update metrics via middleware
+    #
+    # @see ADR-002 Metrics & Yabeda Integration
+    # @see UC-003 Pattern-Based Metrics
+    class Yabeda < Base
+      # Initialize Yabeda adapter
+      #
+      # @param config [Hash] Configuration options
+      # @option config [Integer] :cardinality_limit (1000) Max unique values per label per metric
+      # @option config [Array<Symbol>] :forbidden_labels ([]) Additional labels to denylist
+      # @option config [Boolean] :auto_register (true) Automatically register metrics from Registry
+      def initialize(config = {})
+        super
+
+        @cardinality_protection = E11y::Metrics::CardinalityProtection.new(
+          cardinality_limit: config.fetch(:cardinality_limit, 1000),
+          forbidden_labels: config.fetch(:forbidden_labels, [])
+        )
+
+        # Auto-register metrics from Registry
+        register_metrics_from_registry! if config.fetch(:auto_register, true)
+      end
+
+      # Write a single event to Yabeda
+      #
+      # Extracts metrics from event data and updates corresponding Yabeda metrics.
+      # Applies cardinality protection to prevent label explosions.
+      #
+      # @param event_data [Hash] Event data
+      # @return [Boolean] true if successful
+      def write(event_data)
+        event_name = event_data[:event_name].to_s
+        matching_metrics = E11y::Metrics::Registry.instance.find_matching(event_name)
+
+        matching_metrics.each do |metric_config|
+          update_metric(metric_config, event_data)
+        end
+
+        true
+      rescue StandardError => e
+        warn "E11y Yabeda adapter error: #{e.message}"
+        false
+      end
+
+      # Write a batch of events
+      #
+      # @param events [Array<Hash>] Array of event data hashes
+      # @return [Boolean] true if successful
+      def write_batch(events)
+        events.each { |event| write(event) }
+        true
+      rescue StandardError => e
+        warn "E11y Yabeda adapter batch error: #{e.message}"
+        false
+      end
+
+      # Check if adapter is healthy
+      #
+      # @return [Boolean] true if Yabeda is available and configured
+      def healthy?
+        return false unless defined?(::Yabeda)
+
+        ::Yabeda.configured?
+      rescue StandardError
+        false
+      end
+
+      # Close adapter (no-op for Yabeda)
+      #
+      # @return [void]
+      def close
+        # Yabeda doesn't need explicit cleanup
+      end
+
+      # Get adapter capabilities
+      #
+      # @return [Hash] Capabilities hash
+      def capabilities
+        {
+          batch: true,
+          async: false,
+          filtering: false,
+          metrics: true
+        }
+      end
+
+      # Track a counter metric (for E11y::Metrics facade).
+      #
+      # @param name [Symbol] Metric name
+      # @param labels [Hash] Metric labels
+      # @param value [Integer] Increment value (default: 1)
+      # @return [void]
+      def increment(name, labels = {}, value: 1)
+        return unless healthy?
+
+        # Apply cardinality protection
+        safe_labels = @cardinality_protection.filter(labels, name)
+
+        # Register metric if not exists
+        register_metric_if_needed(name, :counter, safe_labels.keys)
+
+        # Update Yabeda metric
+        ::Yabeda.e11y.send(name).increment(safe_labels, by: value)
+      rescue StandardError => e
+        E11y.logger.warn("Failed to increment Yabeda metric #{name}: #{e.message}", error: e.class.name)
+      end
+
+      # Track a histogram metric (for E11y::Metrics facade).
+      #
+      # @param name [Symbol] Metric name
+      # @param value [Numeric] Observed value
+      # @param labels [Hash] Metric labels
+      # @param buckets [Array<Numeric>, nil] Optional histogram buckets
+      # @return [void]
+      def histogram(name, value, labels = {}, buckets: nil)
+        return unless healthy?
+
+        # Apply cardinality protection
+        safe_labels = @cardinality_protection.filter(labels, name)
+
+        # Register metric if not exists
+        register_metric_if_needed(name, :histogram, safe_labels.keys, buckets: buckets)
+
+        # Update Yabeda metric
+        ::Yabeda.e11y.send(name).observe(value, safe_labels)
+      rescue StandardError => e
+        E11y.logger.warn("Failed to observe Yabeda histogram #{name}: #{e.message}", error: e.class.name)
+      end
+
+      # Track a gauge metric (for E11y::Metrics facade).
+      #
+      # @param name [Symbol] Metric name
+      # @param value [Numeric] Current value
+      # @param labels [Hash] Metric labels
+      # @return [void]
+      def gauge(name, value, labels = {})
+        return unless healthy?
+
+        # Apply cardinality protection
+        safe_labels = @cardinality_protection.filter(labels, name)
+
+        # Register metric if not exists
+        register_metric_if_needed(name, :gauge, safe_labels.keys)
+
+        # Update Yabeda metric
+        ::Yabeda.e11y.send(name).set(value, safe_labels)
+      rescue StandardError => e
+        E11y.logger.warn("Failed to set Yabeda gauge #{name}: #{e.message}", error: e.class.name)
+      end
+
+      # Validate configuration
+      #
+      # @raise [ArgumentError] if configuration is invalid
+      # @return [void]
+      def validate_config!
+        super
+
+        # Validate cardinality_limit
+        if @config[:cardinality_limit] && !@config[:cardinality_limit].is_a?(Integer)
+          raise ArgumentError, "cardinality_limit must be an Integer"
+        end
+
+        # Validate forbidden_labels
+        return unless @config[:forbidden_labels] && !@config[:forbidden_labels].is_a?(Array)
+
+        raise ArgumentError, "forbidden_labels must be an Array"
+      end
+
+      # Format event for Yabeda (no-op, metrics are updated directly)
+      #
+      # @param event_data [Hash] Event data
+      # @return [Hash] Original event data
+      def format_event(event_data)
+        event_data
+      end
+
+      # Get current cardinality statistics
+      #
+      # @return [Hash] Cardinality statistics per metric:label
+      def cardinality_stats
+        @cardinality_protection.cardinalities
+      end
+
+      # Reset cardinality tracking (for testing)
+      #
+      # @return [void]
+      def reset_cardinality!
+        @cardinality_protection.reset!
+      end
+
+      private
+
+      # Register metrics from Registry into Yabeda
+      #
+      # This is called during initialization if auto_register is true.
+      # It creates Yabeda metric definitions for all metrics in the Registry.
+      #
+      # @return [void]
+      def register_metrics_from_registry!
+        return unless defined?(::Yabeda)
+
+        registry = E11y::Metrics::Registry.instance
+        registry.all.each do |metric_config|
+          register_yabeda_metric(metric_config)
+        end
+      end
+
+      # Register a single metric in Yabeda
+      #
+      # @param metric_config [Hash] Metric configuration from Registry
+      # @return [void]
+      def register_yabeda_metric(metric_config)
+        metric_name = metric_config[:name]
+        metric_type = metric_config[:type]
+        tags = metric_config[:tags] || []
+
+        # Define metric in Yabeda group
+        ::Yabeda.configure do
+          group :e11y do
+            case metric_type
+            when :counter
+              counter metric_name, tags: tags, comment: "E11y metric: #{metric_name}"
+            when :histogram
+              histogram metric_name,
+                        tags: tags,
+                        buckets: metric_config[:buckets] || [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10],
+                        comment: "E11y metric: #{metric_name}"
+            when :gauge
+              gauge metric_name, tags: tags, comment: "E11y metric: #{metric_name}"
+            end
+          end
+        end
+      rescue StandardError => e
+        # Metric might already be registered - that's OK
+        warn "E11y Yabeda: Could not register metric #{metric_name}: #{e.message}"
+      end
+
+      # Register a metric if it doesn't exist yet (for direct metric calls).
+      #
+      # @param name [Symbol] Metric name
+      # @param type [Symbol] Metric type (:counter, :histogram, :gauge)
+      # @param tags [Array<Symbol>] Metric tags (labels)
+      # @param buckets [Array<Numeric>, nil] Optional histogram buckets
+      # @return [void]
+      # @api private
+      def register_metric_if_needed(name, type, tags, buckets: nil)
+        # Check if metric already exists
+        return if ::Yabeda.metrics.key?(:"e11y_#{name}")
+
+        ::Yabeda.configure do
+          group :e11y do
+            case type
+            when :counter
+              counter name, tags: tags, comment: "E11y self-monitoring: #{name}"
+            when :histogram
+              histogram name,
+                        tags: tags,
+                        buckets: buckets || [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10],
+                        comment: "E11y self-monitoring: #{name}"
+            when :gauge
+              gauge name, tags: tags, comment: "E11y self-monitoring: #{name}"
+            end
+          end
+        end
+      rescue StandardError => e
+        # Metric might already be registered - that's OK
+        E11y.logger.debug("Could not register Yabeda metric #{name}: #{e.message}")
+      end
+
+      # Update a single metric based on event data
+      #
+      # @param metric_config [Hash] Metric configuration
+      # @param event_data [Hash] Event data
+      # @return [void]
+      def update_metric(metric_config, event_data)
+        metric_name = metric_config[:name]
+        labels = extract_labels(metric_config, event_data)
+
+        # Apply cardinality protection
+        safe_labels = @cardinality_protection.filter(labels, metric_name)
+
+        # Extract value for histogram/gauge
+        value = extract_value(metric_config, event_data) if %i[histogram gauge].include?(metric_config[:type])
+
+        # Update Yabeda metric
+        case metric_config[:type]
+        when :counter
+          ::Yabeda.e11y.send(metric_name).increment(safe_labels)
+        when :histogram
+          ::Yabeda.e11y.send(metric_name).observe(value, safe_labels)
+        when :gauge
+          ::Yabeda.e11y.send(metric_name).set(value, safe_labels)
+        end
+      rescue StandardError => e
+        warn "E11y Yabeda: Error updating metric #{metric_name}: #{e.message}"
+      end
+
+      # Extract labels from event data
+      #
+      # @param metric_config [Hash] Metric configuration
+      # @param event_data [Hash] Event data
+      # @return [Hash] Extracted labels
+      def extract_labels(metric_config, event_data)
+        metric_config.fetch(:tags, []).each_with_object({}) do |tag, acc|
+          value = event_data[tag] || event_data.dig(:payload, tag)
+          acc[tag] = value.to_s if value
+        end
+      end
+
+      # Extract value for histogram or gauge metrics
+      #
+      # @param metric_config [Hash] Metric configuration
+      # @param event_data [Hash] Event data
+      # @return [Numeric] The extracted value
+      def extract_value(metric_config, event_data)
+        value_extractor = metric_config[:value]
+        case value_extractor
+        when Symbol
+          event_data[value_extractor] || event_data.dig(:payload, value_extractor)
+        when Proc
+          value_extractor.call(event_data)
+        else
+          1 # Default fallback
+        end
+      end
+    end
+  end
+end