rails_pulse 0.4.0.pre.2 → 0.4.0.pre.4

data/lib/generators/rails_pulse/templates/rails_pulse.rb

@@ -314,6 +314,18 @@ RailsPulse.configure do |config|
   #   end
   # }
 
+  # STANDALONE DASHBOARD (bin/rails_pulse_server, see docs/deployment-modes.md):
+  # that process has your models but not your app's session, Warden or Devise
+  # helpers, and runs on its own hostname, so the hooks above are ignored there.
+  # By default it uses HTTP Basic auth (RAILS_PULSE_USERNAME / RAILS_PULSE_PASSWORD).
+  # Set this to run something else instead; same rules as authentication_method
+  # (deny by rendering or redirecting, or by returning false).
+  # config.standalone_authentication_method = proc {
+  #   authenticate_or_request_with_http_token do |token, _options|
+  #     ActiveSupport::SecurityUtils.secure_compare(token, ENV["RAILS_PULSE_DASHBOARD_TOKEN"].to_s)
+  #   end
+  # }
+
   # ====================================================================================================
   #                                             DEPLOYMENT TRACKING
   # ====================================================================================================
@@ -338,8 +350,11 @@ RailsPulse.configure do |config|
   #     -H "Content-Type: application/json" \
   #     -d '{"deployment": {"revision": "abc1234", "metadata": {"environment": "production"}}}'
   #
-  # Or use the rake task for simple shell-based deploys:
+  # Or use the rake tasks for shell-based deploys (no token or HTTP access needed):
   #   rake rails_pulse:record_deployment[abc1234]
+  #   rake rails_pulse:finish_deployment[abc1234]
+  # Metadata for the rake task comes from an environment variable, as a JSON object:
+  #   RAILS_PULSE_DEPLOYMENT_METADATA='{"environment":"production"}' rake rails_pulse:record_deployment[abc1234]
 
   # config.deployment_api_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
 
@@ -422,6 +437,12 @@ RailsPulse.configure do |config|
   # Show a dashboard banner when summary data is stale (default: true)
   # config.warn_on_stale_summaries = true
 
+  # When this gem version is newer than the Rails Pulse tables it is connected
+  # to (deployed before `db:migrate`, or a rolling restart), pause tracking after
+  # one logged warning and answer every dashboard page with a 503 that lists the
+  # upgrade commands, instead of erroring on each request (default: true).
+  # config.schema_check_enabled = true
+
   # Set to false to skip dashboard middleware and asset serving entirely.
   # Useful for standalone/API-only deployments that use a separate dashboard app.
   # config.mount_dashboard = true

data/lib/generators/rails_pulse/upgrade_generator.rb

@@ -170,11 +170,7 @@ module RailsPulse
         missing_columns = detect_missing_columns
 
         if missing_columns.empty?
-          if @initializer_updated
-            say "Schema is up to date. Review initializer changes with git diff.", :green
-          else
-            say "Rails Pulse is up to date! No migration needed.", :green
-          end
+          report_outstanding_work(migrate_command)
           return
         end
 
@@ -203,6 +199,61 @@ module RailsPulse
         add_null_action_unique_index_to_routes
       ].freeze
 
