railwatch 0.1.4 → 0.2.0

data/db/railwatch_telemetry_migrate/20260903000006_add_spans_health_vitals_and_fts.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Tier 1-3 telemetry: custom spans, process health samples, request queue
+# time, web vitals on visits, and an FTS5 index over log messages.
+class AddSpansHealthVitalsAndFts < ActiveRecord::Migration[8.1]
+  def up
+    create_table :spans do |t|
+      # The record envelope as it was when this migration shipped; inlined so
+      # the history never calls a model that has since changed.
+      t.datetime :occurred_at, null: false, precision: 6
+      t.string :deploy, limit: 128
+      t.string :server, limit: 255
+      t.string :group_hash, limit: 32
+      t.string :trace_id, limit: 36
+      t.string :execution_source, limit: 20
+      t.string :execution_id, limit: 36
+      t.string :execution_preview, limit: 255
+      t.string :execution_stage, limit: 32
+      t.string :user_ref, limit: 255
+      t.string :app_tenant, limit: 255
+      t.string :name, null: false, limit: 255
+      t.integer :duration, null: false               # microseconds
+      t.json :attributes, null: false, default: {}
+      t.string :status, limit: 20                    # ok, failed
+    end
+    add_index :spans, [ :group_hash, :occurred_at ]
+    add_index :spans, [ :execution_id, :occurred_at ]
+
+    # Periodic Puma / Solid Queue samples, one row per process per interval.
+    create_table :health_samples do |t|
+      t.datetime :sampled_at, null: false, precision: 6
+      t.integer :pid
+      t.string :role, limit: 20
+      t.string :server, limit: 255
+      t.string :deploy, limit: 128
+      t.integer :threads_max
+      t.integer :threads_busy
+      t.integer :backlog
+      t.integer :pool_size
+      t.integer :pool_busy
+      t.integer :pool_waiting
+      t.integer :queue_depth
+      t.integer :queue_latency                        # microseconds, oldest ready job
+      t.bigint :memory
+      t.json :detail, null: false, default: {}
+    end
+    add_index :health_samples, [ :server, :sampled_at ]
+    add_index :health_samples, :sampled_at
+
+    add_column :executions, :queue_time, :integer      # microseconds, from X-Request-Start
+    add_column :executions, :parent_id, :string, limit: 36
+    add_index :executions, :parent_id
+
+    add_column :visits, :lcp, :integer                 # milliseconds
+    add_column :visits, :cls, :float
+    add_column :visits, :inp, :integer                 # milliseconds
+    add_column :visits, :ttfb, :integer                # milliseconds
+
+    add_column :queries, :explain, :text                # captured plan for slow queries (opt-in)
+
+    # External-content FTS5 index over log messages. Kept in sync explicitly
+    # by Ingest::Writer (insert) and PruneTelemetryJob (rebuild) rather than
+    # by triggers: the schema dumper carries create_virtual_table but not
+    # triggers, so a tenant created from telemetry_schema.rb would silently
+    # lose them.
+    execute "CREATE VIRTUAL TABLE logs_fts USING fts5(message, content='logs', content_rowid='id')"
+    execute "INSERT INTO logs_fts(rowid, message) SELECT id, message FROM logs"
+  end
+
+  def down
+    execute "DROP TABLE IF EXISTS logs_fts"
+    remove_column :queries, :explain
+    remove_column :visits, :lcp
+    remove_column :visits, :cls
+    remove_column :visits, :inp
+    remove_column :visits, :ttfb
+    remove_column :executions, :queue_time
+    remove_column :executions, :parent_id
+    drop_table :health_samples
+    drop_table :spans
+  end
+end

data/db/railwatch_telemetry_migrate/20260903000007_rename_span_attributes_to_payload.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# `attributes` is Active Record's own method; a column by that name raises
+# DangerousAttributeError on first access. The wire key stays "attributes",
+# Ingest::Mapper writes it to payload.
+class RenameSpanAttributesToPayload < ActiveRecord::Migration[8.1]
+  def change
+    rename_column :spans, :attributes, :payload
+  end
+end

