railwatch 0.8.4 → 0.8.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f52b89a567e0ac0a05281db9b77499961ee7abf9cbfbf663070600d8885818a3
-  data.tar.gz: 05cdb2e7d19bf73edb2dd80550b1a59bf39c83ad24b951c7f7d43b3ddee9a850
+  metadata.gz: c483283faabf8cf2552cedbd8568e6d06f815c8e5bdf4f2cdffe1909a82fa80b
+  data.tar.gz: 2f56eb2aed77f09e55d869117c3f9bf1d6140f00fa93ebd2a5c2c89e4da62b7b
 SHA512:
-  metadata.gz: d3d4c4f9698de7d6f522d4c171962e959efccd4435ff07e036505ced415aaa43e4b134df949f18c61952c4b22738d7074f49afcc1209cf1088fe41ea6cae564b
-  data.tar.gz: 8f4c96092fc3a62f3538667c4d4f2e40de420e9f2ccacf7305b0b4b4fd99ca9b098cb830cced5b9def8a618d3d1e16e24e478d4461f2599e0047121b79e2df2e
+  metadata.gz: a80ac73b1c0e36d6fb681da86848ac37f3bde8d6b867fbd0a5134087da9c134344595fd1407f49f72f00d8573d2304b9944b2e667ae44fa63cd9c2337527da5a
+  data.tar.gz: a3e7028f181c255b69d0831f9e9a56c163b48bdacccca8464b3d05f6233976a2d412d06d11f3ad5320430186e2c067830e96ee048f415281933da5a6bc41a22f

data/CHANGELOG.md

@@ -6,6 +6,39 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 0.8.6 (2026-10-06)
+
+- An install upgrading from 0.5.0 or older can migrate again. 0.5.1
+  renumbered the export queue migration (20260919000000 to
+  20260919000100), so a telemetry database that had already run it under
+  the old number saw it as pending, and its plain `create_table` raised
+  "table export_destinations already exists" -- in `db:prepare`, which a
+  deploy runs before the app boots. Every statement in it is now
+  `if_not_exists`, so it builds the queue on a new database, completes it
+  on one that ran the old number (keeping anything already queued), and
+  stays a no-op where the new number has run. Rolling it back on a
+  database that came through the old number leaves the queue in place,
+  since the old version still owns it; anywhere else it is reversed as
+  before.
+- The 0.8.0, 0.8.1 and 0.8.5 index migrations accept an index that is
+  already there. Each one reads a whole table, and on a telemetry file
+  much larger than memory that is not seconds: about 40 s per table on
+  rebulk-system's 14.8 GB file, five builds in all, against a deploy
+  that health-checks within 90 s of the container starting -- and runs
+  `db:prepare` inside that window. An operator can now build them ahead
+  of the deploy, while the old release still serves, with the
+  migrations' own `CREATE INDEX` statements; `db:prepare` then records
+  them and moves on.
+
+## 0.8.5 (2026-09-25)
+
+- A new migration adds a partial covering index for the per-tenant sums
+  on the Tenants page and in MCP's `list_tenants`. Over 30 days of
+  rebulk-system's 358,000 tagged requests they took 8.1 s, reading every
+  row from the table; they now take 131 ms. It holds only tagged rows,
+  so an app without tenants gets an empty index. It took 1.6 s to build
+  on a 16 GB file.
+
 ## 0.8.4 (2026-09-23)
 
 - A `class:` filter for a job class with many attempts in the window

data/app/models/railwatch/telemetry/tenant.rb

@@ -120,8 +120,18 @@ module Railwatch
 
       # -- Aggregation steps -----------------------------------------------------
 
