solid_observer 0.3.0 → 0.5.0

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,346 @@
+# 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)
+            @error_count = error_count.to_i
+            @slow_count = slow_count.to_i
+            @latest_recorded_at = latest_recorded_at
+          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
+          error_count, slow_count, latest_recorded_at = SolidObserver::CacheEvent.where(recorded_at: window_range).pick(
+            Arel.sql("COUNT(CASE WHEN #{error_condition_sql} THEN 1 END)"),
+            Arel.sql("COUNT(CASE WHEN #{slow_condition_sql} THEN 1 END)"),
+            Arel.sql("MAX(CASE WHEN #{tracked_condition_sql} THEN recorded_at END)")
+          )
+
+          EventCounts.new(
+            error_count: error_count,
+            slow_count: slow_count,
+            latest_recorded_at: latest_recorded_at
+          )
+        end
+
+        def window_range
+          (current_time - window)..current_time
+        end
+
+        def tracked_condition_sql
+          "(#{error_condition_sql}) OR (#{slow_condition_sql})"
+        end
+
+        def error_condition_sql
+          "error_class IS NOT NULL AND TRIM(error_class) != ''"
+        end
+
+        def slow_condition_sql
+          "(error_class IS NULL OR TRIM(error_class) = '') AND duration >= #{slow_threshold}"
+        end
+
+        def slow_threshold
+          SolidObserver.config.cache_slow_threshold.to_f
+        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
+        Rails.logger&.error("[SolidObserver] CacheStats call failed: #{error.class} #{error.message}") if defined?(Rails)
+        error_response
+      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
+        {
+          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: "Service temporarily unavailable"
+        }
+      end
+    end
+  end
+end

data/lib/solid_observer/services/cleanup_storage.rb

@@ -1,10 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "database_size"
+require_relative "storage_info_snapshot"
 
 module SolidObserver
   module Services
     class CleanupStorage
+      MAINTENANCE_STATEMENT_BUILDERS = {
+        "sqlite" => ->(_tables) { ["VACUUM"] },
+        "postgresql" => ->(tables) { tables.map { |table_name| "VACUUM ANALYZE #{table_name}" } },
+        "mysql2" => ->(tables) { ["OPTIMIZE TABLE #{tables.join(", ")}"] },
+        "trilogy" => ->(tables) { ["OPTIMIZE TABLE #{tables.join(", ")}"] }
+      }.freeze
+
       def self.call
         new.call
       end
@@ -12,100 +20,143 @@ module SolidObserver
       def call
         return 0 if SolidObserver.config.realtime_mode?
 
-        deleted_count = perform_cleanup_transaction
-        post_cleanup(deleted_count)
-      rescue => e
-        handle_cleanup_failure(e)
+        post_cleanup(cleanup_counts)
+      rescue => error
+        handle_cleanup_failure(error)
       end
 
       private
 
+      def cleanup_counts
+        perform_cleanup.tap { record_snapshot_after_cleanup }
+      end
+
       def handle_cleanup_failure(error)
         Rails.logger.error "[SolidObserver] Cleanup failed: #{error.message}"
         raise
       end
 
-      def perform_cleanup_transaction
-        QueueEvent.transaction do
-          deleted_count = delete_old_events
-          record_snapshot_after_cleanup
-          deleted_count
-        end
+      def perform_cleanup
+        config = SolidObserver.config
+        event_cutoff = config.event_retention.ago
+
+        {
+          queue_events: QueueEvent.transaction do
+            QueueEvent.where("recorded_at < ?", event_cutoff).delete_all
+          end,
+          cache_events: delete_telemetry_records(
+            SolidObserver::CacheEvent,
+            column: :recorded_at,
+            cutoff: event_cutoff
+          ),
+          cache_metrics: delete_telemetry_records(
+            SolidObserver::CacheMetric,
+            column: :period_start,
+            cutoff: config.metrics_retention.ago
+          )
+        }
       end
 
-      def post_cleanup(deleted_count)
+      def post_cleanup(cleanup_counts)
         vacuum_database
         check_storage_warnings
