solid_observer 0.1.0

data/lib/solid_observer/configuration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/numeric/bytes"
+
+module SolidObserver
+  # Configuration options for SolidObserver.
+  #
+  # @example Basic configuration
+  #   SolidObserver.configure do |config|
+  #     config.event_retention = 14.days
+  #     config.sampling_rate = 0.5
+  #   end
+  class Configuration
+    # UI Settings
+    attr_accessor :ui_enabled,
+      :ui_base_controller,
+      :http_basic_auth_enabled,
+      :http_basic_auth_user,
+      :http_basic_auth_password
+
+    # Observer Settings
+    attr_accessor :observe_queue
+
+    # Observer Settings (planned for v0.2.0)
+    # @note Cache and Cable observers are not yet implemented
+    attr_accessor :observe_cache,
+      :observe_cable,
+      :cache_sampling_rate
+
+    # Retention Settings
+    attr_accessor :event_retention
+
+    # Retention Settings (planned for v0.2.0)
+    # @note Metrics cleanup is not yet implemented
+    attr_accessor :metrics_retention
+
+    # Storage Settings
+    attr_accessor :max_db_size
+
+    # Performance Settings (with validation)
+    attr_reader :sampling_rate,
+      :warning_threshold,
+      :buffer_size,
+      :flush_interval
+
+    # Correlation Settings
+    attr_accessor :correlation_id_generator
+
+    def initialize
+      # UI defaults
+      @ui_enabled = !production?
+      @ui_base_controller = "::ApplicationController"
+      @http_basic_auth_enabled = false
+      @http_basic_auth_user = nil
+      @http_basic_auth_password = nil
+
+      # Observer defaults
+      @observe_queue = true
+      @observe_cache = false
+      @observe_cable = false
+
+      # Retention defaults
+      @event_retention = 30.days
+      @metrics_retention = 90.days
+
+      # Storage defaults
+      @max_db_size = 1.gigabyte
+      @warning_threshold = 0.8
+
+      # Performance defaults
+      @sampling_rate = 1.0
+      @cache_sampling_rate = 0.1
+      @buffer_size = 1000
+      @flush_interval = 10.seconds
+
+      # Correlation defaults
+      @correlation_id_generator = nil
+    end
+
+    def sampling_rate=(value)
+      validate_rate!(:sampling_rate, value)
+      @sampling_rate = value
+    end
+
+    def warning_threshold=(value)
+      validate_rate!(:warning_threshold, value)
+      @warning_threshold = value
+    end
+
+    def buffer_size=(value)
+      validate_positive_integer!(:buffer_size, value)
+      @buffer_size = value
+    end
+
+    def flush_interval=(value)
+      validate_positive_numeric!(:flush_interval, value)
+      @flush_interval = value
+    end
+
+    private
+
+    def validate_rate!(name, value)
+      unless value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
+        raise ArgumentError, "#{name} must be a number between 0.0 and 1.0"
+      end
+    end
+
+    def validate_positive_integer!(name, value)
+      unless value.is_a?(Integer) && value > 0
+        raise ArgumentError, "#{name} must be a positive integer"
+      end
+    end
+
+    def validate_positive_numeric!(name, value)
+      unless value.is_a?(Numeric) && value > 0
+        raise ArgumentError, "#{name} must be a positive number"
+      end
+    end
+
+    def production?
+      defined?(Rails) && Rails.env.production?
+    end
+  end
+end

data/lib/solid_observer/correlation_id_resolver.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SolidObserver
+  class CorrelationIdResolver
+    def self.resolve(event)
+      new(event).resolve
+    end
+
+    def initialize(event)
+      @event = event
+    end
+
+    def resolve
+      custom_generator_result.presence ||
+        job_id_result.presence ||
+        thread_correlation_id.presence ||
+        SecureRandom.uuid
+    end
+
+    private
+
+    def custom_generator_result
+      call_custom_generator if custom_generator_configured?
+    end
+
+    def job_id_result
+      extract_job_id if job_event?
+    end
+
+    def thread_correlation_id
+      Thread.current[:solid_observer_correlation_id]
+    end
+
+    def custom_generator_configured?
+      SolidObserver.config.correlation_id_generator.present?
+    end
+
+    def call_custom_generator
+      result = SolidObserver.config.correlation_id_generator.call
+      return nil if result.blank?
+      result
+    rescue => e
+      log_generator_error(e)
+      nil
+    end
+
+    def log_generator_error(exception)
+      return unless defined?(Rails) && Rails.logger
+      Rails.logger.warn "[SolidObserver] Custom correlation_id_generator failed: #{exception.message}"
+    end
+
+    def job_event?
+      @event.payload[:job]&.job_id.present?
+    end
+
+    def extract_job_id
+      @event.payload[:job].job_id
+    end
+  end
+end