+      # The per-tenant sums read through idx_executions_tenant_summary, which
+      # holds every column they need for tagged rows only. SQLite prefers the
+      # narrower (app_tenant, occurred_at) index on its own estimate and then
+      # fetches every row from the table (8 s against 131 ms over 30 days).
+      def self.summary_scope(kind)
+        scope = Telemetry::Execution
+        scope = scope.from("#{scope.quoted_table_name} INDEXED BY idx_executions_tenant_summary") if TelemetryRecord.sqlite?
+        scope.where(kind: kind).where.not(app_tenant: nil)
+      end
+
       def self.absorb_requests(rows, from, to, q)
-        filtered(Telemetry::Execution.requests.between(from, to), q).group(:app_tenant)
+        filtered(summary_scope("request").between(from, to), q).group(:app_tenant)
           .pluck(:app_tenant, COUNT_SQL, ERRORS_SQL, Arel.sql("AVG(duration)"), Arel.sql("MAX(duration)"), USERS_SQL)
           .each do |tenant, count, errors, avg, max, users|
             rows[tenant].merge!(requests: count, errors: errors, avg: ms(avg), max: ms(max), users: users)
@@ -129,7 +139,7 @@ module Railwatch
       end
 
       def self.absorb_jobs(rows, from, to, q)
-        filtered(Telemetry::Execution.jobs.between(from, to), q).group(:app_tenant)
+        filtered(summary_scope("job_attempt").between(from, to), q).group(:app_tenant)
           .pluck(:app_tenant, COUNT_SQL, FAILED_SQL)
           .each { |tenant, count, failed| rows[tenant].merge!(jobs: count, failed_jobs: failed) }
       end
@@ -139,7 +149,7 @@ module Railwatch
       end
 
       def self.absorb_last_seen(rows, from, to, q)
-        filtered(Telemetry::Execution.between(from, to), q).group(:app_tenant).maximum(:occurred_at)
+        filtered(summary_scope(Telemetry::Execution::KINDS).between(from, to), q).group(:app_tenant).maximum(:occurred_at)
           .each { |tenant, at| rows[tenant][:last_seen_at] = at }
       end
 

data/db/railwatch_telemetry_migrate/20260919000100_create_export_queue.rb

@@ -13,96 +13,134 @@
 # is stored.
 #
 # Nothing here is written unless export is explicitly enabled.
+#
+# Every statement is if_not_exists, because this migration has run before
+# under another number. Through 0.5.0 it was 20260919000000; 0.5.1 moved it
+# here so it could not collide with a host's own telemetry migration at that
+# number (Railwatch Cloud has one). An install upgrading from 0.5.0 or older
+# therefore already holds every table, index and column below, recorded
+# under the old version, and sees this one as pending: a plain create_table
+# raised "table export_destinations already exists" in db:prepare, which a
+# deploy runs before the app boots. The old run is detected by what it
+# built, not by its version, because on a host like Railwatch Cloud the old
+# number belongs to a different migration.
+#
+# Rolling back has the mirror problem: on a database that came through the
+# old number, these tables and columns -- and anything queued in them -- are
+# the old version's, which stays recorded as applied. So down leaves them
+# alone there, and reverses the migration everywhere else.
 class CreateExportQueue < ActiveRecord::Migration[8.1]
-  def change
-    # One row per destination this database has ever been pointed at.
-    create_table :export_destinations do |t|
-      t.string :url, null: false
-      t.string :url_sha256, limit: 64, null: false
-      # Permanent for this database's lineage: it is how the receiver tells
-      # our deliveries from another installation's.
-      t.string :producer_id, limit: 36, null: false
-      # A fingerprint, never the token. If the token changes, queued bytes
-      # must not follow it to whatever tenant the new one belongs to.
-      t.string :credential_sha256, limit: 64, null: false
-
-      t.string :state, limit: 16, null: false, default: "ready"
-      t.datetime :retry_at, precision: 6
-      t.string :reason, limit: 64
-
-      t.string :lease_owner, limit: 36
-      t.bigint :lease_generation, null: false, default: 0
-      t.datetime :lease_expires_at, precision: 6
-
-      # Live totals, maintained in the same transaction as the rows they
-      # describe, so admission can be decided without counting the table.
-      t.bigint :queued_bytes, null: false, default: 0
-      t.bigint :queued_deliveries, null: false, default: 0
-      # Lifetime accounting: acked, rejected, expired, discarded, shed.
-      t.json :counters, null: false, default: {}
-
-      t.timestamps
+  OLD_VERSION = 20260919000000
+
+  def up
+    build_queue
+  end
+
+  def down
+    if built_under_old_number?
+      say("left in place: #{OLD_VERSION} built this queue under its pre-0.5.1 number and is still recorded as applied")
+    else
+      revert { build_queue }
     end
