solid_observer 0.1.1 → 0.4.0

data/app/controllers/solid_observer/dashboard_controller.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/solid_observer/application_helper"
+
+module SolidObserver
+  class DashboardController < ApplicationController
+    helper SolidObserver::ApplicationHelper
+
+    skip_forgery_protection only: :live_poll
+    skip_after_action :verify_same_origin_request, only: :live_poll
+
+    def index
+      @component = selected_component
+      return assign_cache_dashboard if @component == "cache"
+
+      return unless @component == "queue" && SolidObserver.config.solid_queue_enabled?
+
+      assign_range_and_stats
+      load_persistence_data if persistence_mode?
+    end
+
+    def live_poll
+      send_file(
+        SolidObserver::Engine.root.join("app/assets/javascripts/solid_observer/live_poll.js"),
+        type: "application/javascript; charset=utf-8",
+        disposition: "inline"
+      )
+    end
+
+    def poll_data
+      range = QueueStats.parse_range(request_range_param, fallback: QueueStats::POLL_DEFAULT_RANGE)
+      window = QueueStats.range_duration(range, fallback: QueueStats::POLL_DEFAULT_RANGE)
+      append_chart_buffer
+      render json: tick_request? ? tick_payload : full_payload(range: range, window: window)
+    end
+
+    private
+
+    def assign_range_and_stats
+      range = QueueStats.parse_range(request_range_param)
+      @range = range
+      @live = request_live_param == "on"
+      @stats = QueueStats.snapshot(range: range)
+      @chart = if @stats[:available]
+        QueueStats.chart_data(window: QueueStats.range_duration(@range))
+      else
+        {performed: [], failed: [], ready: []}
+      end
+    rescue
+      @chart = {performed: [], failed: [], ready: []}
+    end
+
+    def load_persistence_data
+      @recent_events = QueueEvent.recent(10)
+    end
+
+    def assign_cache_dashboard
+      SolidObserver::CacheDashboardController.cache_dashboard_assignments(range_param: request_range_param).each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+    end
+
+    def request_range_param
+      request&.query_parameters&.[]("range") || request&.query_parameters&.[](:range)
+    end
+
+    def request_live_param
+      request&.query_parameters&.[]("live") || request&.query_parameters&.[](:live)
+    end
+
+    def request_tick_param
+      request&.query_parameters&.[]("tick") || request&.query_parameters&.[](:tick)
+    end
+
+    def tick_request?
+      request_tick_param == "true"
+    end
+
+    def tick_payload
+      {
+        mode: persistence_mode? ? "persistence" : "realtime",
+        snapshot: QueueStats.snapshot_for_tick,
+        chart: nil
+      }
+    end
+
+    def full_payload(range:, window:)
+      {
+        mode: persistence_mode? ? "persistence" : "realtime",
+        snapshot: QueueStats.snapshot_for_poll(range: range),
+        chart: QueueStats.chart_data(window: window),
+        range_label: helpers.range_label(range)
+      }
+    end
+
+    def append_chart_buffer
+      ChartBuffer.append(SolidQueue::ReadyExecution.count) if QueueStats.solid_queue_available?
+    end
+
+    def selected_component
+      requested = if request&.respond_to?(:path_parameters)
+        request.path_parameters&.[](:component).to_s
+      else
+        ""
+      end
+      requested = path_component if requested.empty?
+      return "cache" if requested == "cache" && SolidObserver.config.solid_cache_enabled?
+
+      "queue"
+    end
+
+    def path_component
+      return "" unless request&.respond_to?(:path)
+
+      path = request&.path.to_s
+      return "cache" if path.end_with?("/cache")
+      return "queue" if path.end_with?("/queue")
+
+      ""
+    end
+  end
+end