-        log_results(deleted_count)
-        deleted_count
+        log_results(cleanup_counts)
+        cleanup_counts.values.sum
       end
 
-      def delete_old_events
-        cutoff = SolidObserver.config.event_retention.ago
-        QueueEvent.where("recorded_at < ?", cutoff).delete_all
+      def delete_telemetry_records(model, column:, cutoff:)
+        return 0 unless data_source_available?(model)
+
+        model.where("#{column} < ?", cutoff).delete_all
       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
 
       def vacuum_database
-        statement = maintenance_statement
-        return unless statement
-
-        QueueEvent.connection.execute(statement)
-      rescue => e
-        Rails.logger.warn "[SolidObserver] Database maintenance failed: #{e.message}"
+        maintenance_statements.each do |statement|
+          QueueEvent.connection.execute(statement)
+        end
+      rescue => error
+        Rails.logger.warn "[SolidObserver] Database maintenance failed: #{error.message}"
       end
 
       def check_storage_warnings
         current_size = current_database_size
-        return unless warning_needed?(current_size)
+        return unless current_size
+        return unless current_size > (SolidObserver.config.max_db_size * SolidObserver.config.warning_threshold)
 
         Rails.logger.warn(storage_warning_message(current_size))
       end
 
-      def warning_needed?(current_size)
-        return false unless current_size
-
-        config = SolidObserver.config
-        max_size = config.max_db_size
-        threshold = config.warning_threshold
-        current_size > (max_size * threshold)
-      end
-
       def storage_warning_message(current_size)
         max_size = SolidObserver.config.max_db_size
         percentage = ((current_size.to_f / max_size) * 100).round(1)
-        current_size_human = human_size(current_size)
-        max_size_human = human_size(max_size)
+        current_size_human = ActiveSupport::NumberHelper.number_to_human_size(
+          current_size,
+          precision: 1,
+          significant: false,
+          strip_insignificant_zeros: false
+        )
+        max_size_human = ActiveSupport::NumberHelper.number_to_human_size(
+          max_size,
+          precision: 1,
+          significant: false,
+          strip_insignificant_zeros: false
+        )
         "[SolidObserver] Queue DB approaching limit: #{current_size_human} / #{max_size_human} (#{percentage}%)"
       end
 
-      def human_size(bytes)
-        ActiveSupport::NumberHelper.number_to_human_size(bytes, precision: 1, significant: false, strip_insignificant_zeros: false)
-      end
-
       def current_database_size
         return @current_database_size if defined?(@current_database_size)
 
         @current_database_size = DatabaseSize.call(connection: QueueEvent.connection)
       end
 
-      def log_results(deleted_count)
-        Rails.logger.info "[SolidObserver] Cleaned #{deleted_count} queue events"
+      def log_results(cleanup_counts)
+        Rails.logger.info(
+          "[SolidObserver] Cleaned #{cleanup_counts[:queue_events]} queue events, " \
+          "#{cleanup_counts[:cache_events]} cache events, " \
+          "#{cleanup_counts[:cache_metrics]} cache metrics"
+        )
       end
 
-      def maintenance_statement
-        case QueueEvent.connection.adapter_name.downcase
-        when "sqlite" then "VACUUM"
-        when "postgresql" then "VACUUM ANALYZE solid_observer_queue_events"
-        when "mysql2", "trilogy" then "OPTIMIZE TABLE solid_observer_queue_events"
+      def maintenance_statements
+        tables = [QueueEvent, SolidObserver::CacheEvent, SolidObserver::CacheMetric].filter_map do |model|
+          model.table_name if data_source_available?(model)
         end
+        return [] if tables.empty?
+
+        MAINTENANCE_STATEMENT_BUILDERS.fetch(QueueEvent.connection.adapter_name.downcase, ->(_known_tables) { [] }).call(tables)
+      end
+
+      def data_source_available?(model)
+        table_name = model.table_name.to_s
+        return false if table_name.empty?
+
+        model.connection.data_source_exists?(table_name)
+      rescue *StorageInfoSnapshot::CONNECTION_ERRORS, TypeError
+        false
       end
     end
   end