rails_orbit 0.1.0

data/lib/generators/rails_orbit/templates/create_orbit_metrics.rb.erb

@@ -0,0 +1,14 @@
+class CreateRailsOrbitMetrics < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :rails_orbit_metrics do |t|
+      t.string   :key,         null: false, limit: 255
+      t.float    :value,       null: false
+      t.string   :dimension,   limit: 255
+      t.datetime :recorded_at, null: false, precision: 6
+    end
+
+    add_index :rails_orbit_metrics, [:key, :recorded_at]
+    add_index :rails_orbit_metrics, :recorded_at
+    add_index :rails_orbit_metrics, [:key, :recorded_at, :value], name: "idx_rails_orbit_metrics_cover"
+  end
+end

data/lib/generators/rails_orbit/templates/initializer.rb

@@ -0,0 +1,31 @@
+RailsOrbit.configure do |config|
+  # ── Storage ───────────────────────────────────────────────────────────────
+  # :sqlite    → writes to db/rails_orbit.sqlite3 (default)
+  # :host_db   → writes to host app's primary DB, all tables prefixed orbit_
+  # :external  → provide config.storage_url below
+  config.storage_adapter = :sqlite
+
+  # Required only when storage_adapter is :external
+  # config.storage_url = ENV["ORBIT_DATABASE_URL"]
+
+  # ── Authentication ────────────────────────────────────────────────────────
+  # Provide a block that will be called as a before_action on the dashboard.
+  # Default: HTTP Basic Auth via ORBIT_USER / ORBIT_PASSWORD env vars.
+  # config.authenticate_with do |controller|
+  #   controller.authenticate_or_request_with_http_basic("Orbit") do |name, password|
+  #     ActiveSupport::SecurityUtils.secure_compare(name, ENV.fetch("ORBIT_USER", "orbit")) &
+  #       ActiveSupport::SecurityUtils.secure_compare(password, ENV.fetch("ORBIT_PASSWORD", "changeme"))
+  #   end
+  # end
+
+  # ── Data retention ────────────────────────────────────────────────────────
+  config.retention_days = 7
+
+  # ── Kamal integration (disabled by default) ───────────────────────────────
+  config.kamal_enabled      = false
+  config.kamal_ssh_key_path = nil
+
+  # ── Dashboard ─────────────────────────────────────────────────────────────
+  config.dashboard_title = "Orbit"
+  config.poll_interval   = 5
+end

data/lib/rails_orbit/configuration.rb

@@ -0,0 +1,73 @@
+module RailsOrbit
+  class Configuration
+    VALID_ADAPTERS = %i[sqlite host_db external].freeze
+
+    attr_accessor :storage_adapter, :storage_url, :retention_days,
+                  :kamal_enabled, :kamal_ssh_key_path,
+                  :dashboard_title, :poll_interval
+    attr_reader   :auth_block
+
+    def initialize
+      @storage_adapter    = :sqlite
+      @storage_url        = nil
+      @retention_days     = 7
+      @kamal_enabled      = false
+      @kamal_ssh_key_path = nil
+      @dashboard_title    = "Orbit"
+      @poll_interval      = 5
+      @auth_block         = default_auth_block
+    end
+
+    def authenticate_with(&block)
+      @auth_block = block
+    end
+
+    def validate!
+      validate_storage_adapter!
+      validate_external_url!
+      validate_kamal_ssh_key!
+    end
+
+    private
+
+    def validate_storage_adapter!
+      return if VALID_ADAPTERS.include?(@storage_adapter)
+      raise ArgumentError, "Unknown storage_adapter: #{@storage_adapter.inspect}. Valid options: #{VALID_ADAPTERS.join(', ')}"
+    end
+
+    def validate_external_url!
+      return unless @storage_adapter == :external && @storage_url.blank?
+      raise ArgumentError, "storage_adapter is :external but storage_url is not set."
+    end
+
+    def validate_kamal_ssh_key!
+      return unless @kamal_enabled
+      return if @kamal_ssh_key_path || ENV["ORBIT_SSH_KEY_PATH"]
+      raise ArgumentError, "kamal_enabled is true but kamal_ssh_key_path is not set. " \
+                           "Set it in the initializer or via ORBIT_SSH_KEY_PATH env var."
+    end
+
+    def default_auth_block
+      ->(controller) {
+        user     = ENV["ORBIT_USER"]
+        password = ENV["ORBIT_PASSWORD"]
+
+        if user.nil? || password.nil?
+          if Rails.env.production?
+            Rails.logger.error("[rails_orbit] ORBIT_USER and ORBIT_PASSWORD must be set in production. Dashboard access denied.")
+            controller.head(:forbidden)
+            return
+          else
+            user     ||= "orbit"
+            password ||= "orbit"
+          end
+        end
+
+        controller.authenticate_or_request_with_http_basic("Orbit") do |name, pwd|
+          ActiveSupport::SecurityUtils.secure_compare(name, user) &
+            ActiveSupport::SecurityUtils.secure_compare(pwd, password)
+        end
+      }
+    end
+  end
+end

