solid_observer 0.4.0 → 0.6.0

data/lib/generators/solid_observer/templates/initializer.rb.tt

@@ -9,11 +9,20 @@ SolidObserver.configure do |config|
   # Recommended: false in production, true in development/staging
   config.ui_enabled = !Rails.env.production?
 
-  # Authentication for web UI — set a username to enable HTTP Basic Auth
+  # Production dashboard exposure is the host app's responsibility. If you mount
+  # the dashboard in production, wrap the mount in your existing admin auth
+  # constraint, for example in config/routes.rb:
+  #
+  #   authenticate :user, ->(user) { user.admin? } do
+  #     mount SolidObserver::Engine, at: "/solid_observer"
+  #   end
+  #
+  # Built-in HTTP Basic Auth is enabled only when BOTH credentials are present.
+  # Setting only one credential disables Basic Auth and logs a boot warning.
   # config.ui_username = "admin"
   # config.ui_password = "secret"
 
-  # Base controller for UI (customize authorization)
+  # Base controller used only to detect API-only rendering compatibility
   # config.ui_base_controller = "ApplicationController"
 
   # === Queue Observability (v0.1.0) ===
@@ -24,8 +33,17 @@ SolidObserver.configure do |config|
   # config.observe_cache = true
   # config.cache_sampling_rate = 0.1  # Sample 10% of cache operations
 
-  # === Cable Observability (Coming in v0.5.0+) ===
+  # === Cable Observability (v0.5.0) ===
+  # Enable SolidCable event capture and trim controls.
+  # Requires SolidCable in the host app; SolidObserver does not add it.
   # config.observe_cable = true
+  # config.cable_sampling_rate = 0.1          # Sample 10% of broadcast events
+  # config.cable_rejection_threshold = 0.05   # Rejection rate → Degraded stability
+  # config.cable_backlog_threshold = 0.10     # Backlog ratio threshold
+  # config.cable_error_threshold = 0.0        # Error rate threshold
+# === Trace & Health Observability (v0.6.0) ===
+# Health scoring (Services::HealthScore) is auto-computed and config-free.
+# Cross-component trace lookup uses correlation_id across Queue, Cache, and Cable.
 
   # Data Retention
   config.event_retention = 30.days    # How long to keep event records
@@ -42,9 +60,10 @@ SolidObserver.configure do |config|
   # Sampling (reduce overhead in high-traffic apps)
   config.sampling_rate = 1.0  # 1.0 = 100% (capture all events)
 
-  # Correlation ID (for distributed tracing)
+  # Correlation ID (for cross-component tracing & APM integration)
+  # Stamped correlation_id powers `rails solid_observer:trace[CORRELATION_ID]` CLI
+  # and the Web UI at /solid_observer/traces/:correlation_id.
   # Integrate with your APM tool (Datadog, Sentry, OpenTelemetry, etc.)
-  # config.correlation_id_generator = -> {
   #   # Example for Datadog APM
   #   Datadog::Tracing.active_trace&.id
   #

data/lib/solid_observer/base_event.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SolidObserver
-  class BaseEvent < ActiveRecord::Base
+  class BaseEvent < BaseRecord
     self.abstract_class = true
 
     # connects_to is configured by the engine after Rails initializes

data/lib/solid_observer/base_metric.rb

@@ -7,7 +7,7 @@ module SolidObserver
   # will be configured by the Engine (similar to BaseEvent) when metrics are
   # fully implemented.
   #
-  class BaseMetric < ActiveRecord::Base
+  class BaseMetric < BaseRecord
     self.abstract_class = true
     self.table_name = "solid_observer_metrics"
 

data/lib/solid_observer/base_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class BaseRecord < ActiveRecord::Base
+    self.abstract_class = true
+    # connects_to is configured by the engine after Rails initializes
+  end
+end