data/app/controllers/solid_observer/events_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class EventsController < ApplicationController
+    include Paginatable
+    include RequirePersistenceMode
+
+    PER_PAGE = 50
+
+    def index
+      filter = Params::EventsFilter.from_params(params)
+      @event_type = filter.event_type
+      @job_class = filter.job_class
+      @queue_name = filter.queue_name
+      @from = filter.from
+      @to = filter.to
+      @page = filter.page
+      scope = Queries::EventsQuery.new(filter).call
+      offset = paginate_scope(scope, per_page: PER_PAGE)
+      @events = scope.limit(PER_PAGE).offset(offset)
+      load_available_options
+    end
+
+    def show
+      @event = QueueEvent.find_by(id: params[:id])
+      return redirect_to(events_path, alert: "Event not found") unless @event
+
+      @metadata = parse_metadata(@event.metadata)
+    end
+
+    private
+
+    def load_available_options
+      @available_event_types = QueueEvent::EVENT_TYPES
+      @available_job_classes = cached_filter_options("solid_observer/events/distinct_job_classes") { QueueEvent.distinct_job_classes }
+      @available_queues = cached_filter_options("solid_observer/events/distinct_queue_names") { QueueEvent.distinct_queue_names }
+    end
+
+    def cached_filter_options(key, &block)
+      Rails.cache.fetch(key, expires_in: SolidObserver.config.filter_cache_ttl, &block)
+    end
+
+    def parse_metadata(metadata)
+      return nil if metadata.blank?
+      JSON.parse(metadata)
+    rescue JSON::ParserError
+      {raw: metadata}
+    end
+  end
+end

data/app/controllers/solid_observer/jobs_controller.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class JobsController < ApplicationController
+    include Paginatable
+    include RequireSolidQueue
+
+    PER_PAGE = 25
+    CACHE_KEY_QUEUES = "solid_observer/jobs/available_queues"
+    CACHE_KEY_JOB_CLASSES = "solid_observer/jobs/available_job_classes"
+
+    def index
+      filter = Params::JobsFilter.from_params(params)
+      @status = filter.status
+      @queue_name = filter.queue_name
+      @job_class = filter.job_class
+      @page = filter.page
+      result = Queries::JobExecutionsQuery.new(filter).call
+      offset = paginate_scope(result, per_page: PER_PAGE)
+      @jobs = if result.is_a?(Array)
+        result.drop(offset).first(PER_PAGE)
+      else
+        result.limit(PER_PAGE).offset(offset).includes(:job).to_a
+      end
+      @available_queues = fetch_available_queues
+      @available_job_classes = fetch_available_job_classes
+    end
+
+    def show
+      @execution = find_execution_for_show
+      return redirect_to jobs_path, alert: "Job not found" unless @execution
+
+      assign_show_presenter
+    end
+
+    def retry
+      id = params[:id]
+      execution = Queries::ExecutionFinder.find_failed(id)
+      return redirect_to(jobs_path, alert: "Failed job not found") unless execution
+
+      execution.retry
+      redirect_to jobs_path(status: "failed"), notice: "Job #{id} queued for retry"
+    end
+
+    def discard
+      id = params[:id]
+      execution = Queries::ExecutionFinder.find_failed(id)
+      return redirect_to(jobs_path, alert: "Failed job not found") unless execution
+
+      execution.discard
+      redirect_to jobs_path(status: "failed"), notice: "Job #{id} discarded"
+    end
+
+    private
+
+    def find_execution_for_show
+      id = params[:id]
+      Queries::ExecutionFinder.find_by_status(id, params[:status]) ||
+        Queries::ExecutionFinder.find_any(id)
+    end
+
+    def assign_show_presenter
+      @presenter = ExecutionPresenter.new(@execution)
+      @job = @presenter.job
+      @status = @presenter.status
+    end
+
+    def fetch_available_queues
+      Rails.cache.fetch(CACHE_KEY_QUEUES, expires_in: SolidObserver.config.filter_cache_ttl) do
+        next [] unless defined?(SolidQueue::Queue)
+        SolidQueue::Queue.all.map(&:name)
+      end
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+      []
+    end
+
+    def fetch_available_job_classes
+      Rails.cache.fetch(CACHE_KEY_JOB_CLASSES, expires_in: SolidObserver.config.filter_cache_ttl) do
+        SolidQueue::Job.distinct.pluck(:class_name).compact.sort
+      end
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+      []
+    end
+  end
+end