+      # "Rails Pulse is up to date! No migration needed." used to be printed
+      # whenever every migration *file* was already in the app — including the
+      # common case where they were copied in one deploy and have not yet been
+      # run against this database, or where the schema migrated but
+      # `rails_pulse:migrate_routes` is still outstanding. A host in that state
+      # is one deploy away from the 0.4 gem running against 0.3 tables. Say
+      # what is actually left instead.
+      def report_outstanding_work(migrate_command)
+        pending = pending_migration_files
+        backfill = route_backfill_outstanding?
+
+        if pending.empty? && !backfill
+          if @initializer_updated
+            say "Schema is up to date. Review initializer changes with git diff.", :green
+          else
+            say "Rails Pulse is up to date! No migration needed.", :green
+          end
+          return
+        end
+
+        say "All of this version's migration files are present, but this database is not up to date:", :yellow
+        if pending.any?
+          say "  #{pending.size} migration file(s) have not been run:", :yellow
+          pending.each { |filename| say "    - #{filename}", :yellow }
+        end
+        say "  Route actions have not been backfilled.", :yellow if backfill
+
+        include_route_backfill = backfill || requires_route_backfill?(pending)
+        say_route_backfill_warning if include_route_backfill
+        say_next_steps(migrate_command, include_route_backfill: include_route_backfill)
+      end
+
+      # Migration files on disk whose version is not recorded on the connection
+      # this install uses. Any failure (no database, stubbed connection) reads
+      # as "nothing pending" so the generator never blocks on it.
+      def pending_migration_files
+        pool = if @is_separate_db && defined?(RailsPulse::ApplicationRecord)
+          RailsPulse::ApplicationRecord.connection_pool
+        else
+          ActiveRecord::Base.connection_pool
+        end
+        context = pool.migration_context
+        applied = context.get_all_versions
+        context.migrations.reject { |migration| applied.include?(migration.version) }
+               .map { |migration| File.basename(migration.filename) }
+      rescue StandardError
+        []
+      end
+
+      def route_backfill_outstanding?
+        defined?(RailsPulse::Route) && RailsPulse::Route.needs_action_backfill?
+      rescue StandardError
+        false
+      end
+
       def requires_route_backfill?(migrations)
         migrations.any? do |name|
           ROUTE_BACKFILL_MIGRATIONS.any? { |fragment| name.include?(fragment) }

data/lib/rails_pulse/configuration.rb

@@ -21,6 +21,7 @@ module RailsPulse
                   :authentication_enabled,
                   :authentication_method,
                   :authorize,
+                  :standalone_authentication_method,
                   :authentication_redirect_path,
                   :tags,
                   :job_tracking_mode,
@@ -32,6 +33,7 @@ module RailsPulse
                   :service_level_objectives,
                   :query_service_level_objectives,
                   :warn_on_stale_summaries,
+                  :schema_check_enabled,
                   :baseline_window,
                   :comparison_window,
                   :hourly_summary_retention
@@ -104,6 +106,10 @@ module RailsPulse
       # Fail-closed predicate: ->(controller) { true to allow }. Anything
       # falsy is a 403. Runs after authentication_method, if both are set.
       @authorize = nil
+      # Used instead of authentication_method / authorize by the standalone
+      # dashboard server, where host session helpers are unavailable. nil
+      # means HTTP Basic against RAILS_PULSE_USERNAME / RAILS_PULSE_PASSWORD.
+      @standalone_authentication_method = nil
       @authentication_redirect_path = "/"
       @tags = [ "ignored", "critical", "experimental" ]
       @job_tracking_mode = :universal
@@ -130,6 +136,10 @@ module RailsPulse
       # Show a warning banner when summaries haven't been generated recently
       @warn_on_stale_summaries = true
 
+      # Pause tracking and gate the dashboard when the tables are behind this
+      # gem version (see RailsPulse::SchemaCheck). Off only as an escape hatch.
+      @schema_check_enabled = true
+
       # Historical comparison. The baseline is the traffic-weighted metric across
       # `baseline_window` of day summaries; `comparison_window` is the recent
       # slice measured against it.
@@ -218,6 +228,7 @@ module RailsPulse
       validate_service_level_objectives_settings!
       validate_query_service_level_objectives_settings!
       validate_comparison_settings!
+      validate_schema_check_settings!
     end
 
     private
@@ -326,6 +337,16 @@ module RailsPulse
       if @authorize && !@authorize.respond_to?(:call)
         raise ArgumentError, "authorize must respond to #call (a proc or lambda receiving the controller and returning true to allow), got #{@authorize.class}"
       end
