solid_observer 0.3.0 → 0.4.0

data/lib/solid_observer/engine.rb

@@ -1,20 +1,38 @@
 # frozen_string_literal: true
 
+require_relative "cache_event_buffer"
+require_relative "cache_subscriber"
+require_relative "services/record_cache_event"
+require_relative "services/record_cache_metric"
+require_relative "services/flush_cache_event_buffer"
+require_relative "services/cache_stats"
+require_relative "services/cache_operations"
+
 module SolidObserver
   class Engine < ::Rails::Engine
     isolate_namespace SolidObserver
 
+    SOLID_QUEUE_AVAILABLE = defined?(::SolidQueue)
+    SOLID_CACHE_AVAILABLE = defined?(::SolidCache)
+
     middleware.use ActionDispatch::Cookies
     middleware.use ActionDispatch::Session::CookieStore, key: "_solid_observer_session"
     middleware.use ActionDispatch::Flash
 
     class << self
       def check_solid_queue_availability
-        return if defined?(SolidQueue)
+        return if defined?(::SolidQueue)
 
         Rails.logger.warn "[SolidObserver] SolidQueue not detected. Queue observability features will be limited."
       end
 
+      def check_solid_cache_availability
+        return if defined?(::SolidCache)
+        return unless SolidObserver.config.observe_cache
+
+        Rails.logger.warn "[SolidObserver] SolidCache not detected. Cache observability features will be disabled."
+      end
+
       def check_ui_authentication
         Services::UiAuthCheck.call(config: SolidObserver.config)
       end
@@ -28,10 +46,11 @@ module SolidObserver
 
       def activate_subscribers
         return activate_subscribers_in_realtime if SolidObserver.config.realtime_mode?
-        return if activation_skipped_for_table_status?
+        return if activation_skipped_for_table_status_for_enabled_components?
 
         Rails.logger.info "[SolidObserver] Activating event subscribers"
-        Subscriber.subscribe!
+        Subscriber.subscribe! if should_activate_queue_subscriber?
+        CacheSubscriber.subscribe! if should_activate_cache_subscriber?
       end
 
       private
@@ -54,13 +73,22 @@ module SolidObserver
 
       def activate_subscribers_in_realtime
         Rails.logger.info "[SolidObserver] Starting in real-time mode (no persistence)"
-        Subscriber.subscribe!
+        Subscriber.subscribe! if should_activate_queue_subscriber?
+        CacheSubscriber.subscribe! if should_activate_cache_subscriber?
+      end
+
+      def activation_skipped_for_table_status_for_enabled_components?
+        enabled_tables = []
+        enabled_tables << "solid_observer_queue_events" if should_activate_queue_subscriber?
+        enabled_tables << "solid_observer_cache_events" if should_activate_cache_subscriber?
+
+        enabled_tables.any? { |table_name| skip_activation_for_missing_table?(table_name) }
       end
 
-      def activation_skipped_for_table_status?
-        case table_status("solid_observer_queue_events")
+      def skip_activation_for_missing_table?(table_name)
+        case table_status(table_name)
         when :absent
-          log_activation_skip("Tables not found. Run: rails solid_observer:install:migrations && rails db:migrate")
+          log_activation_skip("Tables not found (missing: #{table_name}). Run: rails solid_observer:install:migrations && rails db:migrate")
           true
         when :unknown
           log_activation_skip("Database not reachable at boot. Skipping subscriber activation.")
@@ -70,6 +98,14 @@ module SolidObserver
         end
       end
 
+      def should_activate_queue_subscriber?
+        SolidObserver.config.solid_queue_enabled?
+      end
+
+      def should_activate_cache_subscriber?
+        SolidObserver.config.solid_cache_enabled?
+      end
+
       def log_activation_skip(message)
         Rails.logger.info("[SolidObserver] #{message}")
       end
@@ -109,6 +145,7 @@ module SolidObserver
 
     config.before_initialize do
       Engine.check_solid_queue_availability
+      Engine.check_solid_cache_availability
     end
 
     config.after_initialize do