data/app/controllers/solid_observer/storages_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class StoragesController < ApplicationController
+    include RequirePersistenceMode
+
+    def show
+      @storage_components = SolidObserver::Services::StorageInfoSnapshot.call
+      @storage_history = SolidObserver::StorageInfo.recent(20)
+    end
+  end
+end

data/app/helpers/solid_observer/application_helper.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require_relative "dashboard_helper"
+
+module SolidObserver
+  module ApplicationHelper
+    include SolidObserver::DashboardHelper
+
+    STATUS_COLORS = {
+      "completed" => "success",
+      "ready" => "success",
+      "failed" => "danger",
+      "retry_stopped" => "danger",
+      "scheduled" => "warning",
+      "claimed" => "warning",
+      "enqueued" => "info",
+      "discarded" => "info"
+    }.freeze
+    DURATION_SEMANTICS = {
+      "job_enqueued" => "Time spent in the ActiveJob enqueue call (Rails internal; typically sub-millisecond to single-digit ms)",
+      "job_completed" => "Time spent performing the job",
+      "job_failed" => "Time spent performing the job before the exception was raised",
+      "job_discarded" => "Time before discard decision was made"
+    }.freeze
+    STABILITY_STATES = {
+      stable: {label: "Stable", tone: "success"},
+      degraded: {label: "Degraded", tone: "warning"},
+      critical: {label: "Critical", tone: "danger"}
+    }.freeze
+    CACHE_OUTCOME_STATES = {
+      hit: {label: "Hit", tone: "success"},
+      miss: {label: "Miss", tone: "info"},
+      error: {label: "Error", tone: "danger"},
+      recorded: {label: "Recorded", tone: "recorded"}
+    }.freeze
+    CACHE_RANGE_LABELS = {
+      "15m" => "in last 15m",
+      "30m" => "in last 30m",
+      "1h" => "in last hour",
+      "7h" => "in last 7h",
+      "1d" => "in last day",
+      "7d" => "in last 7d",
+      "14d" => "in last 14d"
+    }.freeze
+
+    def execution_status(execution)
+      ExecutionPresenter.new(execution).status
+    end
+
+    def format_duration(seconds)
+      return "0ms" if seconds.to_f.zero?
+
+      if seconds < 1
+        "#{(seconds * 1000).round}ms"
+      else
+        "#{"%.1f" % seconds}s"
+      end
+    end
+
+    def status_badge(status)
+      status_str = status.to_s
+      color = STATUS_COLORS.fetch(status_str, "default")
+      dot = tag.svg(
+        tag.circle(r: 3, cx: 3, cy: 3),
+        class: "so-badge__dot",
+        viewBox: "0 0 6 6",
+        "aria-hidden": "true"
+      )
+      tag.span(class: "so-badge so-badge--pill so-badge--#{color}") do
+        safe_join([dot, status_str.humanize], " ")
+      end
+    end
+
+    def duration_with_semantic(value, event_type)
+      return content_tag(:span, "—", class: "so-text-muted") unless value
+
+      content_tag(:abbr, format_duration(value), title: DURATION_SEMANTICS.fetch(event_type.to_s))
+    end
+
+    def mode_badge
+      config = SolidObserver.config
+      color = config.persistence_mode? ? "info" : "warning"
+      dot = tag.svg(
+        tag.circle(r: 3, cx: 3, cy: 3),
+        class: "so-badge__dot",
+        viewBox: "0 0 6 6",
+        "aria-hidden": "true"
+      )
+      tag.span(class: "so-badge so-badge--pill so-badge--#{color}") do
+        safe_join([dot, config.storage_mode.to_s.capitalize], " ")
+      end
+    end
+
+    def turbo_frame_tag(id, **options, &block)
+      return super if defined?(super)
+
+      content = options.delete(:content)
+      body = block_given? ? capture(&block) : content
+
+      content_tag(:"turbo-frame", body, **options.merge(id: id).compact)
+    end
+
+    def stability_state(stats)
+      return :critical if stats[:failed_last_hour].to_i.positive?
+      return :degraded if stats[:failed_last_24h].to_i.positive?
+
+      :stable
+    end
+
+    def stability_badge(stats)
+      stability_badge_for(stability_state(stats))
+    end
+
+    def cache_stability_badge(state)
+      stability_badge_for(state.to_sym)
+    end
+
+    def cache_ratio_percent(value)
+      number_to_percentage(value.to_f * 100, precision: 1, strip_insignificant_zeros: true)
+    end
+
+    def cache_storage_summary(storage_components)
+      snapshots = Array(storage_components)
+      reason = cache_storage_unavailable_reason(snapshots)
+      return {value: "—", subtitle: "— #{reason}"} if reason
+
+      {
+        value: number_to_human_size(cache_storage_total_bytes(snapshots), precision: 1, significant: false, strip_insignificant_zeros: false),
+        subtitle: "SolidCache + cache observer"
+      }
+    end
+
+    def cache_event_outcome_badge(event)
+      meta = cache_event_outcome_meta(event)
+      dot = tag.svg(
+        tag.circle(r: 3, cx: 3, cy: 3),
+        class: "so-badge__dot",
+        viewBox: "0 0 6 6",
+        "aria-hidden": "true"
+      )
+
+      tag.span(class: "so-badge so-badge--pill so-badge--#{meta[:tone]}") do
+        safe_join([dot, meta[:label]], " ")
+      end
+    end
+
+    def cache_event_digest(key_digest, visible_chars: 10)
+      digest = key_digest.to_s
+      return "—" if digest.empty?
+      return digest if digest.length <= visible_chars
+
+      "#{digest.first(visible_chars)}…"
+    end
+
+    def cache_range_label(range_key)
+      CACHE_RANGE_LABELS.fetch(range_key.to_s, "in selected range")
+    end
+
+    def cache_stability_detail(stability)
+      state = (stability || {})[:state]&.to_sym
+      state = :stable unless STABILITY_STATES.key?(state)
+
+      case state
+      when :critical
+        critical_cache_stability_detail(stability)
+      when :degraded
+        degraded_cache_stability_detail(stability)
+      else
+        "No sampled cache errors or slow events in the selected range"
+      end
+    end
+
+    def stability_detail(stats)
+      failures_24h = stats[:failed_last_24h].to_i
+      return "No failures in the last 24h" if failures_24h.zero?
+
+      "#{pluralize(failures_24h, "failure")} in the last 24h, latest #{latest_failure_phrase(stats[:latest_failure_at])}"
+    end
+
+    def latest_failure_phrase(timestamp)
+      timestamp ? "#{time_ago_in_words(timestamp)} ago" : "unknown"
+    end
+
+    def queue_component_enabled?
+      SolidObserver.config.solid_queue_enabled?
+    end
+
+    def cache_component_enabled?
+      SolidObserver.config.solid_cache_enabled?
+    end
+
+    def dashboard_section_active?(component)
+      current_component = @component.presence || "queue"
+      controller_name == "dashboard" && current_component == component.to_s
+    end
+
+    private
+
+    def stability_badge_for(state)
+      meta = STABILITY_STATES.fetch(state)
+      dot = tag.svg(tag.circle(r: 3, cx: 3, cy: 3),
+        class: "so-badge__dot", viewBox: "0 0 6 6", "aria-hidden": "true")
+      tag.span(class: "so-badge so-badge--pill so-badge--#{meta[:tone]}") do
+        safe_join([dot, meta[:label]], " ")
+      end
+    end
+
+    def critical_cache_stability_detail(stability)
+      detail = pluralize(stability[:error_count].to_i, "sampled cache error")
+      slow_count = stability[:slow_count].to_i
+      detail = "#{detail} and #{pluralize(slow_count, "slow event")}" if slow_count.positive?
+      "#{detail} in the selected range#{cache_stability_latest_suffix(stability[:latest_recorded_at])}"
+    end
+
+    def degraded_cache_stability_detail(stability)
+      detail = pluralize(stability[:slow_count].to_i, "slow sampled cache event")
+      "#{detail} in the selected range#{cache_stability_latest_suffix(stability[:latest_recorded_at])}"
+    end
+
+    def cache_stability_latest_suffix(timestamp)
+      timestamp ? ", latest #{time_ago_in_words(timestamp)} ago" : ""
+    end
+
+    def cache_storage_total_bytes(snapshots)
+      snapshots.sum { |snapshot| snapshot[:db_size_bytes].to_i }
+    end
+
+    def cache_storage_unavailable_reason(snapshots)
+      return "Storage snapshot unavailable" unless snapshots.size == 2
+
+      snapshots.find { |snapshot| !snapshot[:available] }&.[](:unavailable_reason)
+    end
+
+    def cache_event_outcome_meta(event)
+      hit = event.hit
+
+      return CACHE_OUTCOME_STATES.fetch(:error) if event.error_class.present?
+      return CACHE_OUTCOME_STATES.fetch(:hit) if hit == true
+      return CACHE_OUTCOME_STATES.fetch(:miss) if hit == false
+
+      CACHE_OUTCOME_STATES.fetch(:recorded)
+    end
+  end
+end