+
+      if @standalone_authentication_method && !@standalone_authentication_method.is_a?(Proc)
+        raise ArgumentError, "standalone_authentication_method must be a Proc or nil, got #{@standalone_authentication_method.class}"
+      end
+    end
+
+    def validate_schema_check_settings!
+      return if [ true, false ].include?(@schema_check_enabled)
+
+      raise ArgumentError, "schema_check_enabled must be true or false, got #{@schema_check_enabled.inspect}"
     end
 
     def validate_tags!

data/lib/rails_pulse/engine.rb

@@ -66,6 +66,7 @@ module RailsPulse
   # Task runners
   module Tasks
     autoload :CleanupTaskRunner, File.expand_path("tasks/cleanup_task_runner", __dir__)
+    autoload :StatusReporter, File.expand_path("tasks/status_reporter", __dir__)
   end
 
   class Engine < ::Rails::Engine
@@ -149,10 +150,12 @@ module RailsPulse
 
     private
 
+    # Lowercase keys: Rack 3 requires them, and Rack::Lint (which rackup
+    # inserts in its development environment) rejects mixed case with a 500.
     def self.asset_headers
       {
-        "Cache-Control" => "public, max-age=31536000, immutable",
-        "Vary" => "Accept-Encoding"
+        "cache-control" => "public, max-age=31536000, immutable",
+        "vary" => "Accept-Encoding"
       }
     end
   end

data/lib/rails_pulse/installers/config_updater.rb

@@ -27,6 +27,11 @@ module RailsPulse
         new(destination: destination, source: source, output: output).update
       end
 
+      # What `update` would add, without writing anything.
+      def self.missing(destination:, source: nil)
+        new(destination: destination, source: source).missing
+      end
+
       def self.template_path
         File.expand_path("../../../../lib/generators/rails_pulse/templates/rails_pulse.rb", __FILE__)
       end
@@ -37,6 +42,18 @@ module RailsPulse
         @output = output
       end
 
+      # { keys: [setting keys absent from the host file], hash_keys: [names of
+      # entries absent from a hash the host does set] }. Empty arrays when the
+      # host mentions everything; both empty when the file does not exist.
+      def missing
+        return { keys: [], hash_keys: [] } unless File.exist?(destination)
+
+        host = File.read(destination)
+        missing_keys = template_settings.map { |setting| setting[:key] } - mentioned_keys(host)
+        hash_keys = missing_hash_entries(host, missing_keys)
+        { keys: missing_keys, hash_keys: hash_keys.map { |entry| entry[:name] } }
+      end
+
       def update
         return { status: :missing, keys: [], hash_keys: [] } unless File.exist?(destination)
 

data/lib/rails_pulse/job_run_collector.rb

@@ -90,7 +90,7 @@ module RailsPulse
 
       def tracking_enabled?
         config = RailsPulse.configuration
-        config.enabled && config.track_jobs
+        config.enabled && config.track_jobs && RailsPulse::SchemaCheck.tracking_allowed?
       end
 
       def ignore_job?(job)

data/lib/rails_pulse/middleware/asset_server.rb

@@ -62,14 +62,15 @@ module RailsPulse
         path.to_s.sub(VERSIONED_ASSET_PATH, '\1')
       end
 
+      # Lowercase keys: Rack 3 requires them, and Rack::Lint rejects mixed case.
       def cache_headers
         if defined?(Rails) && Rails.env.development?
-          { "Cache-Control" => "no-cache, no-store, must-revalidate", "Pragma" => "no-cache" }
+          { "cache-control" => "no-cache, no-store, must-revalidate", "pragma" => "no-cache" }
         else
           {
-            "Cache-Control" => "public, max-age=31536000, immutable",
-            "Vary" => "Accept-Encoding",
-            "Expires" => (Time.now + 1.year).httpdate
+            "cache-control" => "public, max-age=31536000, immutable",
+            "vary" => "Accept-Encoding",
+            "expires" => (Time.now + 1.year).httpdate
           }
         end
       end