+  end
 
-    add_index :export_destinations, :url_sha256, unique: true
-    add_index :export_destinations, :producer_id, unique: true
-
-    create_table :export_deliveries do |t|
-      t.references :export_destination, null: false, foreign_key: true
-      # A UUIDv7: its embedded time is how the receiver ages it out, so a
-      # delivery cannot be made young again by relabelling it.
-      t.string :delivery_id, limit: 36, null: false
-      # What this delivery is a delivery OF. One per source batch today; a
-      # future policy that selects across batches supplies its own key.
-      t.string :selection_key, limit: 160, null: false
-
-      t.binary :body
-      t.string :body_sha256, limit: 64, null: false
-      t.string :metadata_sha256, limit: 64, null: false
-      t.bigint :body_bytes, null: false
-      t.bigint :ndjson_bytes, null: false
-      t.integer :record_count, null: false
-      # Everything about the delivery that is not its body: version, drop
-      # counts, backpressure. Digested into metadata_sha256 so the same id
-      # arriving with different counts is a conflict, not an update.
-      t.json :wire_metadata, null: false, default: {}
-
-      t.string :state, limit: 8, null: false, default: "pending"
-      # Set only when done: acked, rejected, expired, discarded.
-      t.string :disposition, limit: 16
-      t.datetime :enqueued_at, null: false, precision: 6
-      t.datetime :expires_at, null: false, precision: 6
-      t.datetime :next_attempt_at, null: false, precision: 6
-      t.bigint :attempts, null: false, default: 0
-
-      t.string :claim_token, limit: 36
-      t.bigint :claim_generation
-      t.datetime :claim_expires_at, precision: 6
-
-      t.integer :last_status
-      t.string :last_reason, limit: 64
-      t.json :ack
-      t.datetime :finished_at, precision: 6
-
-      t.timestamps
+  private
+    # The old version is recorded, and no migration file this database knows
+    # of claims it: only the gem's own pre-0.5.1 CreateExportQueue did.
+    def built_under_old_number?
+      context = connection.pool.migration_context
+      context.get_all_versions.include?(OLD_VERSION) && context.migrations.none? { |m| m.version == OLD_VERSION }
     end
 
