upstate-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4783aff7c6640fdf83df97d8c490f32dfa6269dd242628a8d8a177986b229116
+  data.tar.gz: b2684f1698caa10a91248c4950e30ccd38a33ec6002b8bcda4b68104477b7a8f
+SHA512:
+  metadata.gz: b1b8c3b7dbc87385211de8fd8736aa96d145ee13c7dc937ac7c219f36fbea7a7e38bdec69e5dede781d46b9a89d0ada46d5de3f7a7a87a0a0fae4a32ed2cd3b7
+  data.tar.gz: 8c371fa288593ebae53746217b318bf393fd5c0144d6a558982dbad760ee793b82f0686924b6ea4a088cb50f7790e0bbd65ab5cabf3858c554dab01920c48bb5

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `GET /upstate/health` (schema 1) with boot facts, migrations, DB pool, Puma,
+  Solid Queue / Sidekiq / GoodJob job numbers, cache probe, and per-minute action rollups.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Upstate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# upstate-rails
+
+Rails app health for [Upstate](https://upstate.cloud): boot facts, migrations, Puma, jobs, and the slowest actions. Counts only.
+
+The gem adds one endpoint, `GET /upstate/health`. Upstate's host observer reads it from inside your server, over your private Docker network, every minute. Nothing else is installed, and nothing is sent anywhere by the gem itself.
+
+## What is sent
+
+- App version (`APP_VERSION`, else `KAMAL_VERSION`, else `unknown`), Rails and Ruby versions, whether YJIT is on, when the process booted.
+- Whether the database answers, and whether migrations are pending.
+- Active Record pool size, busy and waiting connections.
+- Puma workers, threads, backlog and spare capacity.
+- Job numbers for Solid Queue, Sidekiq or GoodJob: queue depth, oldest queued age, worker count, jobs processed and failed in the last 5 minutes, and when something last ran.
+- Whether your cache (Solid Cache or Redis) answers.
+- For the last 15 minutes, the 10 slowest `Controller#action` names per minute, with request count, error count, a 12-bucket timing histogram, and total database time.
+
+## What is never sent
+
+No params, URLs or paths, SQL, IP addresses, user agents, headers, cookies, job arguments, exception classes or messages, logs, or traces. An error is only a count (a 5xx response or an unhandled exception). Job queue names and job class names are not read either.
+
+## Install
+
+```ruby
+# Gemfile
+gem "upstate-rails"
+```
+
+```sh
+bundle install
+bin/rails g upstate:install
+```
+
+The endpoint is off until `UPSTATE_HEALTH_TOKEN` is set. Without it, `/upstate/health` returns 404. With a missing or wrong token it returns 401.
+
+## Kamal secrets
+
+1. In Upstate, open the environment page and generate a health token. It is shown once.
+2. Add it to `.kamal/secrets`:
+
+   ```sh
+   UPSTATE_HEALTH_TOKEN=<the token>
+   ```
+
+3. List it in `config/deploy.yml`:
+
+   ```yaml
+   env:
+     secret:
+       - UPSTATE_HEALTH_TOKEN
+   ```
+
+4. `kamal deploy`.
+
+The generator appends a commented example to `config/deploy.yml` only when `UPSTATE_HEALTH_TOKEN` is not already in the file.
+
+## Verify
+
+```sh
+curl -i -H "Authorization: Bearer $UPSTATE_HEALTH_TOKEN" https://your-app.example.com/upstate/health
+```
+
+You should get `200` and JSON starting with `"schema": 1`. A `503` means the database is not answering (the JSON says so). Anything with a slow, missing or erroring section reports that section as `null` and still returns the rest.
+
+## Good to know
+
+- The route is added ahead of your routes, so a catch-all route cannot hide it.
+- The path is excluded from `config.host_authorization` and from the `force_ssl` redirect, because the observer calls the container's private IP over plain HTTP. Nothing else changes in those settings.
+- Action timings are kept in memory per Puma worker and written to `Dir.tmpdir/upstate-rails/<pid>.json` about once a minute (not on every request). The endpoint merges the files of live processes. Files older than 20 minutes are ignored.
+- Sidekiq keeps lifetime counters only, so `processed_last_5m` and `failed_last_5m` are `null` until the gem has seen two readings at least 30 seconds apart in one process.
+- In Puma cluster mode, a worker answering the request sees the other workers through the master's last snapshot, so Puma numbers are best effort.
+- Requires Ruby 3.1+ and Rails 7.1+. No other runtime gems.
+
+## Migrating from the v0 controller
+
+If you copied `upstate_health_controller.rb` and its route into your app, remove both: delete `app/controllers/upstate_health_controller.rb` and the `get "/upstate/health"` line in `config/routes.rb`. Keep the same `UPSTATE_HEALTH_TOKEN`. The gem's response is a superset of the v0 response (including the same `solid_queue` block), so Upstate keeps working through the change.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle install && BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
+```
+
+CI runs Rails 7.2 and 8.0 on Ruby 3.2 to 3.4.
+
+## License
+
+MIT.

data/lib/generators/upstate/install/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Upstate
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc "Prints the steps to turn on Upstate Rails app health (GET /upstate/health)."
+
+      DEPLOY_EXAMPLE = <<~YAML
+
+        # Upstate app health: add UPSTATE_HEALTH_TOKEN to .kamal/secrets, then uncomment.
+        # env:
+        #   secret:
+        #     - UPSTATE_HEALTH_TOKEN
+      YAML
+
+      def append_deploy_example
+        path = File.join(destination_root, "config/deploy.yml")
+        return unless File.exist?(path)
+        return if File.read(path).include?("UPSTATE_HEALTH_TOKEN")
+
+        append_to_file "config/deploy.yml", DEPLOY_EXAMPLE
+      end
+
+      def print_steps
+        say <<~TEXT
+
+          Upstate Rails app health is installed. The endpoint is off until you set a token.
+
+          1. In Upstate, open the environment page and generate a health token (shown once).
+          2. Add it to .kamal/secrets:
+               UPSTATE_HEALTH_TOKEN=<the token>
+          3. List it under env.secret in config/deploy.yml:
+               env:
+                 secret:
+                   - UPSTATE_HEALTH_TOKEN
+          4. Deploy, then check it:
+               curl -H "Authorization: Bearer $UPSTATE_HEALTH_TOKEN" https://your-app.example.com/upstate/health
+
+          Without the token the path returns 404. With a wrong token it returns 401.
+        TEXT
+      end
+    end
+  end
+end

data/lib/upstate/rails/action_rollup.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Upstate
+  module Rails
+    # Per-process, thread-safe, bounded rollup of controller actions per minute.
+    # Stores only: name, count, error count, duration buckets, db ms, total ms.
+    class ActionRollup
+      # Upper bounds in ms, inclusive; the 12th bucket is +inf.
+      BUCKETS_MS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10_000].freeze
+      MAX_NAMES_PER_MINUTE = 200
+      RETAIN_MINUTES = 20
+      FLUSH_INTERVAL = 5
+
+      def self.bucket_index(ms)
+        BUCKETS_MS.index { |upper| ms <= upper } || BUCKETS_MS.size
+      end
+
+      def initialize(clock: -> { Time.now }, dir: ActionStore.dir)
+        @clock = clock
+        @dir = dir
+        @mutex = Mutex.new
+        reset!
+      end
+
+      def record(name, duration_ms, db_ms, error)
+        @mutex.synchronize do
+          reset! if @pid != Process.pid # forked (Puma cluster, preload_app)
+          now = @clock.call
+          minute = now.to_i / 60
+          names = (@minutes[minute] ||= {})
+          entry = names[name] || (names.size < MAX_NAMES_PER_MINUTE ? (names[name] = blank) : nil)
+          if entry
+            entry[:count] += 1
+            entry[:errors] += 1 if error
+            entry[:buckets][self.class.bucket_index(duration_ms.to_f)] += 1
+            entry[:db_ms] += db_ms.to_f
+            entry[:total_ms] += duration_ms.to_f
+          end
+          @minutes.delete_if { |m, _| m < minute - RETAIN_MINUTES }
+          flush_locked(now, force: false)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # Writes closed minutes to disk. force: skips the interval throttle.
+      def flush!(force: true)
+        @mutex.synchronize { flush_locked(@clock.call, force: force) }
+      rescue StandardError
+        nil
+      end
+
+      def snapshot_closed(now = @clock.call)
+        current = now.to_i / 60
+        @mutex.synchronize do
+          @minutes.select { |m, _| m < current }.transform_values { |names| top(names) }
+        end
+      end
+
+      private
+
+      def reset!
+        @pid = Process.pid
+        @minutes = {}
+        @flushed_through = nil
+        @last_flush = 0
+      end
+
+      def blank
+        {count: 0, errors: 0, buckets: Array.new(ActionStore::BUCKETS, 0), db_ms: 0.0, total_ms: 0.0}
+      end
+
+      def top(names)
+        names.sort_by { |_, e| -e[:total_ms] }.first(ActionStore::TOP).to_h.transform_values do |e|
+          {"count" => e[:count], "errors" => e[:errors], "buckets" => e[:buckets],
+           "db_ms" => e[:db_ms].round(1), "total_ms" => e[:total_ms].round(1)}
+        end
+      end
+
+      # Disk IO only when a new minute has closed since the last write, and at most
+      # once per FLUSH_INTERVAL seconds.
+      def flush_locked(now, force:)
+        current = now.to_i / 60
+        closed = @minutes.keys.select { |m| m < current }
+        return if closed.empty?
+
+        latest = closed.max
+        return if !force && (@flushed_through == latest || (now.to_f - @last_flush) < FLUSH_INTERVAL)
+        return if force && @flushed_through == latest
+
+        payload = closed.to_h { |m| [m, top(@minutes[m])] }
+        ActionStore.write(Process.pid, payload, dir: @dir)
+        @flushed_through = latest
+        @last_flush = now.to_f
+      end
+    end
+  end
+end

data/lib/upstate/rails/action_store.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    # Reads and writes per-process rollup files in Dir.tmpdir/upstate-rails/<pid>.json.
+    # File shape: {"schema":1,"pid":1,"minutes":{"<epoch minute>":{"Name#action":{...}}}}
+    module ActionStore
+      BUCKETS = 12
+      MAX_AGE = 20 * 60
+      MAX_FILE_BYTES = 512 * 1024
+      MAX_NAME = 200
+      TOP = 10
+
+      module_function
+
+      def dir
+        File.join(Dir.tmpdir, "upstate-rails")
+      end
+
+      # Atomic: write a temp file in the same directory, then rename over the target.
+      def write(pid, minutes, dir: self.dir)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        target = File.join(dir, "#{pid}.json")
+        tmp = "#{target}.#{SecureRandom.hex(4)}.tmp"
+        File.write(tmp, JSON.generate("schema" => 1, "pid" => pid, "minutes" => minutes.transform_keys(&:to_s)), perm: 0o600)
+        File.rename(tmp, target)
+      ensure
+        File.delete(tmp) if tmp && File.exist?(tmp)
+      end
+
+      # Merges every live pid file into [{minute: Time, items: [...]}], the last `window`
+      # closed minutes, ascending, top TOP items per minute by total time.
+      def merged(now: Time.now, window: 15, dir: self.dir)
+        current = now.to_i / 60
+        range = (current - window)...current
+        acc = Hash.new { |h, k| h[k] = {} }
+
+        each_file(now: now, dir: dir) do |data|
+          data["minutes"].each do |minute, items|
+            m = minute.to_i
+            next unless range.cover?(m)
+
+            items.each do |name, e|
+              entry = acc[m][name] ||= {count: 0, errors: 0, buckets: Array.new(BUCKETS, 0), db_ms: 0.0, total_ms: 0.0}
+              entry[:count] += e["count"]
+              entry[:errors] += e["errors"]
+              entry[:db_ms] += e["db_ms"]
+              entry[:total_ms] += e["total_ms"]
+              e["buckets"].each_with_index { |c, i| entry[:buckets][i] += c }
+            end
+          end
+        end
+
+        acc.keys.sort.map do |m|
+          top = acc[m].sort_by { |_, e| -e[:total_ms] }.first(TOP)
+          {
+            minute: Time.at(m * 60).utc,
+            items: top.map do |name, e|
+              {name: name, count: e[:count], errors: e[:errors], duration_buckets: e[:buckets], db_ms: e[:db_ms].round}
+            end
+          }
+        end
+      end
+
+      def each_file(now:, dir:)
+        Dir.glob(File.join(dir, "*.json")).each do |path|
+          pid = File.basename(path)[/\A(\d+)\.json\z/, 1]&.to_i
+          next unless pid
+          next if (now.to_i - File.mtime(path).to_i) > MAX_AGE
+          next unless alive?(pid)
+          next if File.size(path) > MAX_FILE_BYTES
+
+          data = sanitize(JSON.parse(File.read(path)))
+          yield data if data
+        rescue StandardError
+          next
+        end
+      end
+
+      def alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+
+      # Defensive: files are local but not trusted. Keep only well-typed numbers and short names.
+      def sanitize(data)
+        return unless data.is_a?(Hash) && data["schema"] == 1 && data["minutes"].is_a?(Hash)
+
+        minutes = {}
+        data["minutes"].each do |minute, items|
+          next unless minute.to_s.match?(/\A\d+\z/) && items.is_a?(Hash)
+
+          clean = {}
+          items.each do |name, e|
+            next unless name.is_a?(String) && e.is_a?(Hash)
+
+            b = e["buckets"]
+            next unless b.is_a?(Array) && b.size == BUCKETS && b.all?(Integer)
+            next unless %w[count errors].all? { |k| e[k].is_a?(Integer) } && %w[db_ms total_ms].all? { |k| e[k].is_a?(Numeric) }
+
+            clean[name[0, MAX_NAME]] = e
+          end
+          minutes[minute] = clean
+        end
+        {"minutes" => minutes}
+      end
+    end
+  end
+end

data/lib/upstate/rails/endpoint.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    # Rack endpoint for GET /upstate/health.
+    class Endpoint
+      MAX_TOKEN_BYTES = 256
+
+      def call(env)
+        expected = ENV["UPSTATE_HEALTH_TOKEN"].to_s
+        return respond(404, "") if expected.empty?
+        return respond(401, "", "www-authenticate" => "Bearer") unless authorized?(env["HTTP_AUTHORIZATION"], expected)
+
+        status, body = Health.call
+        respond(status, JSON.generate(body), "content-type" => "application/json")
+      end
+
+      private
+
+      def authorized?(header, expected)
+        header = header.to_s
+        return false unless header.start_with?("Bearer ")
+
+        supplied = header.delete_prefix("Bearer ")
+        return false if supplied.empty? || supplied.bytesize > MAX_TOKEN_BYTES
+
+        ActiveSupport::SecurityUtils.secure_compare(Digest::SHA256.hexdigest(supplied), Digest::SHA256.hexdigest(expected))
+      end
+
+      def respond(status, body, headers = {})
+        [status, {"cache-control" => "no-store", "content-length" => body.bytesize.to_s}.merge(headers), [body]]
+      end
+    end
+  end
+end

data/lib/upstate/rails/health.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    # Builds the schema 1 response. Every section rescues its own errors and reports nil.
+    class Health
+      SCHEMA = 1
+
+      def self.call(now: Time.now)
+        new(now).call
+      end
+
+      def initialize(now)
+        @now = now
+      end
+
+      # => [http_status, body_hash]
+      def call
+        database = section { Sections.database }
+        jobs, solid_queue = section { Jobs.call(now: @now) } || [nil, nil]
+
+        body = {
+          schema: SCHEMA,
+          version: version,
+          rails: section { {version: ::Rails.version, environment: ::Rails.env.to_s} },
+          ruby: section { {version: RUBY_VERSION, yjit: yjit?} },
+          booted_at: BOOTED_AT.iso8601,
+          database: database,
+          active_record_pool: section { Sections.active_record_pool },
+          puma: section { Sections.puma },
+          jobs: jobs,
+          cache: section { Sections.cache },
+          actions: section { actions }
+        }
+        body[:solid_queue] = solid_queue if solid_queue
+
+        status = database && database[:ok] == false ? 503 : 200
+        [status, body]
+      end
+
+      private
+
+      def version
+        [ENV["APP_VERSION"], ENV["KAMAL_VERSION"]].find { |v| !v.to_s.strip.empty? }&.strip || "unknown"
+      end
+
+      def yjit?
+        !!(defined?(::RubyVM::YJIT) && ::RubyVM::YJIT.enabled?)
+      end
+
+      def actions
+        Upstate::Rails.rollup.flush!
+        ActionStore.merged(now: @now).map { |m| {minute: m[:minute].iso8601, items: m[:items]} }
+      end
+
+      def section
+        yield
+      rescue StandardError, NotImplementedError
+        nil
+      end
+    end
+  end
+end

data/lib/upstate/rails/jobs/good_job.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    module Jobs
+      # Uses GoodJob's tables (GoodJob 3+/4: GoodJob::Job, GoodJob::Process).
+      module GoodJobAdapter
+        module_function
+
+        def call(now: Time.now)
+          queued = ::GoodJob::Job.where(finished_at: nil, performed_at: nil, scheduled_at: ..now)
+          oldest = queued.minimum(:scheduled_at)
+          since = now - 300
+          finished = ::GoodJob::Job.where(finished_at: since..)
+          recent = [::GoodJob::Job.maximum(:performed_at), ::GoodJob::Job.maximum(:finished_at)].compact.max
+
+          jobs = {
+            adapter: "good_job",
+            queue_depth: queued.count,
+            oldest_queued_age_seconds: oldest && [now.to_i - oldest.to_i, 0].max,
+            workers: ::GoodJob::Process.where(updated_at: (now - 120)..).count,
+            processed_last_5m: finished.count,
+            failed_last_5m: finished.where.not(error: nil).count,
+            recent_processing_at: recent&.utc&.iso8601
+          }
+          [jobs, nil]
+        end
+      end
+    end
+  end
+end

data/lib/upstate/rails/jobs/sidekiq.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    module Jobs
+      # Sidekiq keeps lifetime counters, so the last-5-minute numbers are deltas between
+      # samples taken by this process. Until two samples span time, they are null.
+      module SidekiqAdapter
+        WINDOW = 300
+        MAX_SAMPLES = 64
+        MUTEX = Mutex.new
+        SAMPLES = []
+
+        module_function
+
+        def reset_samples!
+          MUTEX.synchronize { SAMPLES.clear }
+        end
+
+        def call(now: Time.now)
+          stats = ::Sidekiq::Stats.new
+          depth = stats.enqueued
+          oldest = depth.to_i.positive? ? ::Sidekiq::Queue.all.map { |q| q.latency.to_f }.max : nil
+          processed, failed = deltas(now, stats.processed.to_i, stats.failed.to_i)
+
+          jobs = {
+            adapter: "sidekiq",
+            queue_depth: depth.to_i,
+            oldest_queued_age_seconds: oldest && oldest.floor,
+            workers: ::Sidekiq::ProcessSet.new.size,
+            processed_last_5m: processed,
+            failed_last_5m: failed,
+            recent_processing_at: nil
+          }
+          [jobs, nil]
+        end
+
+        def deltas(now, processed, failed)
+          MUTEX.synchronize do
+            SAMPLES.reject! { |t, _, _| now.to_f - t > WINDOW + 60 }
+            base = SAMPLES.find { |t, _, _| now.to_f - t >= 30 }
+            SAMPLES << [now.to_f, processed, failed]
+            SAMPLES.shift while SAMPLES.size > MAX_SAMPLES
+            return [nil, nil] unless base && processed >= base[1] && failed >= base[2]
+
+            [processed - base[1], failed - base[2]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/upstate/rails/jobs/solid_queue.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    module Jobs
+      # Uses the Solid Queue tables (the same queries as the v0 controller).
+      module SolidQueueAdapter
+        module_function
+
+        def call(now: Time.now)
+          ready = ::SolidQueue::ReadyExecution
+          oldest = ready.minimum(:created_at)
+          recent_claim = ::SolidQueue::ClaimedExecution.maximum(:created_at)
+          recent_finish = ::SolidQueue::Job.where.not(finished_at: nil).maximum(:finished_at)
+          recent = [recent_claim, recent_finish].compact.max
+          since = now - 300
+
+          block = {
+            workers: ::SolidQueue::Process.where(kind: "Worker").where(last_heartbeat_at: (now - 120)..).count,
+            queue_depth: ready.count,
+            oldest_queued_age_seconds: oldest && [now.to_i - oldest.to_i, 0].max,
+            recent_processing_at: recent&.utc&.iso8601
+          }
+
+          jobs = block.merge(
+            adapter: "solid_queue",
+            processed_last_5m: ::SolidQueue::Job.where(finished_at: since..).count,
+            failed_last_5m: ::SolidQueue::FailedExecution.where(created_at: since..).count
+          )
+          [jobs, block]
+        end
+      end
+    end
+  end
+end

data/lib/upstate/rails/jobs.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    module Jobs
+      NO_QUEUE = %w[async inline test].freeze
+
+      module_function
+
+      # Returns [jobs_hash, solid_queue_block_or_nil]. Raises if the adapter's store is unreachable.
+      def call(now: Time.now)
+        case adapter_name
+        when "solid_queue" then SolidQueueAdapter.call(now: now)
+        when "sidekiq" then SidekiqAdapter.call(now: now)
+        when "good_job" then GoodJobAdapter.call(now: now)
+        when "none" then [empty("none"), nil]
+        else [empty("unsupported"), nil]
+        end
+      end
+
+      def adapter_name
+        return "none" unless defined?(::ActiveJob::Base)
+
+        name = ::ActiveJob::Base.queue_adapter_name.to_s
+        return name if %w[solid_queue sidekiq good_job].include?(name)
+        return "none" if NO_QUEUE.include?(name) || name.empty?
+
+        "unsupported"
+      rescue StandardError
+        "unsupported"
+      end
+
+      def empty(adapter)
+        {adapter: adapter, queue_depth: nil, oldest_queued_age_seconds: nil, workers: nil,
+         processed_last_5m: nil, failed_last_5m: nil, recent_processing_at: nil}
+      end
+    end
+  end
+end

data/lib/upstate/rails/railtie.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    class Railtie < ::Rails::Railtie
+      # Prepended (not appended) so a catch-all route in the host app cannot shadow it.
+      initializer "upstate_rails.routes" do |app|
+        app.routes.prepend do
+          get Upstate::Rails::PATH, to: Upstate::Rails::Endpoint.new
+        end
+      end
+
+      # The observer calls the container IP over plain HTTP, so Host authorization and
+      # force_ssl redirects must not apply to the health path.
+      initializer "upstate_rails.exclusions", before: :build_middleware_stack do |app|
+        path = Upstate::Rails::PATH
+        wrap = lambda do |existing|
+          ->(request) { request.path == path || (existing.respond_to?(:call) && existing.call(request)) }
+        end
+
+        hosts = (app.config.host_authorization || {}).dup
+        hosts[:exclude] = wrap.call(hosts[:exclude])
+        app.config.host_authorization = hosts
+
+        ssl = (app.config.ssl_options || {}).dup
+        redirect = ssl[:redirect]
+        redirect = {} unless redirect.is_a?(Hash)
+        ssl[:redirect] = redirect.merge(exclude: wrap.call(redirect[:exclude]))
+        app.config.ssl_options = ssl
+      end
+
+      # Collect action rollups only when the endpoint is switched on.
+      config.after_initialize do
+        next if ENV["UPSTATE_HEALTH_TOKEN"].to_s.empty?
+
+        Upstate::Rails.subscribe!
+        at_exit { Upstate::Rails.rollup.flush! }
+      end
+
+      generators do
+        require "generators/upstate/install/install_generator"
+      end
+    end
+  end
+end

data/lib/upstate/rails/sections.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    module Sections
+      module_function
+
+      def database
+        return nil unless defined?(::ActiveRecord::Base)
+
+        ok = begin
+          ::ActiveRecord::Base.connection_pool.with_connection { |c| c.select_value("SELECT 1") }
+          true
+        rescue StandardError
+          false
+        end
+        return {ok: false, pending_migrations: nil} unless ok
+
+        {ok: true, pending_migrations: pending_migrations}
+      end
+
+      # ConnectionPool#migration_context exists on 7.1+; older shapes fall back to the connection.
+      def pending_migrations
+        pool = ::ActiveRecord::Base.connection_pool
+        context = if pool.respond_to?(:migration_context)
+          pool.migration_context
+        else
+          pool.with_connection(&:migration_context)
+        end
+        context.needs_migration?
+      rescue StandardError
+        nil
+      end
+
+      def active_record_pool
+        return nil unless defined?(::ActiveRecord::Base)
+
+        stat = ::ActiveRecord::Base.connection_pool.stat
+        {size: stat[:size], busy: stat[:busy], waiting: stat[:waiting]}
+      end
+
+      # Sums across cluster workers. In cluster mode a worker's view of its siblings comes
+      # from the master's last snapshot, so values are best effort.
+      def puma
+        return nil unless defined?(::Puma) && ::Puma.respond_to?(:stats_hash)
+
+        stats = ::Puma.stats_hash
+        return nil unless stats.is_a?(Hash) && !stats.empty?
+
+        stats = stats.transform_keys(&:to_sym)
+        if stats[:worker_status]
+          statuses = stats[:worker_status].map { |w| (w[:last_status] || w["last_status"] || {}).transform_keys(&:to_sym) }
+          {
+            workers: stats[:workers],
+            booted_workers: stats[:booted_workers],
+            max_threads: sum(statuses, :max_threads),
+            backlog: sum(statuses, :backlog),
+            pool_capacity: sum(statuses, :pool_capacity)
+          }
+        else
+          {workers: 1, booted_workers: 1, max_threads: stats[:max_threads],
+           backlog: stats[:backlog], pool_capacity: stats[:pool_capacity]}
+        end
+      end
+
+      def sum(rows, key)
+        values = rows.filter_map { |r| r[key] }
+        values.empty? ? nil : values.sum
+      end
+
+      PROBED = {"SolidCache::Store" => "solid_cache", "ActiveSupport::Cache::RedisCacheStore" => "redis_cache_store"}.freeze
+
+      # Matches by class name, never by constant, so autoloaded stores (and their gems)
+      # are not loaded just to be compared against.
+      def cache
+        store = ::Rails.cache
+        name = store.class.ancestors.filter_map { |k| PROBED[k.name] }.first
+        return nil unless name
+
+        key = "upstate:health-probe"
+        store.write(key, "1", expires_in: 60)
+        {store: name, ok: store.read(key) == "1"}
+      rescue StandardError
+        name ? {store: name, ok: false} : nil
+      end
+    end
+  end
+end

data/lib/upstate/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Upstate
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/upstate/rails.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "time"
+require "tmpdir"
+require "securerandom"
+require "active_support"
+require "active_support/notifications"
+require "active_support/security_utils"
+require "rails/railtie"
+
+require_relative "rails/version"
+
+# NOTE: inside this namespace, `Rails` means Upstate::Rails. Use `::Rails` for the framework.
+module Upstate
+  module Rails
+    PATH = "/upstate/health"
+    BOOTED_AT = Time.now.utc.freeze
+
+    class << self
+      # The per-process action rollup. Replaceable in tests.
+      attr_writer :rollup
+
+      def rollup
+        @rollup ||= ActionRollup.new
+      end
+
+      # Subscribes once to process_action.action_controller.
+      def subscribe!
+        return if @subscriber
+
+        @subscriber = ActiveSupport::Notifications.subscribe("process_action.action_controller") do |event|
+          record_event(event)
+        end
+      end
+
+      def unsubscribe!
+        ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+        @subscriber = nil
+      end
+
+      private
+
+      # Never raises into the request. Only the controller#action name, timings and an
+      # error flag are kept; params, paths, SQL and exception details are not read.
+      def record_event(event)
+        payload = event.payload
+        status = payload[:status].to_i
+        error = status >= 500 || !payload[:exception].nil? || !payload[:exception_object].nil?
+        rollup.record("#{payload[:controller]}##{payload[:action]}", event.duration, payload[:db_runtime], error)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end
+
+require_relative "rails/action_store"
+require_relative "rails/action_rollup"
+require_relative "rails/jobs/solid_queue"
+require_relative "rails/jobs/sidekiq"
+require_relative "rails/jobs/good_job"
+require_relative "rails/jobs"
+require_relative "rails/sections"
+require_relative "rails/health"
+require_relative "rails/endpoint"
+require_relative "rails/railtie"

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: upstate-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Upstate
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'Adds a bearer-protected GET /upstate/health to a Rails app. Reports
+  aggregate counts and fixed-bucket timings only: no params, paths, SQL, IPs, user
+  agents, or job arguments.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/upstate/install/install_generator.rb
+- lib/upstate/rails.rb
+- lib/upstate/rails/action_rollup.rb
+- lib/upstate/rails/action_store.rb
+- lib/upstate/rails/endpoint.rb
+- lib/upstate/rails/health.rb
+- lib/upstate/rails/jobs.rb
+- lib/upstate/rails/jobs/good_job.rb
+- lib/upstate/rails/jobs/sidekiq.rb
+- lib/upstate/rails/jobs/solid_queue.rb
+- lib/upstate/rails/railtie.rb
+- lib/upstate/rails/sections.rb
+- lib/upstate/rails/version.rb
+homepage: https://github.com/Upstate-run/upstate-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Upstate-run/upstate-rails
+  source_code_uri: https://github.com/Upstate-run/upstate-rails
+  changelog_uri: https://github.com/Upstate-run/upstate-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: 'Rails app health for Upstate: boot facts, migrations, Puma, jobs, and slowest
+  actions. Counts only.'
+test_files: []