data/lib/rails_pulse/schema_check.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "generators/rails_pulse/base_methods"
+
+module RailsPulse
+  # Answers one question about the live Rails Pulse tables: can this gem
+  # version safely read and write them?
+  #
+  # The answer is "no" exactly when new gem code is running against tables
+  # that predate it — a deploy that shipped the gem before `db:migrate`, or a
+  # rolling restart that left old and new processes side by side. Without
+  # this guard that state surfaces as a "Failed to persist tracking data"
+  # log line on every request and a 500 on every dashboard page. With it,
+  # tracking pauses after one warning and the dashboard explains what to run.
+  #
+  # The comparison is deliberately explicit and small: every Rails Pulse
+  # table must exist, and SENTINEL_COLUMNS lists the columns that incremental
+  # migrations have added since a table was first created (see
+  # db/rails_pulse_migrate). Presence only, never types. It runs at most once
+  # per process, and any database error is treated as "not outdated" so a
+  # booting app without a database (assets precompile, db:create) is never
+  # blocked. `config.schema_check_enabled = false` turns it off entirely.
+  module SchemaCheck
+    UPGRADE_INSTRUCTIONS = [
+      "rails generate rails_pulse:upgrade",
+      "rails db:migrate                  # separate Pulse database: rails db:migrate:rails_pulse",
+      "rails rails_pulse:migrate_routes  # once, after the route identity migrations"
+    ].freeze
+
+    # Every table the gem expects. Kept in one place already; reused here so a
+    # new table is covered as soon as it is added there.
+    REQUIRED_TABLES = RailsPulse::Generators::BaseMethods::RAILS_PULSE_TABLES
+
+    # Columns added by incremental migrations after the table itself was
+    # introduced. When db/rails_pulse_migrate gains a migration that adds a
+    # column the models depend on, add it here too (CLAUDE.md lists the other
+    # places); test/lib/rails_pulse/schema_check_test.rb checks every entry
+    # against db/rails_pulse_schema.rb so the list cannot drift from it.
+    SENTINEL_COLUMNS = {
+      "rails_pulse_routes" => %w[controller_action http_methods],
+      "rails_pulse_requests" => %w[method response_size_bytes],
+      "rails_pulse_operations" => %w[actual_sql row_count repeated_query_group],
+      "rails_pulse_jobs" => %w[p95_duration p99_duration],
+      "rails_pulse_exception_groups" => %w[location]
+    }.freeze
+
+    class << self
+      def enabled?
+        RailsPulse.configuration.schema_check_enabled
+      end
+
+      def current?
+        missing.empty?
+      end
+
+      # { "rails_pulse_routes" => ["http_methods", "controller_action"] }
+      # for a table missing columns, { "rails_pulse_exception_groups" => [:table] }
+      # for a table that does not exist at all. Empty when everything is present
+      # or the check is disabled.
+      def missing
+        return {} unless enabled?
+
+        cached = @missing
+        return cached if cached
+
+        result = compute_missing
+        # Only remember a completed comparison; a database error is retried
+        # on the next call rather than cached as either answer.
+        @missing = result unless result.nil?
+        result || {}
+      end
+
+      # Tracking entry points call this instead of writing straight away. The
+      # first refusal logs the upgrade instructions; later ones are silent.
+      def tracking_allowed?
+        return true if current?
+
+        warn_once!
+        false
+      end
+
+      def warn_once!
+        return if @warned
+
+        @warned = true
+        RailsPulse.logger.error(warning_message)
+      end
+
+      def warning_message
+        lines = missing.map do |table, columns|
+          columns == [ :table ] ? "  #{table} (table missing)" : "  #{table}: #{columns.join(', ')}"
+        end
+        <<~MESSAGE.chomp
+          Rails Pulse #{RailsPulse::VERSION} is running against a database that has not been migrated for it.
+          Tracking is paused and the dashboard is unavailable until the schema is upgraded. Missing:
+          #{lines.join("\n")}
+          To upgrade:
+          #{UPGRADE_INSTRUCTIONS.map { |line| "  #{line}" }.join("\n")}
+          (Set config.schema_check_enabled = false to disable this check.)
+        MESSAGE
+      end
+
+      # The table => [column] map the check enforces.
+      def expected_schema
+        REQUIRED_TABLES.each_with_object({}) do |table, expected|
+          expected[table] = SENTINEL_COLUMNS.fetch(table, [])
+        end
+      end
+
+      def reset!
+        @missing = nil
+        @warned = nil
+      end
+
+      private
+
+      def compute_missing
+        connection = RailsPulse::ApplicationRecord.connection
+        expected_schema.each_with_object({}) do |(table, columns), missing|
+          unless connection.table_exists?(table)
+            missing[table] = [ :table ]
+            next
+          end
+
+          absent = columns - connection.columns(table).map(&:name)
+          missing[table] = absent if absent.any?
+        end
+      rescue StandardError
+        # ActiveRecord::ActiveRecordError plus whatever the adapter raises
+        # (PG::Error, SQLite3::Exception, Mysql2::Error) when the database is
+        # not there yet. Unknown, not outdated.
+        nil
+      end
+    end
+  end
+end