data/app/helpers/solid_observer/dashboard_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Mirrors live_poll.js Sparkline.render — keep in sync.
+module SolidObserver
+  module DashboardHelper
+    SVG_W = 120
+    SVG_H = 32
+
+    def spark_points(series, width: SVG_W, height: SVG_H)
+      return "" if series.blank?
+
+      context = build_spark_context(series, width, height)
+      series.map { |point| format_spark_point(point: point, context: context) }.join(" ")
+    end
+
+    def build_spark_context(series, width, height)
+      first_point = series.first
+      last_point = series.last
+      min_time = first_point[:t]
+
+      {
+        min_time: min_time,
+        time_span: last_point[:t] - min_time,
+        max_value: [series.max_by { |point| point[:v] }[:v], 1].max,
+        width: width,
+        height: height,
+        inner_width: width - 2,
+        inner_height: height - 2
+      }
+    end
+
+    def format_spark_point(point:, context:)
+      time_span = context[:time_span]
+      coordinate_x = if time_span.zero?
+        context[:width] / 2.0
+      else
+        ((point[:t] - context[:min_time]).to_f / time_span) * context[:inner_width] + 1
+      end
+
+      coordinate_y = context[:height] - 1 - (point[:v].to_f / context[:max_value]) * context[:inner_height]
+      format("%.1f,%.1f", coordinate_x, coordinate_y)
+    end
+
+    RANGE_LABELS = {
+      "15m" => "in last 15m",
+      "30m" => "in last 30m",
+      "1h" => "in last hour",
+      "7h" => "in last 7h",
+      "1d" => "in last day",
+      "7d" => "in last 7d",
+      "14d" => "in last 14d"
+    }.freeze
+
+    def range_label(range_key)
+      RANGE_LABELS.fetch(range_key, "in selected range")
+    end
+  end
+end

data/app/models/solid_observer/cache_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class CacheEvent < BaseEvent
+    self.table_name = "solid_observer_cache_events"
+
+    validates :event_type, presence: true
+    validates :key_digest, presence: true
+    validates :recorded_at, presence: true
+
+    scope :errored, -> { where.not(error_class: nil) }
+    scope :slow, ->(threshold = SolidObserver.config.cache_slow_threshold) { where("duration >= ?", threshold) }
+    scope :recent, ->(limit = 10) { order(recorded_at: :desc).limit(limit) }
+  end
+end

data/app/models/solid_observer/cache_metric.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class CacheMetric < BaseMetric
+    self.table_name = "solid_observer_cache_metrics"
+    clear_validators!
+
+    validates :event_type, presence: true, length: {maximum: 64}
+    validates :period_start, presence: true
+    validates :operations_count, :hits_count, :misses_count, :errors_count,
+      numericality: {only_integer: true, greater_than_or_equal_to: 0}
+    validates :duration_total, numericality: {greater_than_or_equal_to: 0}
+  end
+end