data/lib/solid_observer/services/cache_operations.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Services
+    class CacheOperations
+      MESSAGES = {
+        clear: {
+          confirmation: "Clear all SolidCache entries? This evicts cached application data and may slow requests while the cache rebuilds. This cannot be undone.",
+          success: "Cache cleared successfully.",
+          failure: "Cache clear failed. SolidCache is unavailable or rejected the operation."
+        }.freeze,
+        prune: {
+          success: "Expired cache entries pruned successfully.",
+          failure: "Cache prune failed. SolidCache is unavailable or rejected the operation."
+        }.freeze,
+        unavailable: "Cache controls are unavailable because SolidCache is not enabled or not detected."
+      }.freeze
+
+      class << self
+        def available?
+          new.available?
+        end
+
+        def clear
+          new.clear
+        end
+
+        def prune
+          new.prune
+        end
+
+        def message(operation, key = nil)
+          return MESSAGES.fetch(:unavailable) if operation == :unavailable
+
+          MESSAGES.fetch(operation).fetch(key)
+        end
+
+        def unavailable_message
+          message(:unavailable)
+        end
+      end
+
+      def available?
+        SolidObserver.config.solid_cache_enabled? && compatible_store?
+      end
+
+      def clear
+        messages = self.class
+        return {ok: false, message: messages.unavailable_message} unless available?
+
+        perform_operation(
+          :clear,
+          success_message: messages.message(:clear, :success),
+          failure_message: messages.message(:clear, :failure)
+        ) do
+          cache_store.clear
+        end
+      end
+
+      def prune
+        messages = self.class
+        return {ok: false, message: messages.unavailable_message} unless available?
+
+        perform_operation(
+          :prune,
+          success_message: messages.message(:prune, :success),
+          failure_message: messages.message(:prune, :failure)
+        ) do
+          prune_with_fallback
+        end
+      end
+
+      private
+
+      def compatible_store?
+        defined?(::SolidCache::Store) && cache_store.is_a?(::SolidCache::Store)
+      end
+
+      def cache_store
+        Rails.cache
+      end
+
+      def perform_operation(name, success_message:, failure_message:)
+        yield
+        {ok: true, message: success_message}
+      rescue => error
+        log_failure(name, error)
+        {ok: false, message: failure_message}
+      end
+
+      def prune_with_fallback
+        cache_store.cleanup
+      rescue NotImplementedError
+        prune_with_solid_cache_fallback
+      end
+
+      def prune_with_solid_cache_fallback
+        cache_store.with_each_connection do
+          ::SolidCache::Entry.expire(
+            cache_store.expiry_batch_size,
+            max_age: cache_store.max_age,
+            max_entries: cache_store.max_entries,
+            max_size: cache_store.max_size
+          )
+        end
+      rescue NameError
+        raise "cleanup unsupported"
+      end
+
+      def log_failure(name, error)
+        Rails.logger&.warn("[SolidObserver] Cache #{name} failed: #{error.class}")
+      end
+    end
+  end
+end