data/lib/rails_pulse/standalone.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RailsPulse
+  # Process-wide "am I the standalone dashboard?" flag, set by
+  # lib/rails_pulse_server.ru once the host environment is loaded.
+  #
+  # Two things differ when the engine is served by its own process instead of
+  # mounted inside the host app, and both are decided here rather than left to
+  # the host to work around:
+  #
+  # * URL generation. Engine path helpers ask the host's route set where the
+  #   engine is mounted and prefix that path — `/rails_pulse/routes` — because
+  #   that is what a link inside the host app needs. (`mount` extends the
+  #   engine route set with a `find_script_name` that does this.) The
+  #   standalone server serves the engine at `/`, so that prefix 404s against
+  #   itself. `standalone!` prepends an override that answers "" while the
+  #   flag is set, so every helper generates root-relative paths in this
+  #   process only. Passing `script_name: ""` or setting it in
+  #   `default_url_options` is not enough: Rails treats the empty value as
+  #   unset and falls through to the mount prefix.
+  #
+  # * Authentication. See ApplicationController#authenticate_rails_pulse_user!
+  #   — host session hooks cannot run here, so the dashboard falls back to
+  #   `config.standalone_authentication_method`, then HTTP Basic.
+  module Standalone
+    module RootScriptName
+      def find_script_name(options)
+        RailsPulse.standalone? ? "" : super
+      end
+    end
+
+    def standalone?
+      @standalone == true
+    end
+
+    def standalone!
+      @standalone = true
+      routes = Engine.routes
+      routes.singleton_class.prepend(RootScriptName) unless routes.singleton_class.ancestors.include?(RootScriptName)
+    end
+
+    # Undo standalone! — for tests that load the rackup file in-process. The
+    # prepended override stays but defers to the mount prefix again.
+    def exit_standalone!
+      @standalone = false
+    end
+  end
+
+  extend Standalone
+end

