e11y 0.1.0

data/lib/e11y/metrics/registry.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module E11y
+  module Metrics
+    # Registry for metric configurations.
+    #
+    # Stores metric definitions and provides pattern-based matching.
+    # This is a singleton class - use Registry.instance to access it.
+    # All metrics (global, event-level, preset) are registered here for validation.
+    #
+    # @example Register metrics
+    #   registry = E11y::Metrics::Registry.instance
+    #   registry.register(
+    #     type: :counter,
+    #     pattern: 'order.*',
+    #     name: :orders_total,
+    #     tags: [:status, :currency],
+    #     source: 'config/initializers/e11y.rb'
+    #   )
+    #
+    # @example Find matching metrics
+    #   metrics = registry.find_matching('order.paid')
+    #   # => [{ type: :counter, name: :orders_total, ... }]
+    class Registry
+      include Singleton
+
+      # Custom error for label conflicts
+      class LabelConflictError < StandardError; end
+
+      # Custom error for type conflicts
+      class TypeConflictError < StandardError; end
+
+      def initialize
+        @metrics = []
+        @mutex = Mutex.new
+      end
+
+      # Register a new metric configuration
+      #
+      # Validates for conflicts with existing metrics:
+      # - Same metric name must have same type
+      # - Same metric name must have same labels (tags)
+      # - Same metric name must have same buckets (for histograms)
+      #
+      # @param config [Hash] Metric configuration
+      # @option config [Symbol] :type Metric type (:counter, :histogram, :gauge)
+      # @option config [String] :pattern Glob pattern for event names
+      # @option config [Symbol] :name Metric name
+      # @option config [Array<Symbol>] :tags Label names to extract
+      # @option config [Proc, Symbol] :value Value extractor (for histogram/gauge)
+      # @option config [Array<Numeric>] :buckets Histogram buckets
+      # @option config [String] :source Source of the metric (for error messages)
+      # @return [void]
+      #
+      # @raise [LabelConflictError] if metric already registered with different labels
+      # @raise [TypeConflictError] if metric already registered with different type
+      def register(config)
+        validate_config!(config)
+
+        @mutex.synchronize do
+          # Check for conflicts with existing metrics (find within lock)
+          existing = @metrics.find { |m| m[:name] == config[:name] }
+          validate_no_conflicts!(existing, config) if existing
+
+          @metrics << config.merge(
+            pattern_regex: compile_pattern(config[:pattern])
+          )
+        end
+      end
+
+      # Find all metrics matching the event name
+      # @param event_name [String] Event name to match
+      # @return [Array<Hash>] Matching metric configurations
+      def find_matching(event_name)
+        @mutex.synchronize do
+          @metrics.select do |metric|
+            metric[:pattern_regex].match?(event_name)
+          end
+        end
+      end
+
+      # Find metric by name (for conflict detection)
+      # @param name [Symbol] Metric name
+      # @return [Hash, nil] Metric configuration or nil
+      def find_by_name(name)
+        @mutex.synchronize do
+          @metrics.find { |m| m[:name] == name }
+        end
+      end
+
+      # Get all registered metrics
+      # @return [Array<Hash>] All metric configurations
+      def all
+        @mutex.synchronize { @metrics.dup }
+      end
+
+      # Clear all registered metrics
+      # @return [void]
+      def clear!
+        @mutex.synchronize { @metrics.clear }
+      end
+
+      # Get count of registered metrics
+      # @return [Integer] Number of registered metrics
+      def size
+        @mutex.synchronize { @metrics.size }
+      end
+
+      # Validate all registered metrics for conflicts
+      #
+      # This method is called at Rails boot time to catch configuration errors early.
+      # It re-validates all metrics to ensure no conflicts exist.
+      #
+      # @raise [LabelConflictError] if metrics have conflicting labels
+      # @raise [TypeConflictError] if metrics have conflicting types
+      # @return [void]
+      #
+      # @example Manual validation
+      #   E11y::Metrics::Registry.instance.validate_all!
+      def validate_all!
+        @mutex.synchronize do
+          # Group metrics by name
+          metrics_by_name = @metrics.group_by { |m| m[:name] }
+
+          # Check each group for conflicts
+          metrics_by_name.each_value do |metrics|
+            next if metrics.size == 1 # No conflicts possible
+
+            # Compare first metric with all others
+            first = metrics.first
+            metrics[1..].each do |metric|
+              validate_no_conflicts!(first, metric)
+            end
+          end
+        end
+      end
+
+      private
+
+      # Validate metric configuration
+      # @param config [Hash] Metric configuration
+      # @raise [ArgumentError] if configuration is invalid
+      # rubocop:disable Metrics/AbcSize
+      def validate_config!(config)
+        raise ArgumentError, "Metric type is required" unless config[:type]
+        raise ArgumentError, "Invalid metric type: #{config[:type]}" unless %i[counter histogram
+                                                                               gauge].include?(config[:type])
+        raise ArgumentError, "Pattern is required" unless config[:pattern]
+        raise ArgumentError, "Metric name is required" unless config[:name]
+
+        return unless %i[histogram gauge].include?(config[:type]) && !config[:value]
+
+        raise ArgumentError, "Value extractor is required for #{config[:type]} metrics"
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # Validate that new metric doesn't conflict with existing one
+      # @param existing [Hash] Existing metric configuration
+      # @param new_config [Hash] New metric configuration
+      # @raise [TypeConflictError] if types don't match
+      # @raise [LabelConflictError] if labels don't match
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def validate_no_conflicts!(existing, new_config)
+        # Check 1: Type must match
+        if existing[:type] != new_config[:type]
+          raise TypeConflictError, <<~ERROR
+            Metric "#{new_config[:name]}" type conflict!
+
+            Existing: #{existing[:type]} (from #{existing[:source] || 'unknown'})
+            New:      #{new_config[:type]} (from #{new_config[:source] || 'unknown'})
+
+            Fix: Use the same type everywhere or rename the metric.
+          ERROR
+        end
+
+        # Check 2: Labels (tags) must match
+        existing_tags = (existing[:tags] || []).sort
+        new_tags = (new_config[:tags] || []).sort
+
+        if existing_tags != new_tags
+          raise LabelConflictError, <<~ERROR
+            Metric "#{new_config[:name]}" label conflict!
+
+            Existing: #{existing_tags.inspect} (from #{existing[:source] || 'unknown'})
+            New:      #{new_tags.inspect} (from #{new_config[:source] || 'unknown'})
+
+            Fix: Use the same labels everywhere or rename the metric.
+
+            Example:
+              # Event 1
+              counter :#{new_config[:name]}, tags: #{existing_tags.inspect}
+            #{'  '}
+              # Event 2 (must match!)
+              counter :#{new_config[:name]}, tags: #{existing_tags.inspect}
+          ERROR
+        end
+
+        # Check 3: For histograms, buckets should match (warn only)
+        return unless new_config[:type] == :histogram
+
+        existing_buckets = existing[:buckets]
+        new_buckets = new_config[:buckets]
+
+        return if existing_buckets == new_buckets
+
+        warn <<~WARNING
+          Metric "#{new_config[:name]}" has different buckets!
+          Existing: #{existing_buckets.inspect}
+          New:      #{new_buckets.inspect}
+          Using existing buckets.
+        WARNING
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      # Compile glob pattern to regex
+      # @param pattern [String] Glob pattern (e.g., "order.*", "user.*.created")
+      # @return [Regexp] Compiled regex
+      def compile_pattern(pattern)
+        # Convert glob pattern to regex
+        # - '*' matches any segment (e.g., "order.*" matches "order.paid", "order.created")
+        # - '**' matches any number of segments (e.g., "order.**" matches "order.paid.usd")
+        regex_pattern = pattern
+                        .gsub(".", '\.')           # Escape dots
+                        .gsub("**", "__DOUBLE__")  # Temporarily replace **
+                        .gsub("*", "[^.]+")        # * matches single segment
+                        .gsub("__DOUBLE__", ".*")  # ** matches multiple segments
+
+        Regexp.new("\\A#{regex_pattern}\\z")
+      end
+    end
+  end
+end