data/lib/solid_observer/services/cache_stats.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Services
+    class CacheStats
+      RANGES = {
+        "15m" => 15.minutes,
+        "30m" => 30.minutes,
+        "1h" => 1.hour,
+        "7h" => 7.hours,
+        "1d" => 1.day,
+        "7d" => 7.days,
+        "14d" => 14.days
+      }.freeze
+      DEFAULT_RANGE = "15m"
+      ACTIVITY_TREND_EMPTY = {
+        available: false,
+        hit_rate: [],
+        operations: [],
+        errors: []
+      }.freeze
+      STABILITY_EMPTY = {
+        available: false,
+        state: :stable,
+        error_count: 0,
+        slow_count: 0,
+        latest_recorded_at: nil
+      }.freeze
+      BUCKET_RULES = [
+        [2.hours.to_i, 1.minute.to_i],
+        [1.day.to_i, 15.minutes.to_i],
+        [7.days.to_i, 2.hours.to_i]
+      ].freeze
+
+      class TrendData
+        class BucketSnapshot
+          attr_reader :operations_count, :hits_count, :misses_count, :errors_count
+
+          def initialize
+            @operations_count = 0
+            @hits_count = 0
+            @misses_count = 0
+            @errors_count = 0
+          end
+
+          def add(row)
+            @operations_count += row[1].to_i
+            @hits_count += row[2].to_i
+            @misses_count += row[3].to_i
+            @errors_count += row[4].to_i
+          end
+
+          def hit_rate
+            read_outcomes = hits_count + misses_count
+            return 0.0 if read_outcomes.zero?
+
+            hits_count.to_f / read_outcomes
+          end
+
+          def value_for(key)
+            public_send(key)
+          end
+        end
+
+        def initialize(metric_rows:, window:, current_time:)
+          @metric_rows = metric_rows
+          @window = window
+          @current_time = current_time
+        end
+
+        def to_h
+          return CacheStats::ACTIVITY_TREND_EMPTY.dup if metric_rows.empty?
+
+          buckets = blank_buckets
+          metric_rows.each do |row|
+            buckets[align_bucket(row[0].to_i)]&.add(row)
+          end
+
+          {
+            available: true,
+            hit_rate: hit_rate_series(buckets),
+            operations: count_series(buckets, :operations_count),
+            errors: count_series(buckets, :errors_count)
+          }
+        end
+
+        private
+
+        attr_reader :metric_rows, :window, :current_time
+
+        def blank_buckets
+          start_bucket = align_bucket((current_time - window).to_i)
+          end_bucket = align_bucket(current_time.to_i)
+
+          start_bucket.step(end_bucket, bucket_seconds).each_with_object({}) do |timestamp, buckets|
+            buckets[timestamp] = BucketSnapshot.new
+          end
+        end
+
+        def hit_rate_series(buckets)
+          buckets.map do |timestamp, totals|
+            {t: timestamp, v: totals.hit_rate}
+          end
+        end
+
+        def count_series(buckets, key)
+          buckets.map do |timestamp, totals|
+            {t: timestamp, v: totals.value_for(key)}
+          end
+        end
+
+        def bucket_seconds
+          seconds = window.to_i
+          CacheStats::BUCKET_RULES.find { |limit, _bucket| seconds <= limit }&.last || 4.hours.to_i
+        end
+
+        def align_bucket(value)
+          (value / bucket_seconds) * bucket_seconds
+        end
+      end
+
+      class StabilityData
+        class EventCounts
+          attr_reader :error_count, :slow_count, :latest_recorded_at
+
+          def initialize
+            @error_count = 0
+            @slow_count = 0
+            @latest_recorded_at = nil
+          end
+
+          def record(recorded_at:, error_class:, duration:)
+            kind = event_kind(error_class: error_class, duration: duration)
+            return unless kind
+
+            @latest_recorded_at = [latest_recorded_at, recorded_at].compact.max
+            @error_count += 1 if kind == :error
+            @slow_count += 1 if kind == :slow
+          end
+
+          def state
+            return :critical if error_count.positive?
+            return :degraded if slow_count.positive?
+
+            :stable
+          end
+
+          def to_h
+            {
+              available: true,
+              state: state,
+              error_count: error_count,
+              slow_count: slow_count,
+              latest_recorded_at: latest_recorded_at
+            }
+          end
+
+          private
+
+          def event_kind(error_class:, duration:)
+            return :error if error_class.present?
+            return :slow if duration.to_f >= SolidObserver.config.cache_slow_threshold.to_f
+
+            nil
+          end
+        end
+
+        def initialize(window:, current_time:)
+          @window = window
+          @current_time = current_time
+        end
+
+        def to_h
+          event_counts.to_h
+        rescue ActiveRecord::StatementInvalid
+          CacheStats::STABILITY_EMPTY.dup
+        end
+
+        private
+
+        attr_reader :window, :current_time
+
+        def event_counts
+          counts = EventCounts.new
+
+          SolidObserver::CacheEvent.where(recorded_at: window_range).pluck(
+            :recorded_at,
+            :duration,
+            :error_class
+          ).each do |recorded_at, duration, error_class|
+            counts.record(recorded_at: recorded_at, error_class: error_class, duration: duration)
+          end
+
+          counts
+        end
+
+        def window_range
+          (current_time - window)..current_time
+        end
+      end
+
+      class << self
+        def parse_range(value, fallback: DEFAULT_RANGE)
+          range_key = value.to_s
+          RANGES.key?(range_key) ? range_key : fallback
+        end
+
+        def range_duration(value, fallback: DEFAULT_RANGE)
+          RANGES.fetch(parse_range(value, fallback: fallback))
+        end
+      end
+
+      def self.call(window:)
+        new.call(window: window)
+      end
+
+      def call(window:)
+        current_time = Time.current
+        dashboard_response(window: window, current_time: current_time)
+      rescue => error
+        error_response(error.message)
+      end
+
+      private
+
+      def dashboard_response(window:, current_time:)
+        time_window = (current_time - window)..current_time
+        metric_rows = metric_rows(time_window: time_window)
+
+        build_response(
+          window: window,
+          totals: metric_totals(time_window: time_window),
+          dashboard_data: dashboard_data(window: window, current_time: current_time, metric_rows: metric_rows)
+        )
+      end
+
+      def build_response(window:, totals:, dashboard_data:)
+        operations_count, hits_count, misses_count, errors_count, duration_total = totals.values_at(
+          :operations_count,
+          :hits_count,
+          :misses_count,
+          :errors_count,
+          :duration_total
+        )
+        read_outcomes_count = hits_count + misses_count
+        window_minutes = [window.to_f / 60.0, 1.0].max
+
+        {
+          hit_rate: ratio(hits_count, read_outcomes_count),
+          throughput: operations_count.to_f / window_minutes,
+          error_rate: ratio(errors_count, operations_count),
+          avg_duration: ratio(duration_total, operations_count),
+          operations_count: operations_count,
+          hits_count: hits_count,
+          misses_count: misses_count,
+          errors_count: errors_count,
+          duration_total: duration_total,
+          activity_trends: dashboard_data[:activity_trends],
+          stability: dashboard_data[:stability]
+        }
+      end
+
+      def dashboard_data(window:, current_time:, metric_rows:)
+        {
+          activity_trends: TrendData.new(
+            metric_rows: metric_rows,
+            window: window,
+            current_time: current_time
+          ).to_h,
+          stability: StabilityData.new(window: window, current_time: current_time).to_h
+        }
+      end
+
+      def metric_rows(time_window:)
+        SolidObserver::CacheMetric.where(period_start: time_window).pluck(
+          :period_start,
+          :operations_count,
+          :hits_count,
+          :misses_count,
+          :errors_count,
+          :duration_total
+        )
+      end
+
+      def metric_totals(time_window:)
+        operations_count, hits_count, misses_count, errors_count, duration_total = SolidObserver::CacheMetric.where(
+          period_start: time_window
+        ).pick(
+          Arel.sql("COALESCE(SUM(operations_count), 0)"),
+          Arel.sql("COALESCE(SUM(hits_count), 0)"),
+          Arel.sql("COALESCE(SUM(misses_count), 0)"),
+          Arel.sql("COALESCE(SUM(errors_count), 0)"),
+          Arel.sql("COALESCE(SUM(duration_total), 0.0)")
+        )
+
+        {
+          operations_count: operations_count,
+          hits_count: hits_count,
+          misses_count: misses_count,
+          errors_count: errors_count,
+          duration_total: duration_total
+        }
+      end
+
+      def ratio(numerator, denominator)
+        return 0.0 if denominator.to_i.zero?
+
+        numerator.to_f / denominator
+      end
+
+      def error_response(message)
+        {
+          hit_rate: 0.0,
+          throughput: 0.0,
+          error_rate: 0.0,
+          avg_duration: 0.0,
+          operations_count: 0,
+          hits_count: 0,
+          misses_count: 0,
+          errors_count: 0,
+          duration_total: 0.0,
+          activity_trends: ACTIVITY_TREND_EMPTY.dup,
+          stability: STABILITY_EMPTY.dup,
+          error: message
+        }
+      end
+    end
+  end
+end

