solid_observer 0.4.0 → 0.6.0

data/lib/solid_observer/chart_buffer.rb

@@ -2,7 +2,40 @@
 
 module SolidObserver
   class ChartBuffer
+    CACHE_KEY = "solid_observer/chart_buffer/ready_samples"
     INSTANCE_MUTEX = Mutex.new
+    SAMPLE_CAP = 720
+    STORAGE_MUTEX = Mutex.new
+
+    class SampleWindow
+      def initialize(samples)
+        @samples = samples
+      end
+
+      def upsert(sample, cap:)
+        return replace_latest_sample(sample) if latest_sample_timestamp == sample[:t]
+
+        append_new_sample(sample, cap: cap)
+      end
+
+      private
+
+      def latest_sample_timestamp
+        @samples.last&.[](:t)
+      end
+
+      def replace_latest_sample(sample)
+        @samples[-1] = sample
+        @samples
+      end
+
+      def append_new_sample(sample, cap:)
+        @samples << sample
+        overflow = @samples.length - cap
+        @samples.shift(overflow) if overflow.positive?
+        @samples
+      end
+    end
 
     class << self
       def append(value, at: Time.now)
@@ -24,16 +57,12 @@ module SolidObserver
       end
     end
 
-    def initialize
-      @mutex = Mutex.new
-      @samples = []
-      @cap = nil
-    end
+    @fallback_samples = []
 
     def append(value, at: Time.now)
       sample = {t: at.to_i, v: value.to_i}
 
-      @mutex.synchronize { store_sample(sample) }
+      STORAGE_MUTEX.synchronize { persist_sample(sample) }
 
       sample
     end
@@ -41,43 +70,71 @@ module SolidObserver
     def recent(window_seconds)
       cutoff = Time.now.to_i - window_seconds.to_i
 
-      @mutex.synchronize do
-        @samples.select { |sample| sample[:t] >= cutoff }.map(&:dup)
+      STORAGE_MUTEX.synchronize do
+        load_samples.select { |sample| sample[:t] >= cutoff }.map(&:dup)
       end
     end
 
     def clear
-      @mutex.synchronize do
-        @samples.clear
-        @cap = nil
+      STORAGE_MUTEX.synchronize do
+        empty_samples = []
+        replace_fallback_samples(empty_samples)
+        cache_store&.delete(CACHE_KEY)
+      rescue
+        nil
       end
     end
 
     private
 
-    def store_sample(sample)
-      @cap ||= compute_cap
-      replace_or_append(sample)
-      trim_to_cap
+    def persist_sample(sample)
+      samples = SampleWindow.new(load_samples).upsert(sample, cap: SAMPLE_CAP)
+      write_samples(samples)
     end
 
-    def replace_or_append(sample)
-      latest_sample = @samples.last
+    def load_samples
+      normalize_samples(cache_store&.read(CACHE_KEY) || stored_fallback_samples)
+    rescue
+      stored_fallback_samples
+    end
 
-      if latest_sample && latest_sample[:t] == sample[:t]
-        @samples[-1] = sample
-      else
-        @samples << sample
-      end
+    def write_samples(samples)
+      normalized = normalize_samples(samples)
+
+      replace_fallback_samples(normalized.map(&:dup))
+      cache_store&.write(CACHE_KEY, normalized)
+    rescue
+      replace_fallback_samples(normalized)
     end
 
-    def trim_to_cap
-      overflow = @samples.length - @cap
-      @samples.shift(overflow) if overflow.positive?
+    def cache_store
+      return unless defined?(Rails)
+
+      Rails.cache
     end
 
-    def compute_cap
-      (3600 / 5).to_i # 720 samples — 1h at the 5s cadence
+    def stored_fallback_samples
+      normalize_samples(self.class.instance_variable_get(:@fallback_samples))
+    end
+
+    def replace_fallback_samples(samples)
+      self.class.instance_variable_set(:@fallback_samples, samples)
+    end
+
+    def normalize_samples(samples)
+      Array(samples).filter_map do |sample|
+        normalize_sample(sample)
+      end.last(SAMPLE_CAP)
+    end
+
+    def normalize_sample(sample)
+      return unless sample.is_a?(Hash)
+
+      timestamp = sample[:t] || sample["t"]
+      value = sample[:v] || sample["v"]
+      return unless timestamp && value
+
+      {t: timestamp.to_i, v: value.to_i}
     end
   end
 end