data/lib/solid_observer/engine.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidObserver
+
+    class << self
+      def check_solid_queue_availability
+        return if defined?(SolidQueue)
+
+        Rails.logger.warn "[SolidObserver] SolidQueue not detected. Queue observability features will be limited."
+      end
+
+      def configure_database_connection
+        db_config = ActiveRecord::Base.configurations.configs_for(
+          env_name: Rails.env,
+          name: "solid_observer_queue"
+        )
+
+        return unless db_config
+
+        connection_config = {
+          database: {writing: :solid_observer_queue, reading: :solid_observer_queue}
+        }
+
+        SolidObserver::BaseEvent.connects_to(**connection_config)
+        SolidObserver::BaseMetric.connects_to(**connection_config)
+      end
+
+      def activate_subscribers
+        logger = Rails.logger
+
+        unless table_exists?("solid_observer_queue_events")
+          logger.info "[SolidObserver] Tables not found. Run: rails solid_observer:install:migrations && rails db:migrate"
+          return
+        end
+
+        logger.info "[SolidObserver] Activating event subscribers"
+        Subscriber.subscribe!
+      rescue ActiveRecord::NoDatabaseError
+        logger.info "[SolidObserver] Database not ready yet. Skipping subscriber activation."
+      end
+
+      private
+
+      def table_exists?(table_name)
+        ActiveRecord::Base.connection.table_exists?(table_name)
+      end
+    end
+
+    config.before_initialize do
+      Engine.check_solid_queue_availability
+    end
+
+    config.after_initialize do
+      Engine.configure_database_connection
+      Engine.activate_subscribers
+    end
+  end
+end

data/lib/solid_observer/queue_event_buffer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module SolidObserver
+  # Thread-safe buffer for collecting queue events before batch insertion.
+  #
+  # Events are buffered in memory and flushed either when:
+  # - Buffer size reaches the configured threshold
+  # - Flush interval timer expires
+  #
+  # @example Push an event to the buffer
+  #   QueueEventBuffer.instance.push(event_data)
+  class QueueEventBuffer
+    include Singleton
+
+    def initialize
+      @mutex = Mutex.new
+      @buffer = []
+      @flush_scheduled = false
+    end
+
+    # Adds an event to the buffer and triggers flush if threshold reached.
+    #
+    # @param event_data [Hash] Event data to buffer
+    # @return [void]
+    def push(event_data)
+      should_flush = false
+
+      @mutex.synchronize do
+        @buffer << event_data
+        schedule_flush unless @flush_scheduled
+        should_flush = @buffer.size >= SolidObserver.config.buffer_size
+      end
+
+      flush! if should_flush
+    end
+
+    # Flushes all buffered events to the database.
+    #
+    # @return [void]
+    def flush!
+      events_to_flush = nil
+
+      @mutex.synchronize do
+        return if @buffer.empty?
+        events_to_flush = @buffer.dup
+        @buffer.clear
+      end
+
+      Services::FlushEventBuffer.call(events_to_flush)
+    rescue => e
+      @mutex.synchronize { @buffer.unshift(*events_to_flush) }
+      Rails.logger&.error "[SolidObserver] Buffer flush failed: #{e.message}" if defined?(Rails)
+    end
+
+    def size
+      @mutex.synchronize { @buffer.size }
+    end
+
+    def clear
+      @mutex.synchronize { @buffer.clear }
+    end
+
+    private
+
+    def schedule_flush
+      @flush_scheduled = true
+      thread = Thread.new do
+        sleep SolidObserver.config.flush_interval
+        @mutex.synchronize { @flush_scheduled = false }
+        flush!
+      rescue => e
+        Rails.logger&.error "[SolidObserver] Scheduled flush failed: #{e.message}" if defined?(Rails)
+      end
+      thread.name = "SolidObserver::QueueEventBuffer#flush"
+      thread.report_on_exception = false
+    end
+  end
+end