data/lib/solid_observer/cable_event_buffer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+require_relative "event_buffer_core"
+
+module SolidObserver
+  class CableEventBuffer
+    include Singleton
+    include EventBufferCore
+
+    INITIAL_METRICS = EventBufferCore::INITIAL_METRICS
+
+    def initialize
+      initialize_event_buffer
+    end
+
+    private
+
+    def flush_service
+      Services::FlushCableEventBuffer
+    end
+
+    def log_label
+      "Cable buffer"
+    end
+  end
+end

data/lib/solid_observer/cable_metric_buffer.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "concurrent/timer_task"
+
+require_relative "services/flush_cable_metrics"
+
+module SolidObserver
+  class CableMetricBuffer
+    include Singleton
+
+    INITIAL_METRICS = {
+      flush_failures_count: 0,
+      drops_count: 0,
+      last_flush_at: nil,
+      last_flush_duration_ms: nil,
+      last_flush_error: nil
+    }.freeze
+
+    def initialize
+      @store = MetricStore.new
+      @timer_mutex = Mutex.new
+      @timer_task = nil
+    end
+
+    def increment(metric_data)
+      config = SolidObserver.config
+      return unless config.persistence_mode?
+
+      @store.add(metric_data)
+      ensure_timer_running
+      flush! if size >= config.buffer_size
+    end
+
+    def flush!
+      metrics_to_flush = @store.drain
+      return if metrics_to_flush.empty?
+
+      flush_metrics(metrics_to_flush, monotonic_ms)
+    end
+
+    def flush
+      flush!
+    end
+
+    def size
+      @store.size
+    end
+
+    def clear
+      @store.clear
+    end
+
+    def metrics
+      @store.metrics
+    end
+
+    def shutdown
+      stop_timer
+      flush!
+    end
+
+    private
+
+    def ensure_timer_running
+      timer_to_start, timer_to_stop = replace_timer_if_stopped
+      return unless timer_to_start
+
+      timer_to_stop&.shutdown
+      timer_to_start.execute
+    end
+
+    def replace_timer_if_stopped
+      @timer_mutex.synchronize do
+        current_timer_task = @timer_task
+        return [nil, nil] if current_timer_task && !current_timer_task.shuttingdown?
+
+        [build_timer_task, current_timer_task]
+      end
+    end
+
+    def stop_timer
+      timer_to_stop = @timer_mutex.synchronize do
+        current_timer = @timer_task
+        @timer_task = nil
+        current_timer
+      end
+
+      timer_to_stop&.shutdown
+    end
+
+    def build_timer_task
+      @timer_task = Concurrent::TimerTask.new(
+        execution_interval: SolidObserver.config.flush_interval,
+        run_now: false
+      ) { flush! }
+    end
+
+    def monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+
+    def flush_metrics(metrics_to_flush, started_at_ms)
+      Services::FlushCableMetrics.call(metrics_to_flush)
+      @store.record_flush_success(monotonic_ms - started_at_ms)
+    rescue => error
+      handle_flush_error(error, metrics_to_flush)
+    end
+
+    def handle_flush_error(error, metrics_to_flush)
+      @store.requeue(metrics_to_flush)
+      @store.record_flush_failure(error)
+      Rails.logger&.error("[SolidObserver] Cable metric buffer flush failed: #{error.message}") if defined?(Rails)
+    end
+
+    class MetricStore
+      COUNTERS = %i[
+        broadcasts_count
+        transmissions_count
+        confirmations_count
+        rejections_count
+        perform_actions_count
+        errors_count
+      ].freeze
+
+      def initialize
+        @mutex = Mutex.new
+        @buffer = {}
+        @metrics = INITIAL_METRICS.dup
+      end
+
+      def add(metric_data)
+        @mutex.synchronize { add_metric(metric_data) }
+      end
+
+      def drain
+        @mutex.synchronize do
+          drained = @buffer.values.map(&:dup)
+          @buffer.clear
+          drained
+        end
+      end
+
+      def requeue(metrics_to_flush)
+        @mutex.synchronize { add_metrics_with_capacity(metrics_to_flush + @buffer.values) }
+      end
+
+      def clear
+        @mutex.synchronize { @buffer.clear }
+      end
+
+      def size
+        @mutex.synchronize { @buffer.size }
+      end
+
+      def metrics
+        @mutex.synchronize do
+          {
+            size: @buffer.size,
+            max_buffer_size: SolidObserver.config.max_buffer_size
+          }.merge(@metrics.dup)
+        end
+      end
+
+      def record_flush_success(duration_ms)
+        @mutex.synchronize do
+          @metrics.merge!(
+            last_flush_at: Time.current,
+            last_flush_duration_ms: duration_ms,
+            last_flush_error: nil
+          )
+        end
+      end
+
+      def record_flush_failure(error)
+        @mutex.synchronize do
+          @metrics[:flush_failures_count] += 1
+          @metrics[:last_flush_error] = error.message
+        end
+      end
+
+      private
+
+      def add_metric(metric_data)
+        config = SolidObserver.config
+        key = metric_data.fetch(:period_start)
+        if @buffer.key?(key)
+          merge_metric(@buffer.fetch(key), metric_data)
+        elsif @buffer.size < config.max_buffer_size
+          @buffer[key] = metric_hash(metric_data)
+        else
+          handle_overflow(key, metric_data)
+        end
+      end
+
+      def add_metrics_with_capacity(metrics)
+        @buffer.clear
+        metrics.each { |metric| add_metric(metric) }
+      end
+
+      def handle_overflow(key, metric_data)
+        drop_count = if SolidObserver.config.buffer_overflow_strategy == :drop_old
+          replace_old_metric(key, metric_data)
+        else
+          COUNTERS.sum { |counter| metric_data.fetch(counter, 0).to_i }
+        end
+
+        @metrics[:drops_count] += drop_count
+      end
+
+      def replace_old_metric(key, metric_data)
+        dropped = @buffer.shift&.last
+        @buffer[key] = metric_hash(metric_data)
+        dropped ? COUNTERS.sum { |counter| dropped.fetch(counter, 0).to_i } : 0
+      end
+
+      def merge_metric(target, metric_data)
+        COUNTERS.each do |counter|
+          target[counter] += metric_data.fetch(counter, 0).to_i
+        end
+      end
+
+      def metric_hash(metric_data)
+        COUNTERS.each_with_object({period_start: metric_data.fetch(:period_start)}) do |counter, hash|
+          hash[counter] = metric_data.fetch(counter, 0).to_i
+        end
+      end
+    end
+  end
+end