data/lib/rails_pulse/tasks/status_reporter.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module RailsPulse
+  module Tasks
+    # `rails rails_pulse:status` — where does this install stand?
+    #
+    # Answers, from the shell and without opening the dashboard, the questions
+    # an upgrade tends to leave hanging: is the schema current for this gem,
+    # are there migration files that have not been run, has the route backfill
+    # been done, does the initializer mention the settings this version added.
+    # Anything that needs action is repeated in a closing "Action needed"
+    # list, and `report` returns false in that case so release scripts can
+    # stop on it.
+    class StatusReporter
+      attr_reader :output, :config
+
+      def self.report(output: $stdout)
+        new(output: output).report
+      end
+
+      def initialize(output: $stdout)
+        @output = output
+        @config = RailsPulse.configuration
+        @actions = []
+      end
+
+      # Returns true when nothing needs attention.
+      def report
+        output.puts "Rails Pulse #{RailsPulse::VERSION}"
+        output.puts
+
+        print_database
+        print_schema
+        print_migrations
+        print_route_backfill
+        print_initializer
+        print_tracking
+        print_summaries
+        print_actions
+
+        @actions.empty?
+      end
+
+      private
+
+      def action(text)
+        @actions << text
+      end
+
+      # -- sections -----------------------------------------------------------
+
+      def print_database
+        connection = RailsPulse::ApplicationRecord.connection
+        name = RailsPulse::ApplicationRecord.connection_db_config.name
+        separate = config.connects_to.present?
+        output.puts "Database:   #{connection.adapter_name} (#{name}#{separate ? ", separate Pulse database" : ""})"
+      rescue StandardError => e
+        output.puts "Database:   unavailable (#{e.class}: #{e.message})"
+        action "Database connection failed; nothing below could be checked."
+      end
+
+      def print_schema
+        RailsPulse::SchemaCheck.reset!
+        missing = RailsPulse::SchemaCheck.missing
+
+        if missing.empty?
+          output.puts "Schema:     up to date for #{RailsPulse::VERSION}"
+          return
+        end
+
+        output.puts "Schema:     BEHIND this gem version"
+        missing.each do |table, columns|
+          output.puts(columns == [ :table ] ? "              #{table}: table missing" : "              #{table}: missing #{columns.join(', ')}")
+        end
+        action "Schema is behind the gem. Run: #{upgrade_commands.join(' && ')}"
+      end
+
+      def print_migrations
+        not_copied = gem_migrations_not_in_host
+        pending = pending_migrations
+
+        if not_copied.empty? && pending.empty?
+          output.puts "Migrations: none pending"
+          return
+        end
+
+        if not_copied.any?
+          output.puts "Migrations: #{not_copied.size} gem migration(s) not yet copied into this app:"
+          not_copied.each { |name| output.puts "              #{name}" }
+          action "Copy this version's migrations: rails generate rails_pulse:upgrade"
+        end
+
+        if pending.any?
+          output.puts "Migrations: #{pending.size} migration file(s) present but not run:"
+          pending.each { |name| output.puts "              #{name}" }
+          action "Run pending migrations: #{migrate_command}"
+        end
+      end
+
+      def print_route_backfill
+        unless RailsPulse::SchemaCheck.current?
+          output.puts "Routes:     (skipped — schema is behind)"
+          return
+        end
+
+        backfill = RailsPulse::Route.needs_action_backfill?
+        index = RailsPulse::RouteIndexes.exists?(RailsPulse::ApplicationRecord.connection)
+
+        if !backfill && index
+          output.puts "Routes:     actions backfilled, unrecognised-path index present"
+          return
+        end
+
+        output.puts "Routes:     #{backfill ? 'actions NOT backfilled' : 'actions backfilled'}, " \
+                    "unrecognised-path index #{index ? 'present' : 'MISSING'}"
+        action "Backfill route actions and create the unrecognised-path index: rails rails_pulse:migrate_routes"
+      rescue StandardError => e
+        output.puts "Routes:     could not check (#{e.class}: #{e.message})"
+      end
+
+      def print_initializer
+        path = Rails.root.join("config", "initializers", "rails_pulse.rb")
+        unless path.exist?
+          output.puts "Initializer: config/initializers/rails_pulse.rb not found"
+          action "Create the initializer: rails generate rails_pulse:install"
+          return
+        end
+
+        missing = RailsPulse::Installers::ConfigUpdater.missing(destination: path.to_s)
+        keys = missing[:keys] + missing[:hash_keys]
+        if keys.empty?
+          output.puts "Initializer: mentions every setting this version knows"
+          return
+        end
+
+        output.puts "Initializer: #{keys.size} setting(s) from this version not mentioned: #{keys.join(', ')}"
+        action "Append the new settings to the initializer: rails generate rails_pulse:upgrade (review with git diff)"
+      end
+
+      def print_tracking
+        auth = if !config.authentication_enabled
+          "disabled"
+        elsif config.authentication_method || config.authorize
+          "custom hook"
+        else
+          "HTTP Basic (RAILS_PULSE_PASSWORD #{ENV["RAILS_PULSE_PASSWORD"].to_s.empty? ? 'NOT set' : 'set'})"
+        end
+
+        output.puts "Tracking:   enabled=#{config.enabled} requests=#{config.enabled} jobs=#{config.track_jobs} " \
+                    "exceptions=#{config.track_exceptions} async=#{config.async}"
+        output.puts "Dashboard:  mount_dashboard=#{config.mount_dashboard} authentication=#{auth}"
+      end
+
+      def print_summaries
+        last = RailsPulse::Summary.maximum(:updated_at)
+        if last.nil?
+          output.puts "Summaries:  none generated yet (schedule RailsPulse::SummaryJob hourly; backfill with rails rails_pulse:backfill_summaries)"
+        elsif last < 2.hours.ago
+          output.puts "Summaries:  last generated #{time_ago(last)} — stale (is RailsPulse::SummaryJob scheduled?)"
+        else
+          output.puts "Summaries:  last generated #{time_ago(last)}"
+        end
+      rescue StandardError => e
+        output.puts "Summaries:  could not check (#{e.class}: #{e.message})"
+      end
+
+      def print_actions
+        output.puts
+        if @actions.empty?
+          output.puts "OK — nothing to do."
+        else
+          output.puts "Action needed:"
+          @actions.each { |text| output.puts "  - #{text}" }
+        end
+      end
+
+      # -- helpers ------------------------------------------------------------
+
+      def gem_migrations_not_in_host
+        gem_dir = RailsPulse::Engine.root.join("db", "rails_pulse_migrate")
+        return [] unless gem_dir.directory?
+
+        host = %w[db/migrate db/rails_pulse_migrate].flat_map do |dir|
+          Dir.glob(Rails.root.join(dir, "*.rb").to_s).map { |f| File.basename(f) }
+        end
+        Dir.glob(gem_dir.join("*.rb").to_s).map { |f| File.basename(f) }.sort - host
+      end
+
+      # Migration files on disk whose version is not recorded on the Pulse
+      # connection. Names only; the versions are in the filenames.
+      def pending_migrations
+        context = RailsPulse::ApplicationRecord.connection_pool.migration_context
+        applied = context.get_all_versions
+        context.migrations.reject { |m| applied.include?(m.version) }.map { |m| File.basename(m.filename) }
+      rescue StandardError
+        []
+      end
+
+      def upgrade_commands
+        [ "rails generate rails_pulse:upgrade", migrate_command, "rails rails_pulse:migrate_routes" ]
+      end
+
+      def migrate_command
+        config.connects_to.present? ? "rails db:migrate:rails_pulse" : "rails db:migrate"
+      end
+
+      def time_ago(time)
+        seconds = (Time.current - time).to_i
+        return "#{seconds}s ago" if seconds < 60
+        return "#{seconds / 60}m ago" if seconds < 3600
+        return "#{seconds / 3600}h ago" if seconds < 86_400
+
+        "#{seconds / 86_400}d ago"
+      end
+    end
+  end
+end

data/lib/rails_pulse/tracker.rb

@@ -10,6 +10,7 @@ module RailsPulse
     class << self
       def track_request(data)
         return if RequestStore.store[:skip_recording_rails_pulse_activity]
+        return unless RailsPulse::SchemaCheck.tracking_allowed?
 
         if RailsPulse.configuration.async && !connection_shared_across_threads?
           Thread.new do