-    add_index :export_deliveries, %i[export_destination_id delivery_id], unique: true,
-      name: "index_export_deliveries_on_destination_and_delivery"
-    # One delivery per selection: a batch replayed into the same transaction
-    # cannot enqueue itself twice.
-    add_index :export_deliveries, %i[export_destination_id selection_key], unique: true,
-      name: "index_export_deliveries_on_destination_and_selection"
-    add_index :export_deliveries, %i[export_destination_id id], where: "state <> 'done'",
-      name: "index_export_deliveries_live"
-    add_index :export_deliveries, :expires_at, where: "body IS NOT NULL",
-      name: "index_export_deliveries_expiring"
-    add_index :export_deliveries, :finished_at, where: "state = 'done'",
-      name: "index_export_deliveries_finished"
-
-    # Why a batch did or did not enqueue anything. Null on every row an
-    # install without export ever writes.
-    add_column :ingest_batches, :export_disposition, :string, limit: 24
-    add_column :ingest_batches, :export_record_count, :bigint
-  end
+    def build_queue
+      # One row per destination this database has ever been pointed at.
+      create_table :export_destinations, if_not_exists: true do |t|
+        t.string :url, null: false
+        t.string :url_sha256, limit: 64, null: false
+        # Permanent for this database's lineage: it is how the receiver tells
+        # our deliveries from another installation's.
+        t.string :producer_id, limit: 36, null: false
+        # A fingerprint, never the token. If the token changes, queued bytes
+        # must not follow it to whatever tenant the new one belongs to.
+        t.string :credential_sha256, limit: 64, null: false
+
+        t.string :state, limit: 16, null: false, default: "ready"
+        t.datetime :retry_at, precision: 6
+        t.string :reason, limit: 64
+
+        t.string :lease_owner, limit: 36
+        t.bigint :lease_generation, null: false, default: 0
+        t.datetime :lease_expires_at, precision: 6
+
+        # Live totals, maintained in the same transaction as the rows they
+        # describe, so admission can be decided without counting the table.
+        t.bigint :queued_bytes, null: false, default: 0
+        t.bigint :queued_deliveries, null: false, default: 0
+        # Lifetime accounting: acked, rejected, expired, discarded, shed.
+        t.json :counters, null: false, default: {}
+
+        t.timestamps
+      end
+
+      add_index :export_destinations, :url_sha256, unique: true, if_not_exists: true
+      add_index :export_destinations, :producer_id, unique: true, if_not_exists: true
+
+      create_table :export_deliveries, if_not_exists: true do |t|
+        t.references :export_destination, null: false, foreign_key: true
+        # A UUIDv7: its embedded time is how the receiver ages it out, so a
+        # delivery cannot be made young again by relabelling it.
+        t.string :delivery_id, limit: 36, null: false
+        # What this delivery is a delivery OF. One per source batch today; a
+        # future policy that selects across batches supplies its own key.
+        t.string :selection_key, limit: 160, null: false
+
+        t.binary :body
+        t.string :body_sha256, limit: 64, null: false
+        t.string :metadata_sha256, limit: 64, null: false
+        t.bigint :body_bytes, null: false
+        t.bigint :ndjson_bytes, null: false
+        t.integer :record_count, null: false
+        # Everything about the delivery that is not its body: version, drop
+        # counts, backpressure. Digested into metadata_sha256 so the same id
+        # arriving with different counts is a conflict, not an update.
+        t.json :wire_metadata, null: false, default: {}
+
+        t.string :state, limit: 8, null: false, default: "pending"
+        # Set only when done: acked, rejected, expired, discarded.
+        t.string :disposition, limit: 16
+        t.datetime :enqueued_at, null: false, precision: 6
+        t.datetime :expires_at, null: false, precision: 6
+        t.datetime :next_attempt_at, null: false, precision: 6
+        t.bigint :attempts, null: false, default: 0
+
+        t.string :claim_token, limit: 36
+        t.bigint :claim_generation
+        t.datetime :claim_expires_at, precision: 6
+
+        t.integer :last_status
+        t.string :last_reason, limit: 64
+        t.json :ack
+        t.datetime :finished_at, precision: 6
+
+        t.timestamps
+      end
+
+      add_index :export_deliveries, %i[export_destination_id delivery_id], unique: true,
+        name: "index_export_deliveries_on_destination_and_delivery", if_not_exists: true
+      # One delivery per selection: a batch replayed into the same transaction
+      # cannot enqueue itself twice.
+      add_index :export_deliveries, %i[export_destination_id selection_key], unique: true,
+        name: "index_export_deliveries_on_destination_and_selection", if_not_exists: true
+      add_index :export_deliveries, %i[export_destination_id id], where: "state <> 'done'",
+        name: "index_export_deliveries_live", if_not_exists: true
+      add_index :export_deliveries, :expires_at, where: "body IS NOT NULL",
+        name: "index_export_deliveries_expiring", if_not_exists: true
+      add_index :export_deliveries, :finished_at, where: "state = 'done'",
+        name: "index_export_deliveries_finished", if_not_exists: true
+
+      # Why a batch did or did not enqueue anything. Null on every row an
+      # install without export ever writes.
+      add_column :ingest_batches, :export_disposition, :string, limit: 24, if_not_exists: true
+      add_column :ingest_batches, :export_record_count, :bigint, if_not_exists: true
+    end
 end