data/lib/solid_observer/queue_stats.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class QueueStats
+    class << self
+      def snapshot
+        new.snapshot
+      end
+
+      def solid_queue_available?
+        !!(defined?(SolidQueue) && defined?(SolidQueue::Job))
+      end
+    end
+
+    def snapshot
+      return unavailable_response unless self.class.solid_queue_available?
+
+      {
+        ready: ready_count,
+        scheduled: scheduled_count,
+        claimed: claimed_count,
+        failed: failed_count,
+        workers: active_workers_count,
+        queues: queue_depths,
+        available: true
+      }
+    rescue => e
+      error_response(e)
+    end
+
+    private
+
+    def unavailable_response
+      {
+        ready: 0,
+        scheduled: 0,
+        claimed: 0,
+        failed: 0,
+        workers: 0,
+        queues: {},
+        available: false,
+        error: "SolidQueue not available"
+      }
+    end
+
+    def error_response(exception)
+      {
+        ready: 0,
+        scheduled: 0,
+        claimed: 0,
+        failed: 0,
+        workers: 0,
+        queues: {},
+        available: false,
+        error: exception.message
+      }
+    end
+
+    def ready_count
+      SolidQueue::ReadyExecution.count
+    end
+
+    def scheduled_count
+      SolidQueue::ScheduledExecution.count
+    end
+
+    def claimed_count
+      SolidQueue::ClaimedExecution.count
+    end
+
+    def failed_count
+      SolidQueue::FailedExecution.count
+    end
+
+    def active_workers_count
+      return 0 unless defined?(SolidQueue::Process)
+
+      SolidQueue::Process.where(kind: "Worker").count
+    end
+
+    def queue_depths
+      return {} unless defined?(SolidQueue::ReadyExecution)
+
+      SolidQueue::ReadyExecution
+        .group(:queue_name)
+        .count
+    end
+  end
+end

data/lib/solid_observer/services/cleanup_storage.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Services
+    class CleanupStorage
+      def self.call
+        new.call
+      end
+
+      def call
+        deleted_count = 0
+
+        QueueEvent.transaction do
+          deleted_count = delete_old_events
+          record_snapshot_after_cleanup
+        end
+
+        vacuum_database
+
+        check_storage_warnings
+        log_results(deleted_count)
+
+        deleted_count
+      rescue => e
+        Rails.logger.error "[SolidObserver] Cleanup failed: #{e.message}"
+        raise
+      end
+
+      private
+
+      def delete_old_events
+        cutoff = SolidObserver.config.event_retention.ago
+        QueueEvent.where("recorded_at < ?", cutoff).delete_all
+      end
+
+      def record_snapshot_after_cleanup
+        db_size = calculate_database_size
+        event_count = QueueEvent.count
+
+        StorageInfo.record_snapshot(
+          db_size: db_size,
+          event_count: event_count
+        )
+      end
+
+      def vacuum_database
+        adapter = QueueEvent.connection.adapter_name.downcase
+        case adapter
+        when "sqlite"
+          QueueEvent.connection.execute("VACUUM")
+        when "postgresql"
+          QueueEvent.connection.execute("VACUUM ANALYZE solid_observer_queue_events")
+        when "mysql2", "trilogy"
+          QueueEvent.connection.execute("OPTIMIZE TABLE solid_observer_queue_events")
+        end
+      rescue => e
+        Rails.logger.warn "[SolidObserver] Database maintenance failed: #{e.message}"
+      end
+
+      def calculate_database_size
+        db_path = QueueEvent.connection_db_config.database
+        File.size(db_path) if File.exist?(db_path)
+      rescue => e
+        Rails.logger.warn "[SolidObserver] Could not calculate DB size: #{e.message}"
+        0
+      end
+
+      def check_storage_warnings
+        max_size = SolidObserver.config.max_db_size
+        threshold = SolidObserver.config.warning_threshold
+        current_size = calculate_database_size
+
+        return unless current_size > (max_size * threshold)
+
+        percentage = ((current_size.to_f / max_size) * 100).round(1)
+        Rails.logger.warn "[SolidObserver] Queue DB approaching limit: #{format_bytes(current_size)} / #{format_bytes(max_size)} (#{percentage}%)"
+      end
+
+      def log_results(deleted_count)
+        Rails.logger.info "[SolidObserver] Cleaned #{deleted_count} queue events"
+      end
+
+      def format_bytes(bytes)
+        return "0 B" if bytes.zero?
+
+        units = ["B", "KB", "MB", "GB"]
+        exp = (Math.log(bytes) / Math.log(1024)).to_i
+        exp = [exp, units.length - 1].min
+
+        "%.1f %s" % [bytes.to_f / (1024**exp), units[exp]]
+      end
+    end
+  end
+end

