solid_observer 0.1.0

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# SolidObserver Configuration
+# See https://github.com/bart-oz/solid_observer for more details
+
+SolidObserver.configure do |config|
+  # UI Settings
+  # Enable the web UI for viewing events and metrics
+  # Recommended: false in production, true in development/staging
+  config.ui_enabled = !Rails.env.production?
+
+  # Authentication for UI (when ui_enabled = true)
+  # config.http_basic_auth_enabled = true
+  # config.http_basic_auth_user = "admin"
+  # config.http_basic_auth_password = "secret"
+
+  # Base controller for UI (customize authorization)
+  # config.ui_base_controller = "ApplicationController"
+
+  # === Queue Observability (v0.1.0) ===
+  config.observe_queue = true
+
+  # === Cache Observability (Coming in v0.2.0+) ===
+  # config.observe_cache = true
+  # config.cache_sampling_rate = 0.1  # Sample 10% of cache operations
+
+  # === Cable Observability (Coming in v0.2.0+) ===
+  # config.observe_cable = true
+
+  # Data Retention
+  config.event_retention = 30.days    # How long to keep event records
+  config.metrics_retention = 90.days  # How long to keep aggregated metrics
+
+  # Database Limits (prevent unlimited growth)
+  config.max_db_size = 1.gigabyte
+  config.warning_threshold = 0.8  # Warn when DB reaches 80% of max_db_size
+
+  # Performance Settings
+  config.buffer_size = 1000        # Events to buffer before flushing
+  config.flush_interval = 10.seconds
+
+  # Sampling (reduce overhead in high-traffic apps)
+  config.sampling_rate = 1.0  # 1.0 = 100% (capture all events)
+
+  # Correlation ID (for distributed tracing)
+  # Integrate with your APM tool (Datadog, Sentry, OpenTelemetry, etc.)
+  # config.correlation_id_generator = -> {
+  #   # Example for Datadog APM
+  #   Datadog::Tracing.active_trace&.id
+  #
+  #   # Example for Sentry
+  #   Sentry.get_current_scope&.transaction&.trace_id
+  #
+  #   # Example for OpenTelemetry
+  #   OpenTelemetry::Trace.current_span&.context&.trace_id
+  # }
+end

data/lib/solid_observer/base_event.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class BaseEvent < ActiveRecord::Base
+    self.abstract_class = true
+
+    # connects_to is configured by the engine after Rails initializes
+    # See lib/solid_observer/engine.rb
+  end
+end

data/lib/solid_observer/base_metric.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  # BaseMetric provides the foundation for time-series metrics storage.
+  #
+  # NOTE: Metrics functionality is planned for v0.2.0. The database connection
+  # will be configured by the Engine (similar to BaseEvent) when metrics are
+  # fully implemented.
+  #
+  class BaseMetric < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name = "solid_observer_metrics"
+
+    PERIOD_TYPES = %w[minute hour day].freeze
+
+    validates :metric_name, presence: true
+    validates :value, presence: true, numericality: {only_integer: true, greater_than_or_equal_to: 0}
+    validates :period_start, presence: true
+    validates :period_type, presence: true, inclusion: {in: PERIOD_TYPES}
+
+    scope :for_metric, ->(name) { where(metric_name: name) }
+    scope :hourly, -> { where(period_type: "hour") }
+    scope :daily, -> { where(period_type: "day") }
+    scope :minutely, -> { where(period_type: "minute") }
+    scope :since, ->(time) { where("period_start >= ?", time) }
+    scope :between, ->(start_time, end_time) { where(period_start: start_time..end_time) }
+
+    class << self
+      def increment(metric:, period: Time.current.beginning_of_hour, period_type: "hour", by: 1)
+        record = find_or_create_by!(
+          metric_name: metric,
+          period_start: period,
+          period_type: period_type
+        )
+        record.increment!(:value, by)
+        record
+      rescue ActiveRecord::RecordNotUnique
+        retry
+      end
+
+      def record(metric:, value:, period: Time.current.beginning_of_hour, period_type: "hour")
+        upsert(
+          {
+            metric_name: metric,
+            value: value,
+            period_start: period,
+            period_type: period_type
+          },
+          unique_by: [:metric_name, :period_start, :period_type]
+        )
+        find_by!(
+          metric_name: metric,
+          period_start: period,
+          period_type: period_type
+        )
+      end
+    end
+  end
+end