data/lib/solid_observer/cable_subscriber.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class CableSubscriber
+    EVENTS = %w[
+      broadcast.action_cable
+      transmit.action_cable
+      transmit_subscription_confirmation.action_cable
+      transmit_subscription_rejection.action_cable
+      perform_action.action_cable
+    ].freeze
+
+    class << self
+      attr_reader :subscriptions
+
+      def subscribe
+        return unless subscription_allowed?
+
+        self.subscriptions = EVENTS.map { |event_name| subscribe_to(event_name) }
+      end
+
+      def unsubscribe
+        return unless subscriptions
+
+        subscriptions.each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+        self.subscriptions = []
+      end
+
+      def subscribe!
+        subscribe
+      end
+
+      def unsubscribe!
+        unsubscribe
+      end
+
+      def subscribed?
+        !!subscriptions&.any?
+      end
+
+      private
+
+      attr_writer :subscriptions
+
+      def subscription_allowed?
+        SolidObserver.config.solid_cable_enabled? && !subscribed? && defined?(ActiveSupport::Notifications)
+      end
+
+      def subscribe_to(event_name)
+        ActiveSupport::Notifications.subscribe(event_name) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          Services::RecordCableEvent.call(event: event, buffer: CableEventBuffer.instance)
+        end
+      end
+    end
+  end
+end

data/lib/solid_observer/cache_event_buffer.rb

@@ -2,52 +2,27 @@
 
 require "singleton"
 
+require_relative "event_buffer_core"
+
 module SolidObserver
   class CacheEventBuffer
     include Singleton