data/lib/e11y/metrics/relabeling.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module E11y
+  module Metrics
+    # Universal label relabeling mechanism via DSL.
+    #
+    # Transforms high-cardinality label values into low-cardinality categories
+    # to prevent metric explosions while preserving signal quality.
+    #
+    # @example HTTP status codes to classes
+    #   relabeler = Relabeling.new
+    #   relabeler.define(:http_status) do |value|
+    #     case value.to_i
+    #     when 100..199 then '1xx'
+    #     when 200..299 then '2xx'
+    #     when 300..399 then '3xx'
+    #     when 400..499 then '4xx'
+    #     when 500..599 then '5xx'
+    #     else 'unknown'
+    #     end
+    #   end
+    #
+    #   relabeler.apply(:http_status, 200) # => '2xx'
+    #   relabeler.apply(:http_status, 404) # => '4xx'
+    #
+    # @example Path normalization
+    #   relabeler.define(:path) do |value|
+    #     value.gsub(/\/\d+/, '/:id')
+    #          .gsub(/\/[a-f0-9-]{36}/, '/:uuid')
+    #   end
+    #
+    #   relabeler.apply(:path, '/users/123/orders/456') # => '/users/:id/orders/:id'
+    #
+    # @example Region grouping
+    #   relabeler.define(:region) do |value|
+    #     case value.to_s
+    #     when /^us-/ then 'us'
+    #     when /^eu-/ then 'eu'
+    #     when /^ap-/ then 'ap'
+    #     else 'other'
+    #     end
+    #   end
+    #
+    # @see ADR-002 §4.6 (Relabeling Rules)
+    class Relabeling
+      # Initialize relabeler with optional rules
+      #
+      # @param rules [Hash{Symbol => Proc}] Initial relabeling rules
+      def initialize(rules = {})
+        @rules = {}
+        @mutex = Mutex.new
+        rules.each { |label_key, block| define(label_key, &block) }
+      end
+
+      # Define relabeling rule for a label
+      #
+      # Rule is applied via block that receives original value
+      # and returns transformed value.
+      #
+      # @param label_key [Symbol, String] Label key to relabel
+      # @yield [value] Block that transforms label value
+      # @yieldparam value [Object] Original label value
+      # @yieldreturn [String, Symbol] Transformed label value
+      # @return [void]
+      #
+      # @example Simple mapping
+      #   relabeler.define(:environment) do |value|
+      #     value == 'production' ? 'prod' : 'non-prod'
+      #   end
+      #
+      # @example Range-based classification
+      #   relabeler.define(:duration_ms) do |value|
+      #     case value.to_i
+      #     when 0..100 then 'fast'
+      #     when 101..1000 then 'medium'
+      #     else 'slow'
+      #     end
+      #   end
+      def define(label_key, &block)
+        raise ArgumentError, "Block required for relabeling rule" unless block_given?
+
+        @mutex.synchronize do
+          @rules[label_key.to_sym] = block
+        end
+      end
+
+      # Apply relabeling to label value
+      #
+      # If rule exists for label_key, applies transformation.
+      # Otherwise returns original value unchanged.
+      #
+      # Thread-safe operation.
+      #
+      # @param label_key [Symbol, String] Label key
+      # @param value [Object] Original value
+      # @return [Object] Relabeled value or original if no rule defined
+      def apply(label_key, value)
+        rule = @mutex.synchronize { @rules[label_key.to_sym] }
+        return value unless rule
+
+        begin
+          rule.call(value)
+        rescue StandardError => e
+          warn "[E11y] Relabeling error for #{label_key}=#{value}: #{e.message}"
+          value # Return original on error
+        end
+      end
+
+      # Apply relabeling to hash of labels
+      #
+      # Transforms all labels that have defined rules.
+      # Labels without rules pass through unchanged.
+      #
+      # @param labels [Hash] Hash of label_key => value
+      # @return [Hash] Hash with relabeled values
+      #
+      # @example
+      #   labels = { http_status: 200, path: '/users/123', env: 'production' }
+      #   relabeler.apply_all(labels)
+      #   # => { http_status: '2xx', path: '/users/:id', env: 'production' }
+      def apply_all(labels)
+        labels.transform_keys(&:to_sym).transform_values do |value|
+          label_key = begin
+            labels.key(value).to_sym
+          rescue StandardError
+            nil
+          end
+          label_key ? apply(label_key, value) : value
+        end
+      end
+
+      # Check if relabeling rule exists for label
+      #
+      # @param label_key [Symbol, String] Label key
+      # @return [Boolean] true if rule defined
+      def defined?(label_key)
+        @mutex.synchronize { @rules.key?(label_key.to_sym) }
+      end
+
+      # Remove relabeling rule
+      #
+      # @param label_key [Symbol, String] Label key
+      # @return [void]
+      def remove(label_key)
+        @mutex.synchronize { @rules.delete(label_key.to_sym) }
+      end
+
+      # Get all defined rule keys
+      #
+      # @return [Array<Symbol>] List of label keys with rules
+      def keys
+        @mutex.synchronize { @rules.keys }
+      end
+
+      # Reset all relabeling rules
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize { @rules.clear }
+      end
+
+      # Get number of defined rules
+      #
+      # @return [Integer] Rule count
+      def size
+        @mutex.synchronize { @rules.size }
+      end
+
+      # Predefined common relabeling rules
+      module CommonRules
+        # HTTP status code to status class (1xx, 2xx, 3xx, 4xx, 5xx)
+        #
+        # @param value [Integer, String] HTTP status code
+        # @return [String] Status class
+        def self.http_status_class(value)
+          code = value.to_i
+          return "unknown" if code < 100 || code >= 600
+
+          "#{code / 100}xx"
+        end
+
+        # Path normalization - replace numeric IDs and UUIDs with placeholders
+        #
+        # @param value [String] URL path
+        # @return [String] Normalized path
+        def self.normalize_path(value)
+          value.to_s
+               .gsub(%r{/[a-f0-9-]{36}}, "/:uuid") # UUIDs (must be before :id to avoid partial match)
+               .gsub(%r{/[a-f0-9]{32}}, "/:hash") # MD5 hashes (must be before :id)
+               .gsub(%r{/\d+}, "/:id") # /users/123 -> /users/:id
+        end
+
+        # Region to region group (us-east-1 -> us, eu-west-2 -> eu)
+        #
+        # @param value [String] AWS-style region
+        # @return [String] Region group
+        def self.region_group(value)
+          case value.to_s
+          when /^us-/ then "us"
+          when /^eu-/ then "eu"
+          when /^ap-/ then "ap"
+          when /^sa-/ then "sa"
+          when /^ca-/ then "ca"
+          when /^af-/ then "af"
+          when /^me-/ then "me"
+          else "other"
+          end
+        end
+
+        # Duration classification (ms to fast/medium/slow)
+        #
+        # @param value [Numeric] Duration in milliseconds
+        # @return [String] Classification
+        def self.duration_class(value)
+          ms = value.to_f
+          case ms
+          when 0..100 then "fast"
+          when 101..1000 then "medium"
+          when 1001..5000 then "slow"
+          else "very_slow"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/metrics.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "e11y/metrics/registry"
+require "e11y/metrics/cardinality_protection"
+
+module E11y
+  # Public API for tracking metrics.
+  #
+  # This is a facade that delegates to the configured metrics backend (e.g., Yabeda).
+  # If no backend is configured, metrics are silently discarded (noop).
+  #
+  # @example Track a counter
+  #   E11y::Metrics.increment(:http_requests_total, { method: 'GET', status: 200 })
+  #
+  # @example Track a histogram
+  #   E11y::Metrics.histogram(:http_request_duration_seconds, 0.042, { method: 'GET' })
+  #
+  # @example Track a gauge
+  #   E11y::Metrics.gauge(:active_connections, 42, { server: 'web-01' })
+  #
+  # @see ADR-002 §3 (Metrics Integration)
+  # @see ADR-016 §3 (Self-Monitoring Metrics)
+  module Metrics
+    class << self
+      # Track a counter metric (monotonically increasing value).
+      #
+      # @param name [Symbol] Metric name (e.g., :http_requests_total)
+      # @param labels [Hash] Metric labels (e.g., { method: 'GET', status: 200 })
+      # @param value [Integer] Increment value (default: 1)
+      # @return [void]
+      #
+      # @example
+      #   E11y::Metrics.increment(:e11y_events_tracked, { event_type: 'order.created' })
+      def increment(name, labels = {}, value: 1)
+        backend&.increment(name, labels, value: value)
+      end
+
+      # Track a histogram metric (distribution of values).
+      #
+      # @param name [Symbol] Metric name (e.g., :http_request_duration_seconds)
+      # @param value [Numeric] Observed value (e.g., 0.042 for 42ms)
+      # @param labels [Hash] Metric labels (e.g., { method: 'GET' })
+      # @param buckets [Array<Numeric>, nil] Optional histogram buckets (for backend config)
+      # @return [void]
+      #
+      # @example
+      #   E11y::Metrics.histogram(:e11y_track_duration_seconds, 0.0005, { event_type: 'order.created' })
+      def histogram(name, value, labels = {}, buckets: nil)
+        backend&.histogram(name, value, labels, buckets: buckets)
+      end
+
+      # Track a gauge metric (current value that can go up or down).
+      #
+      # @param name [Symbol] Metric name (e.g., :active_connections)
+      # @param value [Numeric] Current value (e.g., 42)
+      # @param labels [Hash] Metric labels (e.g., { server: 'web-01' })
+      # @return [void]
+      #
+      # @example
+      #   E11y::Metrics.gauge(:e11y_buffer_size, 128, { buffer_type: 'ring' })
+      def gauge(name, value, labels = {})
+        backend&.gauge(name, value, labels)
+      end
+
+      # Get the configured metrics backend.
+      #
+      # The backend is determined by checking for configured adapters:
+      # - If Yabeda adapter is configured, use it
+      # - Otherwise, return nil (noop)
+      #
+      # @return [Object, nil] Metrics backend or nil
+      # @api private
+      def backend
+        return @backend if defined?(@backend)
+
+        @backend = detect_backend
+      end
+
+      # Reset the backend (useful for testing).
+      #
+      # @api private
+      def reset_backend!
+        remove_instance_variable(:@backend) if defined?(@backend)
+      end
+
+      private
+
+      # Detect the metrics backend from configured adapters.
+      #
+      # @return [Object, nil] Metrics backend or nil
+      def detect_backend
+        # Check if Yabeda adapter is configured
+        # Use class name string to avoid LoadError if Yabeda gem not installed
+        yabeda_adapter = E11y.config.adapters.values.find { |adapter| adapter.class.name == "E11y::Adapters::Yabeda" }
+        return yabeda_adapter if yabeda_adapter
+
+        # No backend configured → noop
+        nil
+      end
+    end
+  end
+end