data/lib/solid_observer/cli/base.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Base
+      def self.call(*args, **kwargs)
+        new.call(*args, **kwargs)
+      end
+
+      def call
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      private
+
+      def output(text, color: nil)
+        text = colorize(text, color) if color && color_enabled?
+        puts text
+      end
+
+      def error(text)
+        output(text, color: :red)
+      end
+
+      def success(text)
+        output(text, color: :green)
+      end
+
+      def warning(text)
+        output(text, color: :yellow)
+      end
+
+      def info(text)
+        output(text, color: :blue)
+      end
+
+      def table(headers:, rows:)
+        return if rows.empty?
+
+        widths = calculate_column_widths(headers, rows)
+
+        output(format_table_row(headers, widths), color: :cyan)
+        output(separator_line(widths), color: :cyan)
+
+        rows.each do |row|
+          output(format_table_row(row, widths))
+        end
+      end
+
+      def confirm(question, default: true)
+        prompt = default ? "(Y/n)" : "(y/N)"
+        output("#{question} #{prompt} ", color: :yellow)
+        print "> "
+
+        response = $stdin.gets&.strip&.downcase
+
+        return default if response.nil? || response.empty?
+
+        response.start_with?("y")
+      end
+
+      def color_enabled?
+        $stdout.tty?
+      end
+
+      def colorize(text, color)
+        return text unless color
+
+        color_code = COLORS[color]
+        return text unless color_code
+
+        "\e[#{color_code}m#{text}\e[0m"
+      end
+
+      def calculate_column_widths(headers, rows)
+        all_rows = [headers] + rows
+        all_rows.transpose.map { |column| column.map(&:to_s).map(&:length).max }
+      end
+
+      def format_table_row(row, widths)
+        row.map.with_index { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ")
+      end
+
+      def separator_line(widths)
+        widths.map { |width| "-" * width }.join("  ")
+      end
+
+      COLORS = {
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36
+      }.freeze
+    end
+  end
+end

data/lib/solid_observer/cli/jobs.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Jobs < Base
+      def list(status: nil, queue: nil, job_class: nil, limit: 20)
+        return error("SolidQueue is not available") unless solid_queue_available?
+
+        jobs = fetch_jobs(status: status, queue: queue, job_class: job_class, limit: limit)
+
+        return warning("No jobs found matching the criteria") if jobs.empty?
+
+        print_jobs_table(jobs)
+      end
+
+      def show(job_id)
+        return error("SolidQueue is not available") unless solid_queue_available?
+
+        job = find_job(job_id)
+        return unless job
+
+        print_job_details(job)
+      end
+
+      def retry_job(job_id)
+        return error("SolidQueue is not available") unless solid_queue_available?
+
+        job = find_failed_job(job_id)
+        return unless job
+
+        return info("Retry cancelled") unless confirm("Retry job #{job_id}?")
+
+        job.retry
+        success("✓ Job #{job_id} has been queued for retry")
+      end
+
+      def discard(job_id)
+        return error("SolidQueue is not available") unless solid_queue_available?
+
+        job = find_failed_job(job_id)
+        return unless job
+
+        return info("Discard cancelled") unless confirm("Discard job #{job_id}? This cannot be undone.", default: false)
+
+        job.discard
+        success("✓ Job #{job_id} has been discarded")
+      end
+
+      private
+
+      def solid_queue_available?
+        SolidObserver::QueueStats.solid_queue_available?
+      end
+
+      def fetch_jobs(status:, queue:, job_class:, limit:)
+        scope = scope_for_status(status)
+        scope = scope.joins(:job) if job_class || needs_job_join?(status, queue)
+        scope = apply_queue_filter(scope, status, queue)
+        scope = scope.where("solid_queue_jobs.class_name = ?", job_class) if job_class
+        scope.order(created_at: :desc).limit(limit.to_i).includes(:job).to_a
+      end
+
+      def needs_job_join?(status, queue)
+        queue && %w[failed claimed].include?(status&.to_s&.downcase)
+      end
+
+      def apply_queue_filter(scope, status, queue)
+        return scope unless queue
+
+        case status&.to_s&.downcase
+        when "failed", "claimed"
+          scope.where("solid_queue_jobs.queue_name = ?", queue)
+        else
+          scope.where(queue_name: queue)
+        end
+      end
+
+      def scope_for_status(status)
+        case status&.to_s&.downcase
+        when "ready" then SolidQueue::ReadyExecution.all
+        when "scheduled" then SolidQueue::ScheduledExecution.all
+        when "claimed" then SolidQueue::ClaimedExecution.all
+        when "failed" then SolidQueue::FailedExecution.all
+        else SolidQueue::ReadyExecution.all
+        end
+      end
+
+      def find_job(job_id)
+        job = find_in_execution_tables(job_id)
+        return job if job
+
+        error("Job #{job_id} not found")
+        nil
+      end
+
+      def find_failed_job(job_id)
+        job = SolidQueue::FailedExecution.find_by(id: job_id)
+        return job if job
+
+        error("Failed job #{job_id} not found")
+        nil
+      end
+
+      def find_in_execution_tables(job_id)
+        SolidQueue::ReadyExecution.find_by(id: job_id) ||
+          SolidQueue::ScheduledExecution.find_by(id: job_id) ||
+          SolidQueue::ClaimedExecution.find_by(id: job_id) ||
+          SolidQueue::FailedExecution.find_by(id: job_id)
+      end
+
+      def print_jobs_table(jobs)
+        print_section_header("📋 Jobs")
+        table(
+          headers: ["ID", "Queue", "Class", "Status", "Created At"],
+          rows: jobs.map { |job| format_job_row(job) }
+        )
+        output("")
+      end
+
+      def format_job_row(execution)
+        job = execution.job
+        [
+          execution.id.to_s,
+          job&.queue_name || execution.try(:queue_name) || "N/A",
+          job&.class_name || "N/A",
+          job_status(execution),
+          format_time(execution.created_at)
+        ]
+      end
+
+      def job_status(execution)
+        return "Ready" if execution.is_a?(SolidQueue::ReadyExecution)
+        return "Scheduled" if execution.is_a?(SolidQueue::ScheduledExecution)
+        return "Claimed" if execution.is_a?(SolidQueue::ClaimedExecution)
+        return "Failed" if execution.is_a?(SolidQueue::FailedExecution)
+
+        "Unknown"
+      end
+
+      def format_time(time)
+        time.strftime("%Y-%m-%d %H:%M:%S")
+      end
+
+      def print_job_details(execution)
+        print_section_header("📄 Job Details")
+
+        details = build_job_details(execution)
+
+        table(
+          headers: ["Attribute", "Value"],
+          rows: details
+        )
+        output("")
+      end
+
+      def build_job_details(execution)
+        job = execution.job
+        details = [
+          ["ID", execution.id],
+          ["Job ID", job&.id || "N/A"],
+          ["Queue", job&.queue_name || execution.try(:queue_name) || "N/A"],
+          ["Class", job&.class_name || "N/A"],
+          ["Status", job_status(execution)],
+          ["Created At", format_time(execution.created_at)],
+          ["Priority", execution.try(:priority) || job&.priority || "N/A"]
+        ]
+
+        add_scheduled_details(details, execution)
+        add_error_details(details, execution)
+
+        details
+      end
+
+      def add_scheduled_details(details, execution)
+        return unless execution.is_a?(SolidQueue::ScheduledExecution)
+
+        details << ["Scheduled At", format_time(execution.scheduled_at)]
+      end
+
+      def add_error_details(details, execution)
+        return unless execution.is_a?(SolidQueue::FailedExecution)
+        return unless execution.error
+
+        details << ["Error", execution.error.exception_class]
+        details << ["Error Message", execution.error.message]
+      end
+
+      def print_section_header(title)
+        output("\n#{title}", color: :cyan)
+        output("=" * 80, color: :cyan)
+        output("")
+      end
+    end
+  end
+end

data/lib/solid_observer/cli/status.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Status < Base
+      def call
+        print_header
+        print_queue_stats
+      end
+
+      private
+
+      def print_header
+        output("\n📊 SolidObserver Status", color: :cyan)
+        output("=" * 50, color: :cyan)
+        output("")
+      end
+
+      def print_queue_stats
+        stats = SolidObserver::QueueStats.snapshot
+
+        if stats[:available]
+          print_queue_table(stats)
+          print_queue_depths(stats[:queues]) if stats[:queues].any?
+        else
+          warning("⚠️  SolidQueue not available: #{stats[:error]}")
+        end
+      end
+
+      def print_queue_table(stats)
+        output("🚀 Solid Queue", color: :green)
+        output("")
+
+        table(
+          headers: ["Metric", "Value"],
+          rows: [
+            ["Ready", stats[:ready]],
+            ["Scheduled", stats[:scheduled]],
+            ["Claimed", stats[:claimed]],
+            ["Failed", stats[:failed]],
+            ["Workers", stats[:workers]]
+          ]
+        )
+        output("")
+      end
+
+      def print_queue_depths(queues)
+        output("📋 Queue Depths", color: :green)
+        output("")
+
+        table(
+          headers: ["Queue", "Jobs"],
+          rows: queues.sort_by { |name, _count| name }.map { |name, count| [name, count] }
+        )
+        output("")
+      end
+    end
+  end
+end

data/lib/solid_observer/cli/storage.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Storage < Base
+      def call
+        print_section_header("💾 Storage Status")
+
+        current_stats = gather_storage_stats
+
+        if current_stats[:error]
+          error(current_stats[:error])
+          return
+        end
+
+        print_storage_table(current_stats)
+        print_configuration
+      end
+
+      private
+
+      def gather_storage_stats
+        {
+          db_size_bytes: calculate_database_size,
+          event_count: QueueEvent.count,
+          max_size_bytes: SolidObserver.config.max_db_size
+        }
+      rescue => e
+        {error: "Failed to gather storage stats: #{e.message}"}
+      end
+
+      def calculate_database_size
+        db_config = QueueEvent.connection_db_config
+        db_path = db_config.database
+
+        return 0 unless File.exist?(db_path)
+
+        File.size(db_path)
+      rescue => e
+        warning("Could not calculate database size: #{e.message}")
+        0
+      end
+
+      def print_storage_table(stats)
+        size_mb = bytes_to_mb(stats[:db_size_bytes])
+        percentage = calculate_percentage(stats[:db_size_bytes], stats[:max_size_bytes])
+        status = status_indicator(percentage)
+
+        table(
+          headers: ["Component", "Size", "Events", "Usage", "Status"],
+          rows: [[
+            "Queue",
+            format_size(size_mb),
+            format_number(stats[:event_count]),
+            "#{percentage}%",
+            status
+          ]]
+        )
+
+        output("")
+      end
+
+      def print_configuration
+        retention_days = (SolidObserver.config.event_retention / 1.day).to_i
+        max_size_mb = bytes_to_mb(SolidObserver.config.max_db_size)
+
+        info("Configuration:")
+        output("  Retention: #{retention_days} days")
+        output("  Max size:  #{format_size(max_size_mb)} per database")
+        output("  Warning:   #{(SolidObserver.config.warning_threshold * 100).to_i}% threshold")
+        output("")
+      end
+
+      def bytes_to_mb(bytes)
+        (bytes / 1_048_576.0).round(2)
+      end
+
+      def calculate_percentage(current, max)
+        return 0.0 if max.zero?
+
+        ((current.to_f / max) * 100).round(2)
+      end
+
+      def status_indicator(percentage)
+        threshold = SolidObserver.config.warning_threshold * 100
+
+        if percentage >= threshold
+          "⚠️  Warning"
+        else
+          "✓ OK"
+        end
+      end
+
+      def format_size(size_mb)
+        if size_mb >= 1024
+          "#{(size_mb / 1024.0).round(2)} GB"
+        else
+          "#{size_mb} MB"
+        end
+      end
+
+      def format_number(number)
+        number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+
+      def print_section_header(title)
+        output("")
+        output(title, color: :cyan)
+        output("=" * 50, color: :cyan)
+        output("")
+      end
+    end
+  end
+end