data/lib/rails_orbit/database_setup.rb

@@ -0,0 +1,87 @@
+module RailsOrbit
+  class DatabaseSetup
+    attr_reader :connection
+
+    def initialize(connection = ApplicationRecord.connection)
+      @connection = connection
+    end
+
+    def run!
+      configure_sqlite! if sqlite?
+      create_table_unless_exists!
+    end
+
+    private
+
+    def sqlite?
+      adapter_name.include?("sqlite")
+    end
+
+    def postgres?
+      adapter_name.include?("postgres")
+    end
+
+    def adapter_name
+      connection.adapter_name.downcase
+    end
+
+    def configure_sqlite!
+      %w[journal_mode=WAL busy_timeout=5000 synchronous=NORMAL].each do |pragma|
+        connection.raw_connection.execute("PRAGMA #{pragma}")
+      end
+    rescue => e
+      Rails.logger.debug("[rails_orbit] SQLite PRAGMA setup: #{e.message}")
+    end
+
+    def create_table_unless_exists!
+      table = Metric.table_name
+      return if connection.table_exists?(table)
+
+      connection.execute(create_table_ddl(table))
+      add_indexes!(table)
+      Rails.logger.info("[rails_orbit] Created #{table} table (adapter: #{adapter_name})")
+    end
+
+    def create_table_ddl(table)
+      if sqlite?
+        <<~SQL
+          CREATE TABLE IF NOT EXISTS #{table} (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            key VARCHAR(255) NOT NULL,
+            value FLOAT NOT NULL,
+            dimension VARCHAR(255),
+            recorded_at DATETIME NOT NULL
+          )
+        SQL
+      elsif postgres?
+        <<~SQL
+          CREATE TABLE IF NOT EXISTS #{table} (
+            id BIGSERIAL PRIMARY KEY,
+            key VARCHAR(255) NOT NULL,
+            value DOUBLE PRECISION NOT NULL,
+            dimension VARCHAR(255),
+            recorded_at TIMESTAMP(6) NOT NULL
+          )
+        SQL
+      else
+        <<~SQL
+          CREATE TABLE IF NOT EXISTS #{table} (
+            id BIGINT AUTO_INCREMENT PRIMARY KEY,
+            key VARCHAR(255) NOT NULL,
+            value DOUBLE NOT NULL,
+            dimension VARCHAR(255),
+            recorded_at DATETIME(6) NOT NULL
+          )
+        SQL
+      end
+    end
+
+    def add_indexes!(table)
+      { key_rec: "(key, recorded_at)", rec: "(recorded_at)", cover: "(key, recorded_at, value)" }.each do |name, cols|
+        connection.execute("CREATE INDEX IF NOT EXISTS idx_#{table}_#{name} ON #{table} #{cols}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rails_orbit/engine.rb

@@ -0,0 +1,80 @@
+module RailsOrbit
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsOrbit
+
+    rake_tasks do
+      load root.join("lib", "tasks", "rails_orbit.rake")
+    end
+
+    initializer "rails_orbit.establish_connection", after: :load_active_record do
+      config.after_initialize do
+        orbit_config = RailsOrbit.configuration
+
+        conn_spec = case orbit_config.storage_adapter
+        when :sqlite
+          db_path = Rails.root.join("db", "rails_orbit.sqlite3")
+          { adapter: "sqlite3", database: db_path.to_s, timeout: 5000 }
+        when :host_db
+          ActiveRecord::Base.connection_db_config.configuration_hash.dup
+        when :external
+          { url: orbit_config.storage_url }
+        end
+
+        ApplicationRecord.establish_connection(conn_spec)
+        DatabaseSetup.new.run!
+      rescue => e
+        Rails.logger.warn("[rails_orbit] Database setup failed: #{e.message}. Run `bin/rails rails_orbit:setup` manually.")
+      end
+    end
+
+    initializer "rails_orbit.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[rails_orbit/application.css rails_orbit/application.js]
+      end
+    end
+
+    initializer "rails_orbit.static_assets" do |app|
+      app.middleware.insert_before(::ActionDispatch::Static, ::ActionDispatch::Static, root.join("public").to_s)
+    end
+
+    initializer "rails_orbit.ephemeral_warning" do
+      next unless RailsOrbit.configuration.storage_adapter == :sqlite
+
+      signals = %w[DYNO RAILWAY_ENVIRONMENT FLY_APP_NAME]
+      next unless signals.any? { |k| ENV.key?(k) }
+
+      platform = ENV["DYNO"] ? "Heroku" : ENV["RAILWAY_ENVIRONMENT"] ? "Railway" : "Fly.io"
+      db_path = Rails.root.join("db", "rails_orbit.sqlite3")
+      msg = "[rails_orbit] WARNING: Using :sqlite on #{platform} (ephemeral filesystem). " \
+            "#{db_path} will be destroyed on deploy. Use :host_db or :external instead."
+      Rails.logger.warn(msg)
+      warn(msg)
+    end
+
+    initializer "rails_orbit.instrumentation", after: "rails_orbit.establish_connection" do
+      ActiveSupport.on_load(:after_initialize) { Instrumentation.subscribe! }
+    end
+
+    initializer "rails_orbit.kamal_poller", after: "rails_orbit.instrumentation" do
+      ActiveSupport.on_load(:after_initialize) do
+        next unless RailsOrbit.configuration.kamal_enabled
+        require "rails_orbit/kamal/config_reader"
+        require "rails_orbit/kamal/stats_collector"
+        require "rails_orbit/kamal/poller"
+        Kamal::Poller.start!
+      end
+    end
+
+    initializer "rails_orbit.puma_fork_safety" do
+      config.after_initialize do
+        next unless defined?(Puma) && Puma.respond_to?(:cli_config)
+        Puma.cli_config.options[:before_worker_boot] ||= []
+        Puma.cli_config.options[:before_worker_boot] << ->(_) { MetricWriter.reset! }
+      end
+    end
+
+    initializer "rails_orbit.shutdown_hook" do
+      at_exit { MetricWriter.shutdown if defined?(MetricWriter) }
+    end
+  end
+end

data/lib/rails_orbit/instrumentation.rb

@@ -0,0 +1,83 @@
+module RailsOrbit
+  module Instrumentation
+    SUBSCRIPTIONS = [
+      "enqueue.solid_queue",
+      "perform.solid_queue",
+      "failed_execution.solid_queue",
+      "retry_execution.solid_queue",
+      "discard_job.solid_queue",
+      "cache_read.active_support",
+      "cache_write.active_support",
+      "cache_delete.active_support",
+      "cache_fetch_hit.active_support",
+      "error_recorded.solid_errors",
+    ].freeze
+
+    class << self
+      def subscribe!
+        unsubscribe! if @subscriptions
+        @subscriptions = SUBSCRIPTIONS.map do |event_name|
+          ActiveSupport::Notifications.subscribe(event_name) do |event|
+            handle(event)
+          end
+        end
+      end
+
+      def unsubscribe!
+        Array(@subscriptions).each do |sub|
+          ActiveSupport::Notifications.unsubscribe(sub)
+        end
+        @subscriptions = nil
+      end
+
+      def subscribed?
+        @subscriptions.present?
+      end
+
+      def handle(event)
+        key, value, dimension = translate(event)
+        return unless key
+        MetricWriter.write(key: key, value: value, dimension: dimension)
+      end
+
+      def translate(event)
+        case event.name
+        when "enqueue.solid_queue"
+          ["solid_queue.enqueued", 1, event.payload[:queue_name]]
+
+        when "perform.solid_queue"
+          duration_ms = event.duration.round(2)
+          ["solid_queue.performed_ms", duration_ms, event.payload[:queue_name]]
+
+        when "failed_execution.solid_queue"
+          ["solid_queue.failed", 1, event.payload[:queue_name]]
+
+        when "retry_execution.solid_queue"
+          ["solid_queue.retried", 1, event.payload[:queue_name]]
+
+        when "discard_job.solid_queue"
+          ["solid_queue.discarded", 1, event.payload[:queue_name]]
+
+        when "cache_read.active_support"
+          hit = event.payload[:hit] ? "hit" : "miss"
+          ["solid_cache.read_#{hit}", 1, event.payload[:store]]
+
+        when "cache_write.active_support"
+          ["solid_cache.write", 1, event.payload[:store]]
+
+        when "cache_delete.active_support"
+          ["solid_cache.delete", 1, event.payload[:store]]
+
+        when "cache_fetch_hit.active_support"
+          ["solid_cache.fetch_hit", 1, event.payload[:store]]
+
+        when "error_recorded.solid_errors"
+          ["solid_errors.recorded", 1, event.payload[:exception_class]]
+
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rails_orbit/kamal/config_reader.rb

@@ -0,0 +1,32 @@
+module RailsOrbit
+  module Kamal
+    class ConfigReader
+      DEPLOY_YML = "config/deploy.yml"
+
+      class << self
+        def load
+          @config ||= begin
+            path = Rails.root.join(DEPLOY_YML)
+            raise "Kamal config not found at #{path}" unless path.exist?
+            YAML.safe_load_file(path, permitted_classes: [Symbol])
+          end
+        end
+
+        def reload!
+          @config = nil
+          load
+        end
+
+        def servers
+          config = load
+          Array(config.dig("servers", "web")) +
+            Array(config.dig("servers", "workers"))
+        end
+
+        def ssh_user
+          load.dig("ssh", "user") || "root"
+        end
+      end
+    end
+  end
+end

data/lib/rails_orbit/kamal/poller.rb

@@ -0,0 +1,64 @@
+require "concurrent"
+
+module RailsOrbit
+  module Kamal
+    class Poller
+      POLL_INTERVAL = 30
+
+      def self.available?
+        return @available if defined?(@available)
+        @available = begin
+          require "sshkit"
+          require "sshkit/dsl"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      def self.start!
+        unless available?
+          Rails.logger.warn "[rails_orbit] Kamal polling requires the sshkit gem. Add it to your Gemfile."
+          return
+        end
+        new.schedule
+      end
+
+      def schedule
+        @task = Concurrent::TimerTask.new(
+          execution_interval: POLL_INTERVAL,
+          run_now: true
+        ) { run }
+        @task.execute
+      end
+
+      def stop
+        @task&.shutdown
+      end
+
+      def run
+        config   = RailsOrbit.configuration
+        servers  = ConfigReader.servers
+        user     = ConfigReader.ssh_user
+        key_path = config.kamal_ssh_key_path || ENV["ORBIT_SSH_KEY_PATH"]
+
+        unless key_path
+          Rails.logger.error "[rails_orbit] kamal_ssh_key_path must be set when kamal_enabled is true"
+          return
+        end
+
+        collector = StatsCollector.new
+        servers.each do |host|
+          stats = collector.collect(host: host, user: user, ssh_key_path: key_path)
+          stats.each do |s|
+            dimension = "#{s[:host]}/#{s[:container]}"
+            MetricWriter.write(key: "kamal.cpu_pct", value: s[:cpu_pct], dimension: dimension)
+            MetricWriter.write(key: "kamal.mem_pct", value: s[:mem_pct], dimension: dimension)
+          end
+        end
+      rescue => e
+        Rails.logger.error "[rails_orbit] Kamal poller error: #{e.class} - #{e.message}"
+      end
+    end
+  end
+end

data/lib/rails_orbit/kamal/stats_collector.rb

@@ -0,0 +1,42 @@
+module RailsOrbit
+  module Kamal
+    class StatsCollector
+      include SSHKit::DSL
+
+      def collect(host:, user:, ssh_key_path:)
+        require "sshkit"
+        require "sshkit/dsl"
+
+        output = nil
+        on(SSHKit::Host.new("#{user}@#{host}")) do
+          output = capture(:docker, "stats", "--no-stream", "--format",
+                           "{{.Name}} {{.CPUPerc}} {{.MemPerc}}")
+        end
+        parse(output, host: host)
+      rescue SSHKit::Command::Failed, SocketError => e
+        Rails.logger.error "[rails_orbit] SSH stats failed for #{host}: #{e.message}"
+        []
+      rescue => e
+        Rails.logger.error "[rails_orbit] SSH stats failed for #{host}: #{e.class} - #{e.message}"
+        []
+      end
+
+      private
+
+      def parse(raw, host:)
+        raw.to_s.lines.filter_map do |line|
+          parts = line.strip.split
+          next unless parts.size == 3
+          name, cpu, mem = parts
+          {
+            host:      host,
+            container: name,
+            cpu_pct:   cpu.to_f,
+            mem_pct:   mem.to_f,
+            at:        Time.current
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rails_orbit/metric_writer.rb

@@ -0,0 +1,37 @@
+require "concurrent"
+
+module RailsOrbit
+  module MetricWriter
+    class << self
+      def executor
+        @executor ||= Concurrent::SingleThreadExecutor.new(
+          fallback_policy: :discard
+        )
+      end
+
+      def write(key:, value:, dimension: nil)
+        executor.post do
+          RailsOrbit::ApplicationRecord.connection_pool.with_connection do
+            RailsOrbit::Metric.insert(
+              { key: key, value: value, dimension: dimension, recorded_at: Time.current },
+              returning: false
+            )
+          end
+        rescue => e
+          Rails.logger.error("[rails_orbit] MetricWriter failed: #{e.message}")
+        end
+      end
+
+      def shutdown
+        return unless defined?(@executor) && @executor
+        executor.shutdown
+        executor.wait_for_termination(5)
+      end
+
+      def reset!
+        shutdown
+        @executor = nil
+      end
+    end
+  end
+end

data/lib/rails_orbit/time_range.rb

@@ -0,0 +1,39 @@
+module RailsOrbit
+  class TimeRange
+    OPTIONS = {
+      "1h"  => { minutes: 60,    bucket_minutes: 1,  delta_window: 15.minutes, label: "1h" },
+      "6h"  => { minutes: 360,   bucket_minutes: 5,  delta_window: 1.hour,     label: "6h" },
+      "24h" => { minutes: 1440,  bucket_minutes: 15, delta_window: 1.hour,     label: "24h" },
+      "7d"  => { minutes: 10080, bucket_minutes: 60, delta_window: 6.hours,    label: "7d" },
+      "30d" => { minutes: 43200, bucket_minutes: 360, delta_window: 1.day,     label: "30d" },
+    }.freeze
+
+    attr_reader :key
+
+    def initialize(param)
+      @key = OPTIONS.key?(param) ? param : "24h"
+    end
+
+    def since
+      config[:minutes].minutes.ago
+    end
+
+    def bucket_minutes
+      config[:bucket_minutes]
+    end
+
+    def delta_window
+      config[:delta_window]
+    end
+
+    def label
+      config[:label]
+    end
+
+    private
+
+    def config
+      OPTIONS[@key]
+    end
+  end
+end

data/lib/rails_orbit/version.rb

@@ -0,0 +1,3 @@
+module RailsOrbit
+  VERSION = "0.1.0"
+end

data/lib/rails_orbit.rb

@@ -0,0 +1,24 @@
+require "rails_orbit/version"
+require "rails_orbit/configuration"
+require "rails_orbit/time_range"
+require "rails_orbit/database_setup"
+require "rails_orbit/metric_writer"
+require "rails_orbit/instrumentation"
+require "rails_orbit/engine"
+
+module RailsOrbit
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/tasks/rails_orbit.rake

@@ -0,0 +1,60 @@
+namespace :rails_orbit do
+  desc "Create the rails_orbit_metrics table in the configured database"
+  task setup: :environment do
+    conn   = RailsOrbit::ApplicationRecord.connection
+    table  = RailsOrbit::Metric.table_name
+    config = RailsOrbit.configuration
+
+    puts "[rails_orbit] Storage adapter: #{config.storage_adapter}"
+    puts "[rails_orbit] Database adapter: #{conn.adapter_name.downcase}"
+    puts "[rails_orbit] Table name: #{table}"
+
+    if conn.table_exists?(table)
+      puts "[rails_orbit] Table '#{table}' already exists. Nothing to do."
+      next
+    end
+
+    RailsOrbit::DatabaseSetup.new(conn).run!
+    puts "[rails_orbit] Created '#{table}' table with indexes."
+  end
+
+  desc "Show rails_orbit configuration and table status"
+  task status: :environment do
+    config  = RailsOrbit.configuration
+    conn    = RailsOrbit::ApplicationRecord.connection
+    table   = RailsOrbit::Metric.table_name
+    adapter = conn.adapter_name.downcase
+
+    puts ""
+    puts "rails_orbit status"
+    puts "-" * 40
+    puts "  Storage adapter:  #{config.storage_adapter}"
+    puts "  Database adapter: #{adapter}"
+    puts "  Table name:       #{table}"
+    puts "  Table exists:     #{conn.table_exists?(table)}"
+
+    if conn.table_exists?(table)
+      count = conn.select_value("SELECT COUNT(*) FROM #{conn.quote_table_name(table)}")
+      oldest = conn.select_value("SELECT MIN(recorded_at) FROM #{conn.quote_table_name(table)}")
+      newest = conn.select_value("SELECT MAX(recorded_at) FROM #{conn.quote_table_name(table)}")
+      puts "  Metric count:     #{count}"
+      puts "  Oldest metric:    #{oldest || 'none'}"
+      puts "  Newest metric:    #{newest || 'none'}"
+    end
+
+    if config.storage_adapter == :sqlite
+      db_path = conn.pool.db_config.configuration_hash[:database]
+      puts "  SQLite path:      #{db_path}"
+      if File.exist?(db_path.to_s)
+        size_kb = (File.size(db_path.to_s) / 1024.0).round(1)
+        puts "  SQLite size:      #{size_kb} KB"
+      end
+    end
+
+    puts "  Retention days:   #{config.retention_days}"
+    puts "  Poll interval:    #{config.poll_interval}s"
+    puts "  Dashboard title:  #{config.dashboard_title}"
+    puts "  Kamal enabled:    #{config.kamal_enabled}"
+    puts ""
+  end
+end