brainzlab-rails 0.1.1

data/lib/brainzlab/rails/collectors/cache.rb

@@ -0,0 +1,384 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Rails
+    module Collectors
+      # Collects Active Support Cache events
+      # Tracks cache efficiency and performance
+      class Cache < Base
+        def initialize(configuration)
+          super
+          @cache_analyzer = Analyzers::CacheEfficiency.new
+        end
+
+        def process(event_data)
+          case event_data[:name]
+          when 'cache_read.active_support'
+            handle_read(event_data)
+          when 'cache_read_multi.active_support'
+            handle_read_multi(event_data)
+          when 'cache_generate.active_support'
+            handle_generate(event_data)
+          when 'cache_fetch_hit.active_support'
+            handle_fetch_hit(event_data)
+          when 'cache_write.active_support'
+            handle_write(event_data)
+          when 'cache_write_multi.active_support'
+            handle_write_multi(event_data)
+          when 'cache_increment.active_support'
+            handle_increment(event_data)
+          when 'cache_decrement.active_support'
+            handle_decrement(event_data)
+          when 'cache_delete.active_support'
+            handle_delete(event_data)
+          when 'cache_delete_multi.active_support'
+            handle_delete_multi(event_data)
+          when 'cache_delete_matched.active_support'
+            handle_delete_matched(event_data)
+          when 'cache_cleanup.active_support'
+            handle_cleanup(event_data)
+          when 'cache_prune.active_support'
+            handle_prune(event_data)
+          when 'cache_exist?.active_support'
+            handle_exist(event_data)
+          when 'message_serializer_fallback.active_support'
+            handle_serializer_fallback(event_data)
+          end
+
+          # Track cache efficiency if enabled
+          if @configuration.cache_efficiency_tracking
+            @cache_analyzer.track(event_data)
+          end
+        end
+
+        private
+
+        def handle_read(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          store = payload[:store]
+          hit = payload[:hit]
+          duration_ms = event_data[:duration_ms]
+
+          # === PULSE: Cache read span ===
+          send_to_pulse(event_data, {
+            name: "cache.read",
+            category: 'cache.read',
+            attributes: {
+              key: truncate_key(key),
+              store: store,
+              hit: hit,
+              super_operation: payload[:super_operation]
+            }
+          })
+
+          # === FLUX: Metrics ===
+          tags = { store: store }
+          send_to_flux(:increment, 'rails.cache.reads', 1, tags)
+          send_to_flux(:increment, hit ? 'rails.cache.hits' : 'rails.cache.misses', 1, tags)
+          send_to_flux(:timing, 'rails.cache.read_ms', duration_ms, tags)
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Cache #{hit ? 'hit' : 'miss'}: #{truncate_key(key)}",
+            category: 'cache.read',
+            level: :debug,
+            data: {
+              key: truncate_key(key),
+              hit: hit,
+              duration_ms: duration_ms
+            }
+          )
+        end
+
+        def handle_read_multi(event_data)
+          payload = event_data[:payload]
+          keys = payload[:key] || []
+          store = payload[:store]
+          hits = payload[:hits] || []
+          duration_ms = event_data[:duration_ms]
+
+          hit_count = hits.size
+          miss_count = keys.size - hit_count
+          hit_rate = keys.size > 0 ? (hit_count.to_f / keys.size * 100).round(1) : 0
+
+          # === PULSE: Multi-read span ===
+          send_to_pulse(event_data, {
+            name: "cache.read_multi",
+            category: 'cache.read',
+            attributes: {
+              key_count: keys.size,
+              hit_count: hit_count,
+              miss_count: miss_count,
+              hit_rate: hit_rate,
+              store: store
+            }
+          })
+
+          # === FLUX: Metrics ===
+          tags = { store: store }
+          send_to_flux(:increment, 'rails.cache.multi_reads', 1, tags)
+          send_to_flux(:increment, 'rails.cache.hits', hit_count, tags)
+          send_to_flux(:increment, 'rails.cache.misses', miss_count, tags)
+          send_to_flux(:histogram, 'rails.cache.multi_read_keys', keys.size, tags)
+          send_to_flux(:timing, 'rails.cache.read_multi_ms', duration_ms, tags)
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Cache multi-read: #{keys.size} keys (#{hit_rate}% hit rate)",
+            category: 'cache.read',
+            level: :debug,
+            data: {
+              key_count: keys.size,
+              hit_count: hit_count,
+              hit_rate: hit_rate
+            }
+          )
+        end
+
+        def handle_generate(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          store = payload[:store]
+          duration_ms = event_data[:duration_ms]
+
+          # This fires on cache miss + block execution
+          # === PULSE: Cache generate span ===
+          send_to_pulse(event_data, {
+            name: "cache.generate",
+            category: 'cache.generate',
+            attributes: {
+              key: truncate_key(key),
+              store: store
+            }
+          })
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.generates', 1, { store: store })
+          send_to_flux(:timing, 'rails.cache.generate_ms', duration_ms, { store: store })
+
+          # Flag slow cache generations
+          if duration_ms > 100
+            send_to_recall(:warn, "Slow cache generation", {
+              key: truncate_key(key),
+              duration_ms: duration_ms
+            })
+          end
+        end
+
+        def handle_fetch_hit(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          store = payload[:store]
+
+          # === FLUX: Fetch hit metrics ===
+          send_to_flux(:increment, 'rails.cache.fetch_hits', 1, { store: store })
+        end
+
+        def handle_write(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          store = payload[:store]
+          duration_ms = event_data[:duration_ms]
+
+          # === PULSE: Cache write span ===
+          send_to_pulse(event_data, {
+            name: "cache.write",
+            category: 'cache.write',
+            attributes: {
+              key: truncate_key(key),
+              store: store
+            }
+          })
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.writes', 1, { store: store })
+          send_to_flux(:timing, 'rails.cache.write_ms', duration_ms, { store: store })
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Cache write: #{truncate_key(key)}",
+            category: 'cache.write',
+            level: :debug,
+            data: {
+              key: truncate_key(key),
+              duration_ms: duration_ms
+            }
+          )
+        end
+
+        def handle_write_multi(event_data)
+          payload = event_data[:payload]
+          keys = payload[:key]&.keys || []
+          store = payload[:store]
+          duration_ms = event_data[:duration_ms]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.multi_writes', 1, { store: store })
+          send_to_flux(:histogram, 'rails.cache.multi_write_keys', keys.size, { store: store })
+          send_to_flux(:timing, 'rails.cache.write_multi_ms', duration_ms, { store: store })
+        end
+
+        def handle_increment(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          amount = payload[:amount]
+          store = payload[:store]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.increments', 1, { store: store })
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Cache increment: #{truncate_key(key)} by #{amount}",
+            category: 'cache.counter',
+            level: :debug,
+            data: { key: truncate_key(key), amount: amount }
+          )
+        end
+
+        def handle_decrement(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          amount = payload[:amount]
+          store = payload[:store]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.decrements', 1, { store: store })
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Cache decrement: #{truncate_key(key)} by #{amount}",
+            category: 'cache.counter',
+            level: :debug,
+            data: { key: truncate_key(key), amount: amount }
+          )
+        end
+
+        def handle_delete(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          store = payload[:store]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.deletes', 1, { store: store })
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Cache delete: #{truncate_key(key)}",
+            category: 'cache.delete',
+            level: :debug,
+            data: { key: truncate_key(key) }
+          )
+        end
+
+        def handle_delete_multi(event_data)
+          payload = event_data[:payload]
+          keys = payload[:key] || []
+          store = payload[:store]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.multi_deletes', 1, { store: store })
+          send_to_flux(:histogram, 'rails.cache.multi_delete_keys', keys.size, { store: store })
+        end
+
+        def handle_delete_matched(event_data)
+          payload = event_data[:payload]
+          pattern = payload[:key]
+          store = payload[:store]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.pattern_deletes', 1, { store: store })
+
+          # === RECALL: Log pattern delete ===
+          send_to_recall(:info, "Cache pattern delete", {
+            pattern: pattern.to_s,
+            store: store
+          })
+        end
+
+        def handle_cleanup(event_data)
+          payload = event_data[:payload]
+          store = payload[:store]
+          size = payload[:size]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.cleanups', 1, { store: store })
+          send_to_flux(:gauge, 'rails.cache.size_before_cleanup', size, { store: store })
+
+          # === RECALL: Log cleanup ===
+          send_to_recall(:info, "Cache cleanup", {
+            store: store,
+            size_before: size
+          })
+        end
+
+        def handle_prune(event_data)
+          payload = event_data[:payload]
+          store = payload[:store]
+          target_size = payload[:key]
+          from_size = payload[:from]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.prunes', 1, { store: store })
+          send_to_flux(:gauge, 'rails.cache.prune_from', from_size, { store: store })
+          send_to_flux(:gauge, 'rails.cache.prune_target', target_size, { store: store })
+
+          # === RECALL: Log prune ===
+          send_to_recall(:info, "Cache prune", {
+            store: store,
+            from_bytes: from_size,
+            target_bytes: target_size
+          })
+        end
+
+        def handle_exist(event_data)
+          payload = event_data[:payload]
+          key = payload[:key]
+          store = payload[:store]
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.exist_checks', 1, { store: store })
+        end
+
+        def handle_serializer_fallback(event_data)
+          payload = event_data[:payload]
+          serializer = payload[:serializer]
+          fallback = payload[:fallback]
+          duration_ms = event_data[:duration_ms]
+
+          # === RECALL: Warn about serializer fallback ===
+          send_to_recall(:warn, "Message serializer fallback", {
+            serializer: serializer.to_s,
+            fallback: fallback.to_s,
+            duration_ms: duration_ms
+          })
+
+          # === REFLEX: Breadcrumb ===
+          add_breadcrumb(
+            "Serializer fallback: #{serializer} -> #{fallback}",
+            category: 'cache.serializer',
+            level: :warning,
+            data: {
+              serializer: serializer.to_s,
+              fallback: fallback.to_s
+            }
+          )
+
+          # === FLUX: Metrics ===
+          send_to_flux(:increment, 'rails.cache.serializer_fallbacks', 1, {
+            serializer: serializer.to_s,
+            fallback: fallback.to_s
+          })
+        end
+
+        def truncate_key(key, max_length = 100)
+          return '' if key.nil?
+
+          key_str = key.to_s
+          key_str.length > max_length ? "#{key_str[0, max_length]}..." : key_str
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/rails/configuration.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Rails
+    class Configuration
+      # Product routing - which products receive which events
+      attr_accessor :pulse_enabled      # APM tracing
+      attr_accessor :recall_enabled     # Structured logging
+      attr_accessor :reflex_enabled     # Error tracking
+      attr_accessor :flux_enabled       # Metrics
+      attr_accessor :nerve_enabled      # Job monitoring
+
+      # Collector settings
+      attr_accessor :action_controller_enabled
+      attr_accessor :action_view_enabled
+      attr_accessor :active_record_enabled
+      attr_accessor :active_job_enabled
+      attr_accessor :action_cable_enabled
+      attr_accessor :action_mailer_enabled
+      attr_accessor :active_storage_enabled
+      attr_accessor :cache_enabled
+
+      # Analyzer settings
+      attr_accessor :n_plus_one_detection
+      attr_accessor :slow_query_threshold_ms
+      attr_accessor :cache_efficiency_tracking
+
+      # Filtering
+      attr_accessor :ignored_actions        # Controller actions to ignore
+      attr_accessor :ignored_sql_patterns   # SQL patterns to ignore (e.g., SCHEMA queries)
+      attr_accessor :ignored_job_classes    # Job classes to ignore
+
+      # Sampling
+      attr_accessor :sample_rate            # 0.0 to 1.0, percentage of events to capture
+
+      # Performance
+      attr_accessor :async_processing       # Process events asynchronously
+      attr_accessor :batch_size             # Batch events before sending
+      attr_accessor :flush_interval_ms      # Flush interval for batched events
+
+      def initialize
+        # Default: all products enabled (respects main SDK settings)
+        @pulse_enabled = true
+        @recall_enabled = true
+        @reflex_enabled = true
+        @flux_enabled = true
+        @nerve_enabled = true
+
+        # Default: all collectors enabled
+        @action_controller_enabled = true
+        @action_view_enabled = true
+        @active_record_enabled = true
+        @active_job_enabled = true
+        @action_cable_enabled = true
+        @action_mailer_enabled = true
+        @active_storage_enabled = true
+        @cache_enabled = true
+
+        # Default: analyzers enabled with sensible thresholds
+        @n_plus_one_detection = true
+        @slow_query_threshold_ms = 100
+        @cache_efficiency_tracking = true
+
+        # Default: ignore common noise
+        @ignored_actions = []
+        @ignored_sql_patterns = [
+          /\ASELECT.*FROM.*schema_migrations/i,
+          /\ASELECT.*FROM.*ar_internal_metadata/i
+        ]
+        @ignored_job_classes = []
+
+        # Default: capture everything
+        @sample_rate = 1.0
+
+        # Default: async with batching
+        @async_processing = true
+        @batch_size = 100
+        @flush_interval_ms = 1000
+      end
+
+      def pulse_effectively_enabled?
+        @pulse_enabled && BrainzLab.configuration&.pulse_effectively_enabled?
+      end
+
+      def recall_effectively_enabled?
+        @recall_enabled && BrainzLab.configuration&.recall_effectively_enabled?
+      end
+
+      def reflex_effectively_enabled?
+        @reflex_enabled && BrainzLab.configuration&.reflex_effectively_enabled?
+      end
+
+      def flux_effectively_enabled?
+        @flux_enabled && BrainzLab.configuration&.flux_enabled
+      end
+
+      def nerve_effectively_enabled?
+        @nerve_enabled
+      end
+
+      def should_sample?
+        return true if @sample_rate >= 1.0
+        return false if @sample_rate <= 0.0
+
+        rand < @sample_rate
+      end
+
+      def ignored_action?(controller, action)
+        @ignored_actions.include?("#{controller}##{action}")
+      end
+
+      def ignored_sql?(sql)
+        @ignored_sql_patterns.any? { |pattern| sql.match?(pattern) }
+      end
+
+      def ignored_job?(job_class)
+        @ignored_job_classes.include?(job_class.to_s)
+      end
+    end
+  end
+end

data/lib/brainzlab/rails/event_router.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Rails
+    # Routes Rails instrumentation events to appropriate BrainzLab products
+    # Each event can be sent to multiple products based on its type
+    class EventRouter
+      attr_reader :configuration, :collectors
+
+      def initialize(configuration)
+        @configuration = configuration
+        @collectors = initialize_collectors
+      end
+
+      def route(event_data)
+        event_name = event_data[:name]
+        collector = collector_for(event_name)
+
+        return unless collector
+
+        # Collector processes and routes to products
+        collector.process(event_data)
+      end
+
+      private
+
+      def initialize_collectors
+        {
+          action_controller: Collectors::ActionController.new(@configuration),
+          action_view: Collectors::ActionView.new(@configuration),
+          active_record: Collectors::ActiveRecord.new(@configuration),
+          active_job: Collectors::ActiveJob.new(@configuration),
+          action_cable: Collectors::ActionCable.new(@configuration),
+          action_mailer: Collectors::ActionMailer.new(@configuration),
+          active_storage: Collectors::ActiveStorage.new(@configuration),
+          cache: Collectors::Cache.new(@configuration)
+        }
+      end
+
+      def collector_for(event_name)
+        case event_name
+        when /\.action_controller$/
+          @collectors[:action_controller] if @configuration.action_controller_enabled
+        when /\.action_view$/
+          @collectors[:action_view] if @configuration.action_view_enabled
+        when /\.active_record$/
+          @collectors[:active_record] if @configuration.active_record_enabled
+        when /\.active_job$/
+          @collectors[:active_job] if @configuration.active_job_enabled
+        when /\.action_cable$/
+          @collectors[:action_cable] if @configuration.action_cable_enabled
+        when /\.action_mailer$/, /\.action_mailbox$/
+          @collectors[:action_mailer] if @configuration.action_mailer_enabled
+        when /\.active_storage$/
+          @collectors[:active_storage] if @configuration.active_storage_enabled
+        when /cache.*\.active_support$/, /message_serializer_fallback\.active_support$/
+          @collectors[:cache] if @configuration.cache_enabled
+        when /\.action_dispatch$/
+          @collectors[:action_controller] if @configuration.action_controller_enabled
+        when /deprecation\.rails$/, /\.railties$/
+          # Route deprecations to Recall for logging
+          @collectors[:action_controller] if @configuration.action_controller_enabled
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/rails/railtie.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Rails
+    # Railtie for automatic Rails integration
+    # Automatically starts instrumentation when Rails boots
+    class Railtie < ::Rails::Railtie
+      config.brainzlab_rails = ActiveSupport::OrderedOptions.new
+
+      # Initialize after Rails and BrainzLab SDK are configured
+      initializer 'brainzlab_rails.setup', after: :load_config_initializers do |app|
+        # Configure from Rails config if provided
+        BrainzLab::Rails.configure do |config|
+          rails_config = app.config.brainzlab_rails
+
+          # Copy any Rails-level configuration
+          config.pulse_enabled = rails_config.pulse_enabled if rails_config.key?(:pulse_enabled)
+          config.recall_enabled = rails_config.recall_enabled if rails_config.key?(:recall_enabled)
+          config.reflex_enabled = rails_config.reflex_enabled if rails_config.key?(:reflex_enabled)
+          config.flux_enabled = rails_config.flux_enabled if rails_config.key?(:flux_enabled)
+          config.nerve_enabled = rails_config.nerve_enabled if rails_config.key?(:nerve_enabled)
+
+          # Collector settings
+          config.action_controller_enabled = rails_config.action_controller_enabled if rails_config.key?(:action_controller_enabled)
+          config.action_view_enabled = rails_config.action_view_enabled if rails_config.key?(:action_view_enabled)
+          config.active_record_enabled = rails_config.active_record_enabled if rails_config.key?(:active_record_enabled)
+          config.active_job_enabled = rails_config.active_job_enabled if rails_config.key?(:active_job_enabled)
+          config.action_cable_enabled = rails_config.action_cable_enabled if rails_config.key?(:action_cable_enabled)
+          config.action_mailer_enabled = rails_config.action_mailer_enabled if rails_config.key?(:action_mailer_enabled)
+          config.active_storage_enabled = rails_config.active_storage_enabled if rails_config.key?(:active_storage_enabled)
+          config.cache_enabled = rails_config.cache_enabled if rails_config.key?(:cache_enabled)
+
+          # Analyzer settings
+          config.n_plus_one_detection = rails_config.n_plus_one_detection if rails_config.key?(:n_plus_one_detection)
+          config.slow_query_threshold_ms = rails_config.slow_query_threshold_ms if rails_config.key?(:slow_query_threshold_ms)
+          config.cache_efficiency_tracking = rails_config.cache_efficiency_tracking if rails_config.key?(:cache_efficiency_tracking)
+
+          # Filtering
+          config.ignored_actions = rails_config.ignored_actions if rails_config.key?(:ignored_actions)
+          config.ignored_sql_patterns = rails_config.ignored_sql_patterns if rails_config.key?(:ignored_sql_patterns)
+          config.ignored_job_classes = rails_config.ignored_job_classes if rails_config.key?(:ignored_job_classes)
+
+          # Sampling
+          config.sample_rate = rails_config.sample_rate if rails_config.key?(:sample_rate)
+        end
+      end
+
+      # Start instrumentation when Rails is ready
+      config.after_initialize do
+        # Only start if BrainzLab SDK is configured
+        # Check for either secret_key (legacy) or any product enabled with auto-provisioning
+        if sdk_configured?
+          BrainzLab::Rails.start!
+          ::Rails.logger.info '[BrainzLab::Rails] Instrumentation started (SDK Rails events delegated)'
+        else
+          ::Rails.logger.warn '[BrainzLab::Rails] BrainzLab SDK not configured, skipping instrumentation'
+        end
+      end
+
+      def self.sdk_configured?
+        config = BrainzLab.configuration
+        return false unless config
+
+        # Check for secret_key (set directly or by auto-provisioning)
+        return true if config.secret_key.to_s.strip.length.positive?
+
+        # Check if any product can auto-provision
+        # Products with auto_provision + master_key will provision on first use
+        products_with_auto = %i[recall reflex pulse flux]
+        has_auto_provision = products_with_auto.any? do |product|
+          enabled = config.send("#{product}_enabled")
+          can_provision = config.send("#{product}_auto_provision") &&
+                          config.send("#{product}_master_key").to_s.strip.length.positive? &&
+                          config.app_name.to_s.strip.length.positive?
+          enabled && can_provision
+        end
+        return true if has_auto_provision
+
+        # Check for direct API keys
+        direct_keys = {
+          reflex: :reflex_api_key,
+          pulse: :pulse_api_key,
+          flux: :flux_api_key
+        }
+        direct_keys.any? do |product, key_method|
+          config.send("#{product}_enabled") &&
+            config.send(key_method).to_s.strip.length.positive?
+        end
+      end
+
+      # Expose configuration in Rails console
+      console do
+        puts '[BrainzLab::Rails] Rails instrumentation active'
+        puts "  Hit rate: #{BrainzLab::Rails.subscriber&.event_router&.collectors&.dig(:cache)&.instance_variable_get(:@cache_analyzer)&.hit_rate}%" rescue nil
+      end
+    end
+  end
+end