data/lib/solid_observer/services/flush_event_buffer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Services
+    # Flushes buffered events to the database using bulk insert.
+    #
+    # Attempts bulk insert with automatic fallback to smaller batches
+    # if the initial insert fails.
+    #
+    # @example Flush events
+    #   FlushEventBuffer.call(events)
+    class FlushEventBuffer
+      BATCH_SIZE = 100
+
+      # @param events [Array<Hash>] Array of event data to insert
+      # @return [Integer] Number of events successfully inserted
+      def self.call(events)
+        new(events).call
+      end
+
+      def initialize(events)
+        @events = events
+        @failed_count = 0
+      end
+
+      def call
+        return 0 if @events.empty?
+
+        QueueEvent.transaction do
+          QueueEvent.insert_all!(@events)
+        end
+
+        @events.size
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::StatementInvalid => e
+        log_error("Bulk insert failed, retrying in batches: #{e.message}")
+        retry_with_smaller_batches
+      end
+
+      private
+
+      def retry_with_smaller_batches
+        inserted = 0
+
+        @events.each_slice(BATCH_SIZE) do |batch|
+          QueueEvent.insert_all(batch, returning: false)
+          inserted += batch.size
+        rescue ActiveRecord::StatementInvalid, ActiveRecord::RecordInvalid => e
+          @failed_count += batch.size
+          log_warning("Failed to insert batch of #{batch.size} events: #{e.message}")
+        end
+
+        log_warning("#{@failed_count} events could not be saved") if @failed_count.positive?
+        inserted
+      end
+
+      def log_error(message)
+        Rails.logger.error("[SolidObserver] #{message}") if defined?(Rails)
+      end
+
+      def log_warning(message)
+        Rails.logger.warn("[SolidObserver] #{message}") if defined?(Rails)
+      end
+    end
+  end
+end

data/lib/solid_observer/services/record_event.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Services
+    # Records ActiveJob events to the buffer with sampling support.
+    #
+    # Extracts job metadata, applies sampling rate, and pushes events
+    # to the buffer for batch insertion.
+    #
+    # @example Record a job completion
+    #   RecordEvent.call(
+    #     event: event,
+    #     event_type: "job_completed",
+    #     buffer: QueueEventBuffer.instance,
+    #     metric_name: "jobs_completed"
+    #   )
+    class RecordEvent
+      # @param event [ActiveSupport::Notifications::Event] The notification event
+      # @param event_type [String] Type of event (e.g., "job_enqueued")
+      # @param buffer [QueueEventBuffer] Buffer to push event data to
+      # @param metric_name [String] Metric name for incrementing
+      # @return [void]
+      def self.call(event:, event_type:, buffer:, metric_name:)
+        new(event, event_type, buffer, metric_name).call
+      end
+
+      def initialize(event, event_type, buffer, metric_name)
+        @event = event
+        @event_type = event_type
+        @buffer = buffer
+        @metric_name = metric_name
+      end
+
+      def call
+        return unless should_record?
+
+        @buffer.push(build_event_data)
+        increment_metric
+      rescue => e
+        handle_error(e)
+      end
+
+      private
+
+      def should_record?
+        rand <= SolidObserver.config.sampling_rate
+      end
+
+      def build_event_data
+        metadata = extract_metadata
+
+        {
+          event_type: @event_type,
+          job_class: metadata[:job_class],
+          queue_name: metadata[:queue_name],
+          correlation_id: CorrelationIdResolver.resolve(@event),
+          duration: @event.duration,
+          metadata: metadata.except(:job_class, :queue_name).to_json,
+          recorded_at: Time.current
+        }
+      end
+
+      def extract_metadata
+        payload = @event.payload || {}
+        exception_obj = payload[:exception_object]
+
+        {
+          job_id: payload.dig(:job, :job_id),
+          job_class: payload.dig(:job, :class_name) || payload.dig(:job, :job_class),
+          queue_name: payload.dig(:job, :queue_name),
+          arguments: payload.dig(:job, :arguments),
+          executions: payload.dig(:job, :executions),
+          exception_class: exception_obj&.class&.name || payload[:exception]&.first,
+          exception_message: exception_obj&.message || payload[:exception]&.last,
+          enqueued_at: payload.dig(:job, :enqueued_at),
+          priority: payload.dig(:job, :priority)
+        }.compact
+      rescue => e
+        Rails.logger.warn "[SolidObserver] Failed to extract metadata: #{e.message}" if defined?(Rails)
+        {}
+      end
+
+      def increment_metric
+        period = Time.current.beginning_of_hour
+        QueueMetric.increment(metric: @metric_name, period: period)
+      rescue => e
+        Rails.logger.warn "[SolidObserver] Metric increment failed: #{e.message}" if defined?(Rails)
+      end
+
+      def handle_error(exception)
+        return unless defined?(Rails) && Rails.logger
+        Rails.logger.warn "[SolidObserver] Event recording failed: #{exception.message}"
+      end
+    end
+  end
+end