data/db/railwatch_telemetry_migrate/20260903000008_add_profiles_and_attachments.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Sampled CPU/wall profiles for an execution, attachments (files an app
+# attaches to an execution or exception), and opt-in captured bodies.
+class AddProfilesAndAttachments < ActiveRecord::Migration[8.1]
+  def change
+    create_table :profiles do |t|
+      # The record envelope as it was when this migration shipped; inlined so
+      # the history never calls a model that has since changed.
+      t.datetime :occurred_at, null: false, precision: 6
+      t.string :deploy, limit: 128
+      t.string :server, limit: 255
+      t.string :group_hash, limit: 32
+      t.string :trace_id, limit: 36
+      t.string :execution_source, limit: 20
+      t.string :execution_id, limit: 36
+      t.string :execution_preview, limit: 255
+      t.string :execution_stage, limit: 32
+      t.string :user_ref, limit: 255
+      t.string :app_tenant, limit: 255
+      t.string :profiler, null: false, limit: 16         # vernier, stackprof
+      t.string :mode, limit: 8                           # wall, cpu
+      t.integer :interval                                # microseconds between samples
+      t.integer :duration, null: false                   # microseconds profiled
+      t.integer :samples, null: false                    # total samples collected
+      t.binary :stacks, null: false                      # gzip of collapsed stacks: "frame;frame;frame count\n"
+      t.integer :stacks_bytes                            # uncompressed size
+    end
+    add_index :profiles, [ :execution_id ]
+    add_index :profiles, [ :group_hash, :occurred_at ]
+    add_index :profiles, [ :occurred_at ]
+
+    create_table :attachments do |t|
+      # The record envelope as it was when this migration shipped; inlined so
+      # the history never calls a model that has since changed.
+      t.datetime :occurred_at, null: false, precision: 6
+      t.string :deploy, limit: 128
+      t.string :server, limit: 255
+      t.string :group_hash, limit: 32
+      t.string :trace_id, limit: 36
+      t.string :execution_source, limit: 20
+      t.string :execution_id, limit: 36
+      t.string :execution_preview, limit: 255
+      t.string :execution_stage, limit: 32
+      t.string :user_ref, limit: 255
+      t.string :app_tenant, limit: 255
+      t.string :name, null: false, limit: 255
+      t.string :content_type, limit: 128
+      t.integer :bytes, null: false
+      t.binary :data, null: false                        # gzip
+      t.string :exception_group_hash, limit: 32          # set when attached to an exception
+    end
+    add_index :attachments, [ :execution_id ]
+    add_index :attachments, [ :exception_group_hash, :occurred_at ]
+    add_index :attachments, [ :occurred_at ]
+
+    add_column :outgoing_requests, :response_body, :text  # captured on error only, truncated
+    add_column :executions, :profile_id, :integer         # denormalised: the execution has a profile
+  end
+end

data/db/railwatch_telemetry_migrate/20260903000009_add_truncated_to_attachments.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The gem cuts an attachment off at its size limit and flags the wire
+# record; without this column the UI cannot tell a whole file from a stub.
+class AddTruncatedToAttachments < ActiveRecord::Migration[8.1]
+  def change
+    add_column :attachments, :truncated, :boolean, default: false, null: false
+  end
+end

data/db/railwatch_telemetry_migrate/20260903000010_create_sessions_and_release_health.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Release health. `sessions` are the raw records the gem ships -- one per
+# browser tab and per authenticated/cookied server session, repeated every
+# flush interval, so a session id appears many times and the rollup keeps the
+# worst status it saw. `release_health` is the hourly aggregate per deploy
+# (the release) that the crash-free rates are read from.
+class CreateSessionsAndReleaseHealth < ActiveRecord::Migration[8.1]
+  def change
+    create_table :sessions do |t|
+      # The record envelope as it was when this migration shipped; inlined so
+      # the history never calls a model that has since changed.
+      t.datetime :occurred_at, null: false, precision: 6
+      t.string :deploy, limit: 128
+      t.string :server, limit: 255
+      t.string :group_hash, limit: 32
+      t.string :trace_id, limit: 36
+      t.string :execution_source, limit: 20
+      t.string :execution_id, limit: 36
+      t.string :execution_preview, limit: 255
+      t.string :execution_stage, limit: 32
+      t.string :user_ref, limit: 255
+      t.string :app_tenant, limit: 255
+      t.string :session_id, null: false, limit: 64
+      t.string :source, limit: 16                        # browser, server
+      t.string :status, limit: 16                        # started, ok, errored, crashed
+      t.datetime :started_at, precision: 6
+      t.integer :duration                                # microseconds, null until the session has one
+      t.integer :requests, default: 0
+      t.integer :visits, default: 0
+      t.integer :error_count, default: 0            # `errors` is a reserved Active Record name
+      t.boolean :ended, default: false
+    end
+    add_index :sessions, [ :session_id, :occurred_at ]
+    add_index :sessions, [ :deploy, :occurred_at ]
+    add_index :sessions, [ :occurred_at ]
+
+    create_table :release_health do |t|
+      t.string :deploy, null: false, limit: 128
+      t.datetime :bucket, null: false, precision: 6
+      t.integer :sessions, default: 0
+      t.integer :sessions_errored, default: 0
+      t.integer :sessions_crashed, default: 0
+      t.integer :users, default: 0
+      t.integer :users_crashed, default: 0
+      t.bigint :duration_sum, default: 0
+      t.integer :duration_count, default: 0
+    end
+    add_index :release_health, [ :deploy, :bucket ], unique: true
+  end
+end

data/db/railwatch_telemetry_migrate/20260903000011_add_fingerprint_to_exceptions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The parts the gem hashed this exception into an issue on, and where they
+# came from (its own default, a resolver, a per-call fingerprint, or the
+# error class itself) -- so an issue can show why it grouped the way it did.
+class AddFingerprintToExceptions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :exceptions, :fingerprint, :json, default: [], null: false
+    add_column :exceptions, :fingerprint_source, :string, limit: 16
+  end
+end

data/db/railwatch_telemetry_migrate/20260904000012_add_failed_to_broadcasts.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Whether a channel action raised. The gem reports the exception itself
+# (source "application.action_cable"); this flag lets the Broadcasts page mark
+# the failed action alongside its siblings, the way jobs and mail already do.
+class AddFailedToBroadcasts < ActiveRecord::Migration[8.1]
+  def change
+    add_column :broadcasts, :failed, :boolean, default: false, null: false
+  end
+end

data/db/railwatch_telemetry_migrate/20260904010000_add_filter_cursor_indexes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Keyset pagination orders every telemetry list by (sort column, id), so an
+# index that stops at the sort column still leaves SQLite sorting ties in a
+# temp B-tree. Each index below ends in id for that reason, and exists only
+# where the leading filter column is selective enough that seeking beats
+# scanning the ordering index and filtering.
+#
+# Deliberately NOT indexed, even though the FilterBar exposes them:
+# exceptions.handled, queries.connection, queries.role, and executions.queue
+# all carry a handful of distinct values in practice, so the existing ordering
+# index plus a row filter is as good as a seek and costs nothing on write.
+class AddFilterCursorIndexes < ActiveRecord::Migration[8.1]
+  def change
+    # Jobs page, filtered by tenant. index_executions_on_app_tenant_and_occurred_at
+    # cannot serve it: the page is already restricted to kind = "job".
+    add_index :executions, [ :kind, :app_tenant, :occurred_at, :id ], name: "idx_executions_kind_tenant_cursor"
+    # "Failed jobs" is the most-used view on that page and failures are rare,
+    # so the two-valued outcome column is highly selective here.
+    add_index :executions, [ :kind, :outcome, :occurred_at, :id ], name: "idx_executions_kind_outcome_cursor"
+
+    # exceptions has only (occurred_at); both of these filters are per-tenant
+    # or per-class needles in a large table.
+    add_index :exceptions, [ :app_tenant, :occurred_at, :id ], name: "idx_exceptions_tenant_cursor"
+    add_index :exceptions, [ :class_name, :occurred_at, :id ], name: "idx_exceptions_class_cursor"
+
+    add_index :logs, [ :app_tenant, :occurred_at, :id ], name: "idx_logs_tenant_cursor"
+    # Replaced, not added: the same index with the keyset tiebreaker appended.
+    remove_index :logs, [ :level, :occurred_at ], name: "index_logs_on_level_and_occurred_at"
+    add_index :logs, [ :level, :occurred_at, :id ], name: "idx_logs_level_cursor"
+
+    # The queries page sorts by duration, which index_queries_on_occurred_at_and_duration
+    # cannot order by. The first index serves the unfiltered page.
+    add_index :queries, [ :duration, :id ], name: "idx_queries_duration_cursor"
+    add_index :queries, [ :app_tenant, :duration, :id ], name: "idx_queries_tenant_duration_cursor"
+  end
+end

data/db/railwatch_telemetry_migrate/20260904020000_add_n_plus_ones_execution_id_index.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# n_plus_ones had no execution_id index, alone among the child tables, so
+# every trace page and every get_route call that asked "which N+1s did
+# these requests hit" scanned the table: 1.6 s at 70k rows on the
+# platform's own tenant, and it only grows.
+class AddNPlusOnesExecutionIdIndex < ActiveRecord::Migration[8.1]
+  def change
+    add_index :n_plus_ones, :execution_id, name: "index_n_plus_ones_on_execution_id"
+  end
+end

data/db/railwatch_telemetry_migrate/20260904120000_create_query_shapes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# A query group's normalized statement, stored once; rows that carry
+# exactly it store "" instead (docs/architecture.md). queries.sql keeps
+# its NOT NULL: relaxing it would rewrite the table on every tenant, which
+# SQLite cannot do in place and the deploy's health window cannot afford.
+class CreateQueryShapes < ActiveRecord::Migration[8.1]
+  def change
+    create_table :query_shapes, id: false do |t|
+      t.string :group_hash, null: false, limit: 32
+      t.text :sql, null: false
+    end
+    add_index :query_shapes, :group_hash, unique: true
+  end
+end

data/db/railwatch_telemetry_migrate/20260906120000_add_backpressure_factor_to_ingest_batches.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The gem reports when load forces it to sample every execution kind, so the
+# platform can distinguish quiet traffic from reduced client-side reporting.
+class AddBackpressureFactorToIngestBatches < ActiveRecord::Migration[8.1]
+  def change
+    add_column :ingest_batches, :backpressure_factor, :float, null: false, default: 1.0
+  end
+end

data/db/railwatch_telemetry_migrate/20260907000000_rename_lantern_version_on_processes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# The gem version a process reports. Column renamed with the platform; the
+# ingest mapper accepts both wire spellings while environments still run the
+# lantern gem.
+class RenameLanternVersionOnProcesses < ActiveRecord::Migration[8.1]
+  def change
+    rename_column :processes, :lantern_version, :nightrail_version
+  end
+end

data/db/railwatch_telemetry_migrate/20260913000000_rename_nightrail_version_on_processes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The gem version a process reports. Column renamed with the platform; the
+# ingest mapper still accepts the pinned lantern gem's wire spelling.
+class RenameNightrailVersionOnProcesses < ActiveRecord::Migration[8.1]
+  def change
+    rename_column :processes, :nightrail_version, :railwatch_version
+  end
+end

data/db/railwatch_telemetry_migrate/20260914000000_drop_orphan_durable_ingest_tables.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Telemetry half of the primary migration of the same name: #84's
+# rollup_cursors and source_maps, and #60's release_health_finalizations,
+# stayed behind in every tenant after their code was reverted or replaced.
+class DropOrphanDurableIngestTables < ActiveRecord::Migration[8.1]
+  ORPHAN_TABLES = %w[release_health_finalizations rollup_cursors source_maps].freeze
+  ORPHAN_VERSIONS = %w[20260904000013 20260905000100 20260905000200 20260905000400].freeze
+
+  def up
+    ORPHAN_TABLES.each { |table| drop_table table, if_exists: true }
+    execute "DELETE FROM schema_migrations WHERE version IN (#{ORPHAN_VERSIONS.map { |v| "'#{v}'" }.join(", ")})"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "the dropped tables belonged to reverted code; there is nothing to restore"
+  end
+end

data/db/railwatch_telemetry_migrate/20260914010000_drop_orphan_durable_ingest_columns.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The column half of the #84 cleanup (see 20260914000000): its migrations
+# also added delivery-state columns to ingest_batches and resolved-frame
+# columns to exceptions in every tenant before the code was reverted in
+# 5521379. Nothing reads them, and the weekly restore drill fails the
+# column comparison on every restored tenant. Indexes go first: SQLite
+# refuses to drop an indexed column.
+class DropOrphanDurableIngestColumns < ActiveRecord::Migration[8.1]
+  def up
+    remove_index :ingest_batches, :followups_completed_at, if_exists: true
+    remove_index :ingest_batches, :delivery_key, if_exists: true
+    remove_index :ingest_batches, :batch_id, if_exists: true
+    %i[batch_id delivery_key followups followups_completed_at].each do |column|
+      remove_column :ingest_batches, column if column_exists?(:ingest_batches, column)
+    end
+    %i[resolved_frames resolved_frames_key].each do |column|
+      remove_column :exceptions, column if column_exists?(:exceptions, column)
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "the dropped columns belonged to reverted code; there is nothing to restore"
+  end
+end

data/db/railwatch_telemetry_migrate/20260915000000_create_llm_calls.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# One row per RubyLLM call: a model call of any operation, or a tool
+# invocation (operation "tool", which carries a name and a duration but no
+# tokens or cost). Token counts keep RubyLLM's normalized buckets rather
+# than a provider's own names, and cost is nanodollars so a month of rollup
+# sums stays exact -- nil there means unpriced, never free.
+class CreateLlmCalls < ActiveRecord::Migration[8.1]
+  def change
+    create_table :llm_calls do |t|
+      # The record envelope as it was when this migration shipped; inlined so
+      # the history never calls a model that has since changed.
+      t.datetime :occurred_at, null: false, precision: 6
+      t.string :deploy, limit: 128
+      t.string :server, limit: 255
+      t.string :group_hash, limit: 32
+      t.string :trace_id, limit: 36
+      t.string :execution_source, limit: 20
+      t.string :execution_id, limit: 36
+      t.string :execution_preview, limit: 255
+      t.string :execution_stage, limit: 32
+      t.string :user_ref, limit: 255
+      t.string :app_tenant, limit: 255
+      t.string :operation, null: false, limit: 20
+      t.string :provider, limit: 64
+      t.string :model, limit: 255
+      t.string :response_model, limit: 255
+      t.string :tool_name, limit: 255
+      t.integer :duration, null: false
+      t.string :status, limit: 16
+      t.string :error, limit: 255
+      t.boolean :streaming
+      t.integer :message_count
+      t.integer :tool_count
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :cache_read_tokens
+      t.integer :cache_write_tokens
+      t.integer :thinking_tokens
+      t.bigint :cost_nanos
+      # Present only for calls made inside RubyLLM.workflow (2.0 and up).
+      # The parent step id is what reconstructs a nested agent run.
+      t.string :workflow_id, limit: 64
+      t.string :workflow_name, limit: 255
+      t.string :workflow_step_id, limit: 64
+      t.string :workflow_step_name, limit: 255
+      t.string :workflow_step_parent_id, limit: 64
+      t.text :prompt
+      t.text :completion
+    end
+    add_index :llm_calls, [ :group_hash, :occurred_at ]
+    add_index :llm_calls, [ :execution_id ]
+    add_index :llm_calls, [ :workflow_id, :occurred_at ]
+  end
+end

data/db/railwatch_telemetry_migrate/20260915120000_add_detail_to_llm_calls.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# What an LLM call carried and how it was configured, alongside what it
+# cost. finish_reason is the one that changes what you can see: max_tokens
+# means the answer was cut off, and a truncated extraction otherwise reads
+# exactly like a complete one.
+class AddDetailToLlmCalls < ActiveRecord::Migration[8.1]
+  def change
+    change_table :llm_calls, bulk: true do |t|
+      t.string :finish_reason, limit: 32
+      t.string :provider_request_id, limit: 128
+      t.string :tools, limit: 1024
+      t.boolean :cost_reported
+      t.integer :attachments
+      t.string :attachment_types, limit: 128
+      t.string :attachment_names, limit: 1024
+      t.string :tool_call_id, limit: 128
+      t.json :params
+    end
+  end
+end

data/db/railwatch_telemetry_migrate/20260915200000_add_explained_index_to_queries.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# The queries page asks "which of these 200 shapes have a captured plan in
+# the window?" -- WHERE occurred_at BETWEEN ? AND ? AND group_hash IN (200
+# values) AND explain IS NOT NULL. The planner walks the (group_hash,
+# occurred_at) index for every one of the 200 shapes and then checks
+# `explain` on each row, which is 840 ms at one day of one environment's
+# queries (1M rows), and that whole time is a GVL hold: sqlite3-ruby does
+# not release the GVL inside sqlite3_step. Plans are only captured for slow
+# queries, so a partial index over just the explained rows is tiny and
+# answers the question in 4 ms.
+class AddExplainedIndexToQueries < ActiveRecord::Migration[8.1]
+  def change
+    add_index :queries, [ :group_hash, :occurred_at ], name: "idx_queries_explained", where: "explain IS NOT NULL"
+  end
+end

data/db/railwatch_telemetry_migrate/20260915210000_add_slowest_index_to_queries.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# The queries page's "slowest in window" list orders the window by duration
+# and takes a page. Every existing index leads with occurred_at, so the
+# planner scans the whole window and sorts it: 48 ms for a day of one
+# environment's queries (1M rows) -- and sqlite3-ruby holds the GVL for the
+# whole statement, so every other request thread waits too. An index that
+# leads with (duration DESC, id DESC) matches the page's ORDER BY exactly, so
+# SQLite walks it from the slowest row and stops at the page (microseconds,
+# and it cannot get worse as the table grows); occurred_at rides along so
+# the window filter is answered from the index too. The planner still
+# prefers the occurred_at index on its own cost model, so CursorPage forces
+# this one.
+class AddSlowestIndexToQueries < ActiveRecord::Migration[8.1]
+  def change
+    add_index :queries, [ :duration, :id, :occurred_at ], name: "idx_queries_slowest", order: { duration: :desc, id: :desc }
+  end
+end

data/db/railwatch_telemetry_migrate/20260917010000_add_batch_ledger_to_ingest_batches.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Delivery ledger for in-process ingest. The reporter gives every batch a
+# stable id before the first attempt; recording it on the ingest_batches row
+# inside the batch transaction lets a retry ask "did this commit?" instead of
+# guessing, and lets the follow-up work the batch still owes (exception
+# grouping, which writes the other database) be resumed after a crash.
+# `followups` is the small outbox: nil once everything has run.
+class AddBatchLedgerToIngestBatches < ActiveRecord::Migration[8.1]
+  def change
+    add_column :ingest_batches, :batch_id, :string, limit: 36
+    add_column :ingest_batches, :followups, :json
+    add_index :ingest_batches, :batch_id, unique: true
+    add_index :ingest_batches, :received_at, where: "followups IS NOT NULL", name: "index_ingest_batches_pending_followups"
+  end
+end

data/docs/configuration.md

@@ -21,6 +21,8 @@ initializer always win over the env var.
 | `server` | `RAILWATCH_SERVER` | `KAMAL_HOST`, else `Socket.gethostname` | Host stamped on every record. Under Kamal the container hostname carries a per-deploy container id, so the Kamal host wins; it is what the post-deploy hook registers as an expected server, which is what silent-host detection compares against. |
 | `environment` | — | resolved lazily from `Rails.env` | Set `c.environment = "staging"` to report under a name other than the actual Rails env. |
 | `ignored_request_paths` | `RAILWATCH_IGNORED_REQUEST_PATHS` (comma-separated) | `/up,/railwatch/beacon` | Exact request paths that bypass Railwatch's request execution entirely. In Ruby configuration, `Regexp` entries are also supported. Setting the env var replaces the defaults; append with `c.ignored_request_paths += ["/healthz"]` to keep them. |
+| `beacon_allowed_origins` | `RAILWATCH_BEACON_ALLOWED_ORIGINS` | `[]` | Extra origins allowed to post to the beacon beyond the app's own, comma-separated: a full origin (`https://app.example.com`) or a bare host. Like Sentry's allowed domains this bounds abuse rather than authenticating, since an endpoint a browser posts to cannot hold a secret. |
+| `beacon_global_rate_limit` | `RAILWATCH_BEACON_GLOBAL_RATE_LIMIT` | `6000` | Beacons accepted per minute across every client, so a rotating address cannot multiply past the per-client limit. 0 disables it. |
 | `beacon_rate_limit` | `RAILWATCH_BEACON_RATE_LIMIT` | `120` | Beacon POSTs accepted per client IP per minute before `POST /railwatch/beacon` answers 429. The beacon is unauthenticated and keeps every browser error it is sent, so this is what stops a script from spending the app's event quota. Counted in the app's cache store; `0` turns it off. |
 
 `Railwatch.enabled?` delegates to `config.enabled?`, which is `@enabled &&
@@ -858,6 +860,30 @@ in `lib/railwatch.rb`, unless noted:
 `instrument_outgoing`, `flush`, `debug { }`. `pause`/`resume` are the
 ignore block's building blocks, and are nestable.
 
+## Embedded mode
+
+```ruby
+c.transport = :local        # RAILWATCH_TRANSPORT; default "http"
+c.issue_prefix = "SHOP"     # RAILWATCH_ISSUE_PREFIX; default from the app name
+c.repository_url = "..."    # RAILWATCH_REPOSITORY_URL
+c.retention_days = 7        # RAILWATCH_RETENTION_DAYS
+c.http_basic_auth_enabled = true      # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; on and closed until credentials exist
+c.http_basic_auth_user = "ops"        # RAILWATCH_HTTP_BASIC_AUTH_USER, or credentials railwatch.http_basic_auth_user
+c.http_basic_auth_password = "..."    # RAILWATCH_HTTP_BASIC_AUTH_PASSWORD, or credentials railwatch.http_basic_auth_password
+c.base_controller_class = "AdminController"  # RAILWATCH_BASE_CONTROLLER_CLASS; default ActionController::Base
+c.dashboard_open = false              # RAILWATCH_DASHBOARD_OPEN; public on purpose
+c.dashboard_user = ->(request) { { id:, name:, email: } or nil }
+```
+
+With `transport = :local` the reporter writes each batch into the app's
+own `railwatch_telemetry` database instead of POSTing it, and the engine
+serves the dashboard at its mount. `enabled?` no longer needs a token.
+The others only matter in that mode. The dashboard is behind HTTP Basic
+by default and answers 401 until `bin/rails
+railwatch:authentication:configure` has written credentials; a host with
+its own admin auth turns Basic off and sets `base_controller_class` or a
+routes constraint. Full walkthrough: [Embedded mode](embedded.md).
+
 ## Rake tasks
 
 Ship with the gem via Rails::Engine's default `lib/tasks` convention, in