data/lib/solid_observer/cli/health.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Health < Base
+      STATUS_COLORS = {stable: :green, degraded: :yellow, critical: :red}.freeze
+      NAME_WIDTH = 8
+      UNAVAILABLE_SUFFIX = "  (unavailable)"
+
+      def call
+        health = SolidObserver::Services::HealthScore.call
+
+        print_header
+        print_overall(health[:overall])
+        print_components(health[:components])
+        output("")
+      end
+
+      private
+
+      def print_header
+        output("\n🩺 SolidObserver Health", color: :red)
+        output("=" * 50, color: :red)
+        output("")
+      end
+
+      def print_overall(overall)
+        output("Overall: #{overall}", color: STATUS_COLORS[overall])
+        output("")
+      end
+
+      def print_components(components)
+        return warning("⚠️  No components enabled") if components.empty?
+
+        output("Components", color: :green)
+        output("")
+        components.each { |name, entry| print_component(name, entry[:status], entry[:available]) }
+      end
+
+      # Renders the status verbatim: HealthScore owns the worst-of ladder, so an
+      # unrecognised status stays uncoloured rather than being coerced to stable.
+      # :reek:ControlParameter
+      def print_component(name, status, available)
+        suffix = available ? "" : UNAVAILABLE_SUFFIX
+        output("  #{name.to_s.ljust(NAME_WIDTH)}#{status}#{suffix}", color: STATUS_COLORS[status])
+      end
+    end
+  end
+end

data/lib/solid_observer/cli/trace.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Trace < Base
+      DETAIL_FORMATTERS = {
+        queue: :format_queue_details,
+        cache: :format_cache_details,
+        cable: :format_cable_details
+      }.freeze
+
+      EVENT_FORMATTERS = {
+        "cable_summary" => ->(row) { "and #{row[:collapsed_count]} more cable events" }
+      }.freeze
+
+      def call(correlation_id:, limit: nil)
+        return output("Trace unavailable in realtime mode.") if SolidObserver.config.realtime_mode?
+
+        result = SolidObserver::Queries::TraceQuery.new.call(correlation_id: correlation_id, limit: limit)
+        return warning("No events found for correlation_id: #{correlation_id}") if (rows = result.rows).empty?
+
+        print_trace_table(rows)
+        print_unavailable_components(result.unavailable_components)
+      end
+
+      private
+
+      def print_trace_table(rows)
+        print_section_header("Trace")
+        table(
+          headers: ["Time", "Component", "Event", "Details"],
+          rows: rows.map { |row| format_cells(row) }
+        )
+        output("")
+      end
+
+      def print_unavailable_components(unavailable)
+        unavailable.each { |component| warning("#{component} unavailable") }
+      end
+
+      def format_cells(row)
+        recorded_at, component, event_type = row.values_at(:recorded_at, :component, :event_type)
+        [
+          format_time(recorded_at),
+          component.to_s,
+          event_type,
+          format_details(row)
+        ]
+      end
+
+      def format_details(row)
+        event_type, component = row.values_at(:event_type, :component)
+        event_formatter = EVENT_FORMATTERS[event_type]
+        return event_formatter.call(row) if event_formatter
+
+        component_formatter = DETAIL_FORMATTERS[component]
+        send(component_formatter, row) if component_formatter
+      end
+
+      def format_queue_details(row)
+        job_class, queue_name, duration = row.values_at(:job_class, :queue_name, :duration)
+        [label("job", job_class), label("queue", queue_name), duration_part(duration)].compact.join(" ")
+      end
+
+      def format_cache_details(row)
+        hit, error_class, duration = row.values_at(:hit, :error_class, :duration)
+        [hit_part(hit), error_part(error_class), duration_part(duration)].compact.join(" ")
+      end
+
+      def format_cable_details(row)
+        channel_class, duration, error_class, collapsed_count = row.values_at(:channel_class, :duration, :error_class, :collapsed_count)
+        [label("channel", channel_class), error_part(error_class), duration_part(duration), ("collapsed=#{collapsed_count}" if collapsed_count)].compact.join(" ")
+      end
+
+      def label(name, value)
+        "#{name}=#{value}" if value
+      end
+
+      def error_part(error_class)
+        "error=#{error_class}" if error_class
+      end
+
+      def hit_part(hit)
+        "hit=#{hit}" if [true, false].include?(hit)
+      end
+
+      def duration_part(duration)
+        "duration=#{format_duration(duration)}" if duration
+      end
+
+      def format_duration(duration)
+        duration ? "#{duration.round(3)}s" : nil
+      end
+
+      def format_time(time)
+        time.strftime("%Y-%m-%d %H:%M:%S")
+      end
+
+      def print_section_header(title)
+        output("\n#{title}", color: :red)
+        output("=" * 50, color: :red)
+        output("")
+      end
+    end
+  end
+end

data/lib/solid_observer/configuration.rb

@@ -21,19 +21,20 @@ module SolidObserver
     # Observer Settings
     attr_accessor :observe_queue
 
-    # Observer Settings (planned for a future release)
-    # @note Cache and Cable observers are not yet implemented
+    # Cache & Cable Observer Settings
     attr_accessor :observe_cache,
       :observe_cable,
       :cache_sampling_rate,
       :cache_slow_threshold,
       :cache_store_errors
 
+    attr_reader :cable_rejection_threshold,
+      :cable_backlog_threshold,
+      :cable_error_threshold
+
     # Retention Settings
     attr_accessor :event_retention
 
-    # Retention Settings (planned for a future release)
-    # @note Metrics cleanup is not yet implemented
     attr_accessor :metrics_retention
 
     # Storage Settings
@@ -49,7 +50,8 @@ module SolidObserver
       :flush_interval,
       :max_buffer_size,
       :buffer_overflow_strategy,
-      :filter_cache_ttl
+      :filter_cache_ttl,
+      :cable_sampling_rate
 
     # Correlation Settings
     attr_accessor :correlation_id_generator
@@ -58,13 +60,16 @@ module SolidObserver
       @ui_enabled, @ui_base_controller, @ui_username, @ui_password,
         @storage_mode, @observe_queue, @observe_cache, @observe_cable,
         @event_retention, @metrics_retention, @max_db_size, @warning_threshold,
-        @sampling_rate, @cache_sampling_rate, @cache_slow_threshold, @cache_store_errors,
+        @sampling_rate, @cache_sampling_rate, @cable_sampling_rate, @cache_slow_threshold, @cache_store_errors,
+        @cable_rejection_threshold, @cable_backlog_threshold, @cable_error_threshold,
         @buffer_size, @flush_interval,
         @max_buffer_size, @buffer_overflow_strategy, @filter_cache_ttl,
         @correlation_id_generator = !production?, "::ApplicationController", nil, nil,
           :persistence, true, false, false,
           30.days, 90.days, 1.gigabyte, 0.8,
-          1.0, 0.1, 0.1, true, 1000, 10.seconds,
+          1.0, 0.1, 0.1, 0.1, true,
+          0.05, 0.10, 0.0,
+          1000, 10.seconds,
           10_000, :drop_old, 1.minute,
           nil
     end
@@ -95,6 +100,10 @@ module SolidObserver
       !!defined?(::SolidCache)
     end
 
+    def solid_cable_available?
+      !!defined?(::SolidCable)
+    end
+
     def solid_queue_enabled?
       observe_queue
     end
@@ -103,11 +112,35 @@ module SolidObserver
       observe_cache && solid_cache_available?
     end
 
+    def solid_cable_enabled?
+      observe_cable && solid_cable_available?
+    end
+
     def sampling_rate=(value)
       validate_rate!(:sampling_rate, value)
       @sampling_rate = value
     end
 
+    def cable_sampling_rate=(value)
+      validate_rate!(:cable_sampling_rate, value)
+      @cable_sampling_rate = value
+    end
+
+    def cable_rejection_threshold=(value)
+      validate_rate!(:cable_rejection_threshold, value)
+      @cable_rejection_threshold = value
+    end
+
+    def cable_backlog_threshold=(value)
+      validate_rate!(:cable_backlog_threshold, value)
+      @cable_backlog_threshold = value
+    end
+
+    def cable_error_threshold=(value)
+      validate_non_negative_numeric!(:cable_error_threshold, value)
+      @cable_error_threshold = value
+    end
+
     def warning_threshold=(value)
       validate_rate!(:warning_threshold, value)
       @warning_threshold = value
@@ -170,6 +203,13 @@ module SolidObserver
       end
     end
 
+    # :reek:FeatureEnvy
+    def validate_non_negative_numeric!(name, value)
+      unless value.is_a?(Numeric) && value >= 0
+        raise ArgumentError, "#{name} must be a non-negative number"
+      end
+    end
+
     def production?
       defined?(Rails) && Rails.env.production?
     end

data/lib/solid_observer/correlated.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Correlated
+    def self.included(base)
+      base.around_perform do |job, block|
+        SolidObserver::Correlated.stamp(job.job_id) { block.call }
+      end
+    end
+
+    def self.stamp(correlation_id)
+      thread_local = Thread.current
+      previous = thread_local[:solid_observer_correlation_id]
+      thread_local[:solid_observer_correlation_id] = correlation_id if correlation_id.present?
+
+      yield
+    ensure
+      thread_local[:solid_observer_correlation_id] = previous
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_job) { include SolidObserver::Correlated }

data/lib/solid_observer/engine.rb

@@ -1,20 +1,9 @@
 # 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
@@ -33,6 +22,13 @@ module SolidObserver
         Rails.logger.warn "[SolidObserver] SolidCache not detected. Cache observability features will be disabled."
       end
 
+      def check_solid_cable_availability
+        return if defined?(::SolidCable)
+        return unless SolidObserver.config.observe_cable
+
+        Rails.logger.warn "[SolidObserver] SolidCable not detected. Cable observability features will be disabled."
+      end
+
       def check_ui_authentication
         Services::UiAuthCheck.call(config: SolidObserver.config)
       end
@@ -46,16 +42,18 @@ module SolidObserver
 
       def activate_subscribers
         return activate_subscribers_in_realtime if SolidObserver.config.realtime_mode?
-        return if activation_skipped_for_table_status_for_enabled_components?
 
         Rails.logger.info "[SolidObserver] Activating event subscribers"
-        Subscriber.subscribe! if should_activate_queue_subscriber?
-        CacheSubscriber.subscribe! if should_activate_cache_subscriber?
+        activate_queue_subscriber
+        activate_cache_subscriber
+        activate_cable_subscriber
       end
 
       private
 
       def queue_db_config
+        return unless active_record_available?
+
         ActiveRecord::Base.configurations.configs_for(
           env_name: Rails.env,
           name: "solid_observer_queue"
@@ -67,34 +65,40 @@ module SolidObserver
           database: {writing: :solid_observer_queue, reading: :solid_observer_queue}
         }
 
-        SolidObserver::BaseEvent.connects_to(**connection_config)
-        SolidObserver::BaseMetric.connects_to(**connection_config)
+        SolidObserver::BaseRecord.connects_to(**connection_config)
+      end
+
+      def active_record_available?
+        defined?(::ActiveRecord::Base)
       end
 
       def activate_subscribers_in_realtime
         Rails.logger.info "[SolidObserver] Starting in real-time mode (no persistence)"
         Subscriber.subscribe! if should_activate_queue_subscriber?
         CacheSubscriber.subscribe! if should_activate_cache_subscriber?
+        CableSubscriber.subscribe! if should_activate_cable_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?
+      def activate_queue_subscriber
+        activate_subscriber_for_table("solid_observer_queue_events", Subscriber) if should_activate_queue_subscriber?
+      end
 
-        enabled_tables.any? { |table_name| skip_activation_for_missing_table?(table_name) }
+      def activate_cache_subscriber
+        activate_subscriber_for_table("solid_observer_cache_events", CacheSubscriber) if should_activate_cache_subscriber?
       end
 
-      def skip_activation_for_missing_table?(table_name)
+      def activate_cable_subscriber
+        activate_subscriber_for_table("solid_observer_cable_events", CableSubscriber) if should_activate_cable_subscriber?
+      end
+
+      def activate_subscriber_for_table(table_name, subscriber)
         case table_status(table_name)
         when :absent
           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.")
-          true
         else
-          false
+          subscriber.subscribe!
         end
       end
 
@@ -106,18 +110,28 @@ module SolidObserver
         SolidObserver.config.solid_cache_enabled?
       end
 
+      def should_activate_cable_subscriber?
+        SolidObserver.config.solid_cable_enabled?
+      end
+
       def log_activation_skip(message)
         Rails.logger.info("[SolidObserver] #{message}")
       end
 
       def table_status(table_name)
-        pool = SolidObserver::BaseEvent.connection_pool
+        return :unknown unless active_record_available?
+
+        data_source_status(table_name)
+      rescue *boot_connection_errors
+        :unknown
+      end
+
+      def data_source_status(table_name)
+        pool = SolidObserver::BaseRecord.connection_pool
 
         return :present if cached_data_source_exists?(pool, table_name)
 
         data_source_exists_in_db?(pool, table_name) ? :present : :absent
-      rescue *boot_connection_errors
-        :unknown
       end
 
       def cached_data_source_exists?(pool, table_name)
@@ -132,12 +146,15 @@ module SolidObserver
       end
 
       def boot_connection_errors
+        return [] unless active_record_available?
+
         [
           ActiveRecord::NoDatabaseError,
           ActiveRecord::ConnectionNotEstablished,
           ActiveRecord::StatementInvalid,
           *([PG::ConnectionBad] if defined?(PG::ConnectionBad)),
           *([Mysql2::Error::ConnectionError] if defined?(Mysql2::Error::ConnectionError)),
+          *([Trilogy::Error] if defined?(Trilogy::Error)),
           *([SQLite3::CantOpenException] if defined?(SQLite3::CantOpenException))
         ]
       end
@@ -146,6 +163,7 @@ module SolidObserver
     config.before_initialize do
       Engine.check_solid_queue_availability
       Engine.check_solid_cache_availability
+      Engine.check_solid_cable_availability
     end
 
     config.after_initialize do