+    include EventBufferCore
 
-    def initialize
-      @mutex = Mutex.new
-      @buffer = []
-    end
-
-    def push(event_data)
-      config = SolidObserver.config
-      return unless config.persistence_mode?
-
-      should_flush = buffer_ready_to_flush?(event_data, config.buffer_size)
-      flush! if should_flush
-    end
+    INITIAL_METRICS = EventBufferCore::INITIAL_METRICS
 
-    def flush!
-      events = @mutex.synchronize do
-        buffered_events = @buffer.dup
-        @buffer.clear
-        buffered_events
-      end
-      return if events.empty?
-
-      Services::FlushCacheEventBuffer.call(events)
-    rescue => error
-      @mutex.synchronize { @buffer = events + @buffer }
-      Rails.logger&.error("[SolidObserver] Cache buffer flush failed: #{error.message}") if defined?(Rails)
+    def initialize
+      initialize_event_buffer
     end
 
-    def size
-      @mutex.synchronize { @buffer.size }
-    end
+    private
 
-    def clear
-      @mutex.synchronize { @buffer.clear }
+    def flush_service
+      Services::FlushCacheEventBuffer
     end
 
-    private
-
-    def buffer_ready_to_flush?(event_data, buffer_size)
-      @mutex.synchronize do
-        @buffer << event_data
-        @buffer.size >= buffer_size
-      end
+    def log_label
+      "Cache buffer"
     end
   end
 end