data/lib/solid_observer/services/cleanup_storage.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "database_size"
+require_relative "storage_info_snapshot"
 
 module SolidObserver
   module Services
@@ -46,10 +47,25 @@ module SolidObserver
       end
 
       def record_snapshot_after_cleanup
+        snapshots = StorageInfoSnapshot.call
+
         # StorageInfo.db_size_bytes is NOT NULL; record_snapshot coerces nil to 0.
+        StorageInfo.record_snapshot(db_size: current_database_size, event_count: QueueEvent.count)
+
+        snapshots.each do |snapshot|
+          record_component_snapshot(snapshot)
+        end
+      end
+
+      def record_component_snapshot(snapshot)
+        return unless snapshot[:available]
+        component = snapshot[:component]
+        return if component == "queue_observer"
+
         StorageInfo.record_snapshot(
-          db_size: current_database_size,
-          event_count: QueueEvent.count
+          component: component,
+          db_size: snapshot[:db_size_bytes],
+          event_count: snapshot[:event_count]
         )
       end
 

data/lib/solid_observer/services/database_size.rb

@@ -7,14 +7,15 @@ module SolidObserver
     # SQLite uses whole-database page accounting; PostgreSQL and MySQL/Trilogy
     # use table + index size from adapter-native system functions.
     class DatabaseSize