data/db/railwatch_telemetry_migrate/20260922000000_add_covering_indexes_for_dashboard_aggregates.rb

@@ -25,10 +25,10 @@
 # Execution.named_like seek them instead of reading the window.
 class AddCoveringIndexesForDashboardAggregates < ActiveRecord::Migration[8.1]
   def change
-    add_index :executions, [ :kind, :occurred_at, :queue, :outcome, :queue_latency ], name: "idx_executions_queue_stats"
+    add_index :executions, [ :kind, :occurred_at, :queue, :outcome, :queue_latency ], name: "idx_executions_queue_stats", if_not_exists: true
     add_index :health_samples, [ :sampled_at, :threads_max, :threads_busy, :backlog, :queue_depth, :queue_latency ],
-              name: "idx_health_samples_series"
-    add_index :broadcasts, :occurred_at
-    add_index :executions, [ :kind, :occurred_at ], name: "idx_executions_with_preview", where: "exception_preview IS NOT NULL"
+              name: "idx_health_samples_series", if_not_exists: true
+    add_index :broadcasts, :occurred_at, if_not_exists: true
+    add_index :executions, [ :kind, :occurred_at ], name: "idx_executions_with_preview", where: "exception_preview IS NOT NULL", if_not_exists: true
   end
 end

data/db/railwatch_telemetry_migrate/20260923000000_add_people_index.rb

@@ -10,6 +10,6 @@
 class AddPeopleIndex < ActiveRecord::Migration[8.1]
   def change
     add_index :executions, [ :user_ref, :kind, :occurred_at, :status ], name: "idx_executions_people",
-              where: "user_ref IS NOT NULL"
+              where: "user_ref IS NOT NULL", if_not_exists: true
   end
 end

data/db/railwatch_telemetry_migrate/20260925000000_add_tenant_summary_index.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# The Tenants page and MCP's list_tenants sum every tenant-tagged request
+# and job in the window per tenant. Through (app_tenant, occurred_at)
+# SQLite finds the rows but fetches each from the table for kind, status,
+# outcome, duration and user_ref: 8.1 s over 30 days on rebulk-system
+# (358,000 tagged requests), and 24 s once in production, which held the
+# web process -- and every ingest request queued behind it -- the whole
+# time. This index carries every column those aggregates read, only for
+# tagged rows: 131 ms for the same query, 41 MB, 1.6 s to build on a copy
+# of that 16 GB file. An untagged app gets an empty index.
+class AddTenantSummaryIndex < ActiveRecord::Migration[8.1]
+  def change
+    add_index :executions, [ :kind, :app_tenant, :occurred_at, :status, :outcome, :duration, :user_ref ],
+              name: "idx_executions_tenant_summary", where: "app_tenant IS NOT NULL", if_not_exists: true
+  end
+end

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "0.8.4"
+  VERSION = "0.8.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch
 version: !ruby/object:Gem::Version
-  version: 0.8.4
+  version: 0.8.6
 platform: ruby
 authors:
 - Cole Robertson
@@ -405,6 +405,7 @@ files:
 - db/railwatch_telemetry_migrate/20260919000100_create_export_queue.rb
 - db/railwatch_telemetry_migrate/20260922000000_add_covering_indexes_for_dashboard_aggregates.rb
 - db/railwatch_telemetry_migrate/20260923000000_add_people_index.rb
+- db/railwatch_telemetry_migrate/20260925000000_add_tenant_summary_index.rb
 - docs/ai-and-mcp.md
 - docs/configuration.md
 - docs/embedded.md