data/lib/solid_observer/cache_metric_buffer.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "concurrent/timer_task"
+
+require_relative "services/flush_cache_metrics"
+
+module SolidObserver
+  class CacheMetricBuffer
+    include Singleton
+
+    INITIAL_METRICS = {
+      flush_failures_count: 0,
+      drops_count: 0,
+      last_flush_at: nil,
+      last_flush_duration_ms: nil,
+      last_flush_error: nil
+    }.freeze
+
+    def initialize
+      @store = MetricStore.new
+      @timer_mutex = Mutex.new
+      @timer_task = nil
+    end
+
+    def increment(metric_data)
+      config = SolidObserver.config
+      return unless config.persistence_mode?
+
+      @store.add(metric_data)
+      ensure_timer_running
+      flush! if size >= config.buffer_size
+    end
+
+    def flush!
+      metrics_to_flush = @store.drain
+      return if metrics_to_flush.empty?
+
+      flush_metrics(metrics_to_flush, monotonic_ms)
+    end
+
+    def flush
+      flush!
+    end
+
+    def size
+      @store.size
+    end
+
+    def clear
+      @store.clear
+    end
+
+    def metrics
+      @store.metrics
+    end
+
+    def shutdown
+      stop_timer
+      flush!
+    end
+
+    private
+
+    def ensure_timer_running
+      timer_to_start, timer_to_stop = replace_timer_if_stopped
+      return unless timer_to_start
+
+      timer_to_stop&.shutdown
+      timer_to_start.execute
+    end
+
+    def replace_timer_if_stopped
+      @timer_mutex.synchronize do
+        current_timer_task = @timer_task
+        return [nil, nil] if current_timer_task && !current_timer_task.shuttingdown?
+
+        [build_timer_task, current_timer_task]
+      end
+    end
+
+    def stop_timer
+      timer_to_stop = @timer_mutex.synchronize do
+        current_timer = @timer_task
+        @timer_task = nil
+        current_timer
+      end
+
+      timer_to_stop&.shutdown
+    end
+
+    def build_timer_task
+      @timer_task = Concurrent::TimerTask.new(
+        execution_interval: SolidObserver.config.flush_interval,
+        run_now: false
+      ) { flush! }
+    end
+
+    def monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+
+    def flush_metrics(metrics_to_flush, started_at_ms)
+      Services::FlushCacheMetrics.call(metrics_to_flush)
+      @store.record_flush_success(monotonic_ms - started_at_ms)
+    rescue => error
+      handle_flush_error(error, metrics_to_flush)
+    end
+
+    def handle_flush_error(error, metrics_to_flush)
+      @store.requeue(metrics_to_flush)
+      @store.record_flush_failure(error)
+      Rails.logger&.error("[SolidObserver] Cache metric buffer flush failed: #{error.message}") if defined?(Rails)
+    end
+
+    class MetricStore
+      def initialize
+        @mutex = Mutex.new
+        @buffer = {}
+        @metrics = INITIAL_METRICS.dup
+      end
+
+      def add(metric_data)
+        @mutex.synchronize { add_metric(metric_data) }
+      end
+
+      def drain
+        @mutex.synchronize do
+          drained = @buffer.values.map(&:dup)
+          @buffer.clear
+          drained
+        end
+      end
+
+      def requeue(metrics_to_flush)
+        @mutex.synchronize { add_metrics_with_capacity(metrics_to_flush + @buffer.values) }
+      end
+
+      def clear
+        @mutex.synchronize { @buffer.clear }
+      end
+
+      def size
+        @mutex.synchronize { @buffer.size }
+      end
+
+      def metrics
+        @mutex.synchronize do
+          {
+            size: @buffer.size,
+            max_buffer_size: SolidObserver.config.max_buffer_size
+          }.merge(@metrics.dup)
+        end
+      end
+
+      def record_flush_success(duration_ms)
+        @mutex.synchronize do
+          @metrics.merge!(
+            last_flush_at: Time.current,
+            last_flush_duration_ms: duration_ms,
+            last_flush_error: nil
+          )
+        end
+      end
+
+      def record_flush_failure(error)
+        @mutex.synchronize do
+          @metrics[:flush_failures_count] += 1
+          @metrics[:last_flush_error] = error.message
+        end
+      end
+
+      private
+
+      def add_metric(metric_data)
+        config = SolidObserver.config
+        key = [metric_data.fetch(:event_type), metric_data.fetch(:period_start)]
+        if @buffer.key?(key)
+          merge_metric(@buffer.fetch(key), metric_data)
+        elsif @buffer.size < config.max_buffer_size
+          @buffer[key] = metric_hash(metric_data)
+        else
+          handle_overflow(key, metric_data)
+        end
+      end
+
+      def add_metrics_with_capacity(metrics)
+        @buffer.clear
+        metrics.each { |metric| add_metric(metric) }
+      end
+
+      def handle_overflow(key, metric_data)
+        drop_count = if SolidObserver.config.buffer_overflow_strategy == :drop_old
+          replace_old_metric(key, metric_data)
+        else
+          metric_data.fetch(:operations_count, 1).to_i
+        end
+
+        @metrics[:drops_count] += drop_count
+      end
+
+      def replace_old_metric(key, metric_data)
+        dropped = @buffer.shift&.last
+        @buffer[key] = metric_hash(metric_data)
+        dropped ? dropped.fetch(:operations_count, 1).to_i : 0
+      end
+
+      def merge_metric(target, metric_data)
+        target[:operations_count] += metric_data.fetch(:operations_count, 1).to_i
+        target[:hits_count] += metric_data.fetch(:hits_count, 0).to_i
+        target[:misses_count] += metric_data.fetch(:misses_count, 0).to_i
+        target[:errors_count] += metric_data.fetch(:errors_count, 0).to_i
+        target[:duration_total] += metric_data.fetch(:duration_total, 0.0).to_f
+      end
+
+      def metric_hash(metric_data)
+        {
+          event_type: metric_data.fetch(:event_type),
+          period_start: metric_data.fetch(:period_start),
+          operations_count: metric_data.fetch(:operations_count, 1).to_i,
+          hits_count: metric_data.fetch(:hits_count, 0).to_i,
+          misses_count: metric_data.fetch(:misses_count, 0).to_i,
+          errors_count: metric_data.fetch(:errors_count, 0).to_i,
+          duration_total: metric_data.fetch(:duration_total, 0.0).to_f
+        }
+      end
+    end
+  end
+end