-      TABLE_NAME = "solid_observer_queue_events"
+      DEFAULT_TABLE_NAME = "solid_observer_queue_events"
 
-      def self.call(connection:)
-        new(connection).call
+      def self.call(connection:, table_name: DEFAULT_TABLE_NAME)
+        new(connection, table_name: table_name).call
       end
 
-      def initialize(connection)
+      def initialize(connection, table_name:)
         @connection = connection
+        @table_name = table_name
       end
 
       def call
@@ -26,7 +27,7 @@ module SolidObserver
 
       private
 
-      attr_reader :connection
+      attr_reader :connection, :table_name
 
       def adapter_key
         case connection.adapter_name.to_s.downcase
@@ -52,16 +53,20 @@ module SolidObserver
       end
 
       def sqlite_size
-        connection.query_value("SELECT pragma_page_count() * pragma_page_size()")&.to_i
+        page_count = connection.query_value("PRAGMA page_count")
+        page_size = connection.query_value("PRAGMA page_size")
+        return unless page_count && page_size
+
+        page_count.to_i * page_size.to_i
       end
 
       def postgresql_size
-        quoted_table = connection.quote(TABLE_NAME)
+        quoted_table = connection.quote(table_name)
         connection.query_value("SELECT pg_total_relation_size(#{quoted_table})")&.to_i
       end
 
       def mysql_size
-        quoted_table = connection.quote(TABLE_NAME)
+        quoted_table = connection.quote(table_name)
 
         connection.query_value(<<~SQL)&.to_i
           SELECT COALESCE(data_length + index_length, 0)

data/lib/solid_observer/services/flush_cache_event_buffer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Services
+    class FlushCacheEventBuffer
+      BATCH_SIZE = 100
+
+      def self.call(events)
+        new(events).call
+      end
+
+      def initialize(events)
+        @events = events
+      end
+
+      def call
+        return 0 if @events.empty?
+
+        insert_all_events
+        @events.size
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::StatementInvalid => error
+        fallback_insert_count(error)
+      end
+
+      private
+
+      def insert_all_events
+        CacheEvent.transaction { CacheEvent.insert_all!(@events) }
+      end
+
+      def fallback_insert_count(error)
+        Rails.logger&.error("[SolidObserver] Cache bulk insert failed, retrying in batches: #{error.message}") if defined?(Rails)
+        @events.each_slice(BATCH_SIZE).sum { |batch| insert_batch(batch) }
+      end
+
+      def insert_batch(batch)
+        size = batch.size
+        CacheEvent.insert_all(batch, returning: false)
+        size
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::StatementInvalid => error
+        handle_batch_insert_error(size, error)
+      end
+
+      def log_batch_warning(size, error)
+        Rails.logger&.warn("[SolidObserver] Failed to insert cache batch of #{size} events: #{error.message}") if defined?(Rails)
+      end
+
+      def handle_batch_insert_error(size, error)
+        log_batch_warning(size, error)
+        0
+      end
+    end
+  end
+end