railwatch 0.9.4 → 1.1.0

data/lib/railwatch.rb

@@ -21,19 +21,9 @@ require "railwatch/current"
 require "railwatch/record"
 require "railwatch/buffer"
 require "railwatch/transport/wire_encoder"
-require "railwatch/export/policy"
-require "railwatch/export/lease"
-require "railwatch/export/outbox"
-require "railwatch/export/client"
-require "railwatch/export/sender"
 require "railwatch/transport/http"
-require "railwatch/transport/local"
-require "railwatch/transport/socket"
-require "railwatch/writer"
 require "railwatch/authentication"
 require "railwatch/json_compat"
-require "railwatch/embedded"
-require "railwatch/ingest_request_body_limit"
 require "railwatch/reporter"
 require "railwatch/sampler"
 require "railwatch/redactor"
@@ -69,7 +59,7 @@ module Railwatch
     end
 
     def reporter
-      @reporter ||= Reporter.new(config, transport: local_transport)
+      @reporter ||= Reporter.new(config)
     end
 
     # Called once config/initializers has run, so a reporter built before
@@ -87,16 +77,6 @@ module Railwatch
       @reporter&.adopt_final_config!
     end
 
-    # Embedded mode: a Puma worker hands its batches to the writer process
-    # over the socket; the writer itself, and any process when no socket is
-    # configured, writes them straight into SQLite. nil means HTTP.
-    def local_transport
-      return nil unless config.local?
-      return Transport::Local.new(config) if Writer.running? || config.writer_socket_path.nil?
-
-      Transport::Socket.new(config)
-    end
-
     def redactor
       @redactor ||= Redactor.new(config)
     end
@@ -124,9 +104,7 @@ module Railwatch
       Subscribers::Users.restart_after_fork!
       Subscribers::ProcessInfo.restart_after_fork!
       Health.restart_after_fork!
-      Export::Sender.restart_after_fork!
       Sessions.restart_after_fork!
-      Maintenance.restart_after_fork!
     end
 
     # --- execution lifecycle -------------------------------------------------
@@ -619,45 +597,16 @@ module Railwatch
 end
 
 require "railwatch/subscribers"
-require "railwatch/dashboard_assets"
 
 module Railwatch
-  # Where the engine's two databases migrate from. database.yml names them
-  # (`migrations_paths: <%= Railwatch.migrations_path(:railwatch) %>`) so a
-  # host's db:prepare creates the tables on install and migrates them after
-  # every gem update, from the gem's own history, the way Active Storage
-  # migrates its tables. Nothing is copied into the app.
-  def self.migrations_path(database)
-    File.expand_path("../db/#{database}_migrate", __dir__)
-  end
-
-  # Where links the models build (a trace from an execution page, a saved
-  # view's page) resolve. The engine's own routes serve the embedded
-  # dashboard; a host that mounts these pages on its own routes, as
-  # Railwatch Cloud does, points this at them.
-  def self.url_helpers
-    @url_helpers || Engine.routes.url_helpers
-  end
-
-  def self.url_helpers=(helpers)
-    @url_helpers = helpers
-  end
-
-  # The one browser client, relative to the gem root. The dashboard bundle
-  # is built from it and the install generator copies it into a host.
-  BROWSER_CLIENT = "app/frontend/lib/railwatch.ts"
+  # The Inertia browser client, relative to the gem root. The install
+  # generator copies it into a host's app/frontend/lib.
+  BROWSER_CLIENT = "lib/generators/railwatch/install/templates/railwatch.ts"
 
   def self.browser_client_path
     File.expand_path("../#{BROWSER_CLIENT}", __dir__)
   end
 
-  # The dashboard's frontend source. Railwatch Cloud builds its bundle from
-  # this directory plus its own hosting pages, so there is one copy of every
-  # dashboard page and component.
-  def self.frontend_path
-    File.expand_path("../app/frontend", __dir__)
-  end
-
   # One realistic wire record per record type, exactly as the gem's own
   # subscribers emit it, generated by spec/railwatch/wire_fixtures_spec.rb.
   # A receiver tests its mapper against these instead of hand-writing what
@@ -669,12 +618,5 @@ module Railwatch
   def self.wire_fixtures
     @wire_fixtures ||= JSON.parse(File.read(wire_fixtures_path)).freeze
   end
-
-  # Raised when the engine's models are used in an app whose database.yml
-  # has no entry for them. They must never fall back to the host's primary
-  # connection: the telemetry tables are unprefixed (`sessions`, `visits`,
-  # `people`, `notifications`, `logs`), so a query there would read, and a
-  # write would corrupt, the application's own tables.
-  class DatabaseNotConfigured < StandardError; end
 end
 require "railwatch/engine" if defined?(Rails::Engine)

data/lib/tasks/railwatch_tasks.rake

@@ -28,130 +28,6 @@ module Railwatch
     end
   end
 
-  # What the embedded telemetry database is costing on disk, and the one-time
-  # conversion that lets pruning give that cost back.
-  #
-  # Deleting rows does not shrink a SQLite file. The pages go on the freelist
-  # and are reused by later inserts, and the only way back to the filesystem
-  # is auto_vacuum=incremental plus PRAGMA incremental_vacuum -- which
-  # PruneTelemetryJob now runs after every prune. A database can only enter
-  # that mode while it is still empty (EnableIncrementalVacuum does that for
-  # every telemetry database created since it shipped) or through a full
-  # VACUUM, which is what this offers to an older one.
-  class TelemetryDisk
-    # Deliberately pessimistic, and said out loud as an estimate: VACUUM
-    # rewrites the whole file, and what that costs is the operator's disk,
-    # not ours to know.
-    VACUUM_BYTES_PER_SECOND = 50 * 1024 * 1024
-
-    # nil, having said why, for an install with no telemetry database to
-    # talk about.
-    def self.open
-      unless Railwatch.config.local?
-        puts "Railwatch reports over HTTP here (transport = :http), so this app has no telemetry database; nothing to vacuum."
-        return nil
-      end
-
-      environment = Railwatch::Environment.current
-      return new(environment) if environment.with_telemetry { Railwatch::TelemetryRecord.sqlite? }
-
-      puts "The railwatch_telemetry database is not SQLite; auto_vacuum does not apply."
-      nil
-    end
-
-    def initialize(environment)
-      @environment = environment
-    end
-
-    def report
-      with_telemetry do
-        <<~TEXT.chomp
-          Railwatch telemetry database
-            file    #{path}
-            size    #{human(file_bytes)}#{" + #{human(wal_bytes)} WAL" if wal_bytes.positive?}
-            mode    auto_vacuum=#{mode}
-            free    #{freelist} pages (#{human(freelist * page_size)}) on the freelist
-        TEXT
-      end
-    end
-
-    def advice
-      with_telemetry do
-        if mode != :incremental
-          "\nPruning cannot return space to the filesystem in this mode: every page it frees stays in this file.\n" \
-            "`bin/rails railwatch:vacuum` converts the database to incremental auto-vacuum with a full VACUUM. " \
-            "That rewrites all #{human(file_bytes)}, needs about that much free disk for the temporary copy, and " \
-            "holds the write lock for roughly #{estimate}. Telemetry written while it runs waits for it."
-        elsif freelist.positive?
-          "\nThe nightly prune returns up to #{human(Railwatch::PruneTelemetryJob::VACUUM_PAGES_PER_SLICE * Railwatch::PruneTelemetryJob::VACUUM_SLICES * page_size)} " \
-            "a night on its own. `bin/rails railwatch:vacuum` returns all #{human(freelist * page_size)} now."
-        else
-          "\nNothing on the freelist: pruning is already returning this database's space as it goes."
-        end
-      end
-    end
-
-    # The whole point of asking explicitly, so this one is not bounded the way
-    # the nightly prune is.
-    def reclaim!
-      with_telemetry do
-        before = disk_bytes
-        if mode == :incremental
-          Railwatch::TelemetryRecord.incremental_vacuum
-        else
-          puts "\nConverting to incremental auto-vacuum (full VACUUM, roughly #{estimate})..."
-          connection.execute("PRAGMA auto_vacuum = incremental")
-          connection.execute("VACUUM")
-        end
-        # A checkpoint that cannot finish says so in its result rather than
-        # raising: a reader still on an older snapshot holds the WAL open.
-        # Counting only the main file would then report the WAL's bytes as
-        # returned while they are still on the disk.
-        busy = checkpoint_busy?
-        [
-          "\nauto_vacuum=#{mode}, #{human(disk_bytes)} on disk including the WAL " \
-            "(#{human(before - disk_bytes)} returned), #{freelist} pages left on the freelist.",
-          busy ? "The WAL could not be truncated yet -- something is still reading it. " \
-                 "Its bytes come back at the next checkpoint; run this again if you want to watch it." : nil
-        ].compact.join("\n")
-      end
-    end
-
-    private
-      def with_telemetry(&) = @environment.with_telemetry(&)
-
-      def connection = Railwatch::TelemetryRecord.connection
-
-      def mode = Railwatch::TelemetryRecord.auto_vacuum_mode
-
-      def freelist = Railwatch::TelemetryRecord.freelist_pages
-
-      def page_size = Railwatch::TelemetryRecord.page_size
-
-      def path = Rails.root.join(Railwatch::TelemetryRecord.connection_db_config.database.to_s)
-
-      def file_bytes = File.exist?(path) ? File.size(path) : 0
-
-      # What this database actually occupies. In WAL mode the pages a VACUUM
-      # frees are not off the disk until the WAL is checkpointed, so the main
-      # file alone understates it -- and, right after a vacuum, flatters it.
-      def disk_bytes = file_bytes + wal_bytes
-
-      # `PRAGMA wal_checkpoint` answers with [busy, log_pages, checkpointed];
-      # a non-zero first column means it gave up rather than failed.
-      def checkpoint_busy?
-        connection.select_rows("PRAGMA wal_checkpoint(TRUNCATE)").dig(0, 0).to_i != 0
-      rescue StandardError
-        false
-      end
-
-      def wal_bytes = File.exist?("#{path}-wal") ? File.size("#{path}-wal") : 0
-
-      def estimate = ActiveSupport::Duration.build([ (file_bytes / VACUUM_BYTES_PER_SECOND.to_f).ceil, 1 ].max).inspect
-
-      def human(bytes) = ActiveSupport::NumberHelper.number_to_human_size(bytes)
-  end
-
   # Where this install's platform lives, derived from config.ingest_url:
   # railwatch:token and railwatch:mcp point at the same host the gem already
   # ships to, so a self-hosted app never gets told to visit railwatch.rebulk.com.
@@ -189,10 +65,6 @@ namespace :railwatch do
 
   desc "Check that the app can reach Railwatch with the configured token"
   task status: :environment do
-    if Railwatch.config.local?
-      puts "Railwatch OK: embedded (telemetry in this app's railwatch_telemetry database; dashboard at /railwatch)"
-      next
-    end
     unless Railwatch.config.token.present?
       abort "RAILWATCH_TOKEN is not set"
     end
@@ -214,146 +86,6 @@ namespace :railwatch do
       ok
     end
 
-    if config.local?
-      # Embedded: no token and no ingest host. What can go wrong instead is
-      # the two databases the engine writes to and the jobs that derive
-      # rollups and issues from them.
-      check.call(true, "transport", "local (telemetry stays in this app; dashboard at the engine mount)")
-      # Mirroring is opt-in, so silence means "not asked for". Asked for and
-      # not working is the case worth failing on: the operator believes their
-      # telemetry is leaving the box and it is not.
-      if config.export_enabled
-        problem = config.export_problem
-        check.call(problem.nil?, "export", problem || "mirroring to #{config.resolved_export_url}", fatal: true)
-        if problem.nil?
-          status = Railwatch::Export::Outbox.new(config, Railwatch::Environment.current)
-                                            .then { |outbox| Railwatch::Environment.current.with_telemetry { outbox.status } }
-          check.call(status[:state] == "ready", "export destination",
-                     status[:state] == "ready" ? "#{status[:queued_deliveries]} queued (#{status[:queued_bytes]} bytes), producer #{status[:producer_id]}" : "#{status[:state]}: #{status[:reason]} (bin/rails railwatch:export:rebind to clear)")
-        end
-      end
-      %w[railwatch railwatch_telemetry].each do |name|
-        configured = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env, name: name)
-        check.call(!configured.nil?, "#{name} database",
-                   configured ? configured.database : "not in config/database.yml (bin/rails generate railwatch:install)",
-                   fatal: true)
-      end
-      { "railwatch_telemetry" => Railwatch::TelemetryRecord, "railwatch" => Railwatch::ApplicationRecord }.each do |name, base|
-        pending = begin
-          base.connection_pool.migration_context.open.pending_migrations.map(&:version)
-        rescue StandardError => e
-          e.message
-        end
-        check.call(pending == [], "#{name} migrations",
-                   case pending
-                   when [] then "up to date"
-                   when Array then "#{pending.size} pending (bin/rails db:prepare)"
-                   else "cannot check: #{pending}"
-                   end, fatal: true)
-      end
-      # An install created before 0.3.5 is in auto_vacuum=none, where the
-      # nightly prune's reclaim is a silent no-op and the file only grows.
-      # Nothing converts it on its own, because that needs a full VACUUM with
-      # the write lock held -- so the check people actually run is where it
-      # has to be said, rather than leaving them to notice the disk.
-      if Railwatch.config.local? && Railwatch::TelemetryRecord.sqlite?
-        vacuum_mode = begin
-          Railwatch::Environment.current.with_telemetry { Railwatch::TelemetryRecord.auto_vacuum_mode }
-        rescue StandardError => e
-          e.message
-        end
-        check.call(vacuum_mode == :incremental, "telemetry disk",
-                   case vacuum_mode
-                   when :incremental then "auto_vacuum=incremental; the nightly prune returns freed pages"
-                   when Symbol then "auto_vacuum=#{vacuum_mode}: pruned pages stay in the file " \
-                                    "(bin/rails railwatch:vacuum:status)"
-                   else "cannot check: #{vacuum_mode}"
-                   end)
-      end
-      # The maintenance clock runs in web and worker processes, not in this
-      # rake process, so what can be checked here is whether one has ticked.
-      last_tick = begin
-        Railwatch::MaintenanceTask.last_tick_at
-      rescue StandardError
-        nil
-      end
-      check.call(last_tick && last_tick > 10.minutes.ago, "maintenance",
-                 if last_tick
-                   "last tick #{ActiveSupport::Duration.build((Time.current - last_tick).round).inspect} ago"
-                 else
-                   "no tick recorded yet (runs inside the app's web and worker processes, not in rake)"
-                 end)
-      socket_path = config.writer_socket_path
-      if socket_path && !Railwatch::Writer.usable_path?(socket_path)
-        check.call(false, "writer process",
-                   "socket path is #{socket_path.bytesize} bytes, over Linux's #{Railwatch::Writer::MAX_SOCKET_PATH}; " \
-                   "set RAILWATCH_WRITER_SOCKET to a shorter path (e.g. /tmp/#{Rails.application.class.module_parent_name.parameterize}-railwatch.sock)")
-      elsif socket_path
-        listening = Railwatch::Writer.listening?(socket_path)
-        puma_rb = Rails.root.join("config/puma.rb")
-        plugged = puma_rb.exist? && puma_rb.read.include?("plugin :railwatch")
-        # Not listening is only fine when the app is not running: this task
-        # is its own process and cannot tell, so it says which case it is
-        # looking at instead of calling a missing writer a pass.
-        check.call(listening, "writer process",
-                   if listening
-                     "listening at #{socket_path}"
-                   elsif plugged
-                     "not listening at #{socket_path} right now. Expected if the app is stopped; if it is serving, " \
-                     "the writer died or `plugin :railwatch` never activated (check the Puma log)"
-                   else
-                     "not configured: add `plugin :railwatch` to config/puma.rb so batches are written outside the " \
-                     "processes serving requests"
-                   end)
-        # A socket that answers is a process that is alive; the ledger is
-        # what says it is doing its job. Nothing written in a while with the
-        # app serving traffic is a writer that is stuck or a worker that is
-        # not reaching it.
-        if listening
-          last_write = begin
-            Railwatch::Environment.current.with_telemetry { Railwatch::Telemetry::IngestBatch.maximum(:received_at) }
-          rescue StandardError
-            nil
-          end
-          check.call(last_write && last_write > 5.minutes.ago, "last write",
-                     if last_write
-                       "#{ActiveSupport::Duration.build((Time.current - last_write).round).inspect} ago"
-                     else
-                       "no batch written yet"
-                     end)
-        end
-      end
-      # HTTP Basic is on and closed until credentials exist; a deploy that
-      # forgot gets a 401, not a public page, and this says so first.
-      gate = config.dashboard_gate
-      check.call(gate != :undeclared && !(gate == :basic && !config.http_basic_auth_configured? && !config.http_basic_auth_waived?),
-                 "dashboard access",
-                 case gate
-                 when :basic
-                   if config.http_basic_auth_configured?
-                     "HTTP Basic, user #{config.http_basic_auth_user}"
-                   elsif config.http_basic_auth_waived?
-                     "open in development. Production stays closed until you run " \
-                       "`RAILS_ENV=production bin/rails railwatch:authentication:configure`"
-                   else
-                     "closed: HTTP Basic is on with no credentials, so every dashboard request is 401. " \
-                       "Run `bin/rails railwatch:authentication:configure`"
-                   end
-                 when :controller then "your own: c.base_controller_class = #{config.base_controller_class}"
-                 when :resolver then "your own: c.dashboard_user decides, and live updates follow it"
-                 when :open then "deliberately open: anyone who can reach the mount can read it (c.dashboard_open)"
-                 else
-                   "undeclared: HTTP Basic is off and no base_controller_class, dashboard_user or dashboard_open " \
-                   "is set. If a routes constraint gates the mount, say so with `c.dashboard_open = true` " \
-                   "(it also enables live updates); otherwise the dashboard is public"
-                 end)
-      check.call(!Railwatch::JsonCompat.broken?, "json compatibility",
-                 Railwatch::JsonCompat.broken? ? Railwatch::JsonCompat.advice : "json #{Railwatch::JsonCompat.json_version} decodes on Rails #{Rails.version}")
-      recurring = Rails.root.join("config/recurring.yml")
-      leftover = recurring.exist? && recurring.read.include?("Railwatch::")
-      check.call(!leftover, "recurring.yml",
-                 leftover ? "Railwatch::* jobs listed in config/recurring.yml are no longer needed in embedded mode; remove them" : "no Railwatch entries (none needed)")
-    else
     token = config.token.to_s
     check.call(!token.empty?, "token",
                token.empty? ? "RAILWATCH_TOKEN is not set" : Railwatch::SecretSafety.token_preview(token),
@@ -380,7 +112,6 @@ namespace :railwatch do
 
     check.call(Railwatch::Transport::Http.new(config).ping, "ingest reachable",
                "GET #{URI.join(config.ingest_url, '/ingest/ping')}", fatal: true)
-    end
 
     middleware = Rails.application.middleware.map(&:name)
     position = middleware.index("Railwatch::Middleware::Request")
@@ -447,47 +178,6 @@ namespace :railwatch do
     puts "\nRailwatch is wired up."
   end
 
-  # Disk. `railwatch:vacuum:status` only reads; `railwatch:vacuum` is the
-  # one-time conversion a database created before EnableIncrementalVacuum
-  # needs, and it is a rake task rather than anything automatic because it
-  # rewrites the whole file with the write lock held.
-  desc "Report the telemetry database's size, free pages, and whether pruning can return them to the filesystem"
-  task "vacuum:status" => :environment do
-    disk = Railwatch::TelemetryDisk.open or next
-    puts disk.report
-    puts disk.advice
-  end
-
-  desc "Reclaim disk from the telemetry database. Converts it to incremental auto-vacuum if needed -- a full VACUUM, which locks the file"
-  task vacuum: :environment do
-    disk = Railwatch::TelemetryDisk.open or next
-    puts disk.report
-    puts disk.reclaim!
-  end
-
-  namespace :export do
-    desc "Show what the export queue is holding and whether it can send"
-    task status: :environment do
-      env = Railwatch::Environment.current
-      status = env.with_telemetry { Railwatch::Export::Outbox.new(Railwatch.config, env).status }
-      status.each { |key, value| puts "#{key}: #{value}" }
-    end
-
-    desc "Clear a credential block, abandoning work admitted under the old token"
-    task rebind: :environment do
-      env = Railwatch::Environment.current
-      discarded = env.with_telemetry { Railwatch::Export::Outbox.new(Railwatch.config, env).rebind! }
-      puts discarded ? "rebound; #{discarded} queued deliveries abandoned" : "export is not configured"
-    end
-
-    desc "Abandon everything queued for export without contacting the receiver"
-    task discard: :environment do
-      env = Railwatch::Environment.current
-      count = env.with_telemetry { Railwatch::Export::Outbox.new(Railwatch.config, env).discard_all! }
-      puts "#{count} queued deliveries abandoned"
-    end
-  end
-
   desc "Print where to create an ingest token for this app's Railwatch platform"
   task token: :environment do
     base = Railwatch::Endpoints.new(Railwatch.config)
@@ -583,9 +273,10 @@ namespace :railwatch do
 
   # The same shape as `mission_control:jobs:authentication:configure`: asks
   # for a user and password and writes them to the current environment's
-  # credentials under `railwatch:`, which the engine reads at boot.
+  # credentials under `railwatch:`, which the engine reads at boot and
+  # railwatch-server's dashboard proxy checks.
   #   RAILS_ENV=production bin/rails railwatch:authentication:configure
-  desc "Configure HTTP Basic authentication for the embedded dashboard (writes Rails credentials)"
+  desc "Configure HTTP Basic authentication for railwatch-server's dashboard (writes Rails credentials)"
   task "authentication:configure" => :environment do
     Railwatch::Authentication.configure
   end
@@ -593,19 +284,6 @@ namespace :railwatch do
   desc "Send deploy metadata to Railwatch: rake railwatch:deploy[ref,name,url]"
   task :deploy, [ :ref, :name, :url ] => :environment do |_t, args|
     deploy = Railwatch.config.deploy or abort "RAILWATCH_DEPLOY (or KAMAL_VERSION) is not set"
-    if Railwatch.config.local?
-      # Embedded: the deploy marker is a row in this app's railwatch database.
-      row = Railwatch::Environment.current.deploys.find_or_initialize_by(deploy: deploy.to_s.first(128))
-      row.assign_attributes(ref: (args[:ref] || `git rev-parse HEAD 2>/dev/null`.strip).presence&.first(128),
-                            name: args[:name].presence&.first(255), url: args[:url].presence&.first(1024),
-                            server: Railwatch.config.server, deployed_at: Time.current,
-                            commits: Railwatch::DeployMetadata.commits,
-                            detail: { performer: ENV["KAMAL_PERFORMER"], destination: ENV["KAMAL_DESTINATION"],
-                                      service: ENV["KAMAL_SERVICE"] }.compact)
-      row.save!
-      puts "Deploy #{deploy} recorded"
-      next
-    end
     abort "Plain HTTP ingest is disabled; use HTTPS or set RAILWATCH_ALLOW_HTTP=true" unless Railwatch.config.ingest_url_allowed?
     uri = URI.join(Railwatch.config.ingest_url, "/ingest/deploys")
     req = Net::HTTP::Post.new(uri)

data/llms.txt

@@ -1,44 +1,42 @@
 # Railwatch
 
-> Railwatch is a Ruby gem that instruments a Rails application end to end —
-> requests, jobs, scheduled tasks, rake/runner commands, database queries and
-> N+1s, exceptions, cache, mail, notifications, broadcasts, outgoing HTTP,
-> Active Storage, view renders, RubyLLM calls, and logs — links every one of
-> them into a single execution tree by `execution_id`/`trace_id`, and writes
-> them from a background thread into two SQLite files the app owns (embedded,
-> the default) or to Railwatch Cloud. It replaces a separate APM and a
-> separate error tracker with one gem and one configuration block, costs
-> under a millisecond of CPU per request, and never writes to the
-> application's primary database. Install is `bundle add railwatch` followed
-> by `bin/rails generate railwatch:install`, which by default keeps
-> everything in the app (two SQLite databases, a Puma writer process, the
-> dashboard at `/railwatch`, open in development and password-protected
-> elsewhere); with `--cloud` or a token option it sends to Railwatch Cloud
-> instead, and an embedded install can export to the cloud as well. It
-> writes the initializer, mounts the engine, adds a Kamal post-deploy hook
-> and the Inertia browser client where the app has them, and wires the test
+> Railwatch is a Ruby gem (the agent) that instruments a Rails application end
+> to end — requests, jobs, scheduled tasks, rake/runner commands, database
+> queries and N+1s, exceptions, cache, mail, notifications, broadcasts,
+> outgoing HTTP, Active Storage, view renders, RubyLLM calls, and logs — links
+> every one of them into a single execution tree by `execution_id`/`trace_id`,
+> and sends them from a background thread over HTTPS to a Railwatch server:
+> Railwatch Cloud (the default), a self-hosted railwatch-rs, or the one the
+> separate `railwatch-server` gem runs next to Puma for an embedded dashboard
+> at `/railwatch`. It replaces a separate APM and a separate error tracker
+> with one gem and one configuration block, costs under a millisecond of CPU
+> per request, and never writes to the application's primary database.
+> Install is `bundle add railwatch` followed by
+> `bin/rails generate railwatch:install` (`--prompt-token`, `--url` for a
+> self-hosted server, `--kamal-secrets`), which writes the initializer,
+> mounts the engine for the browser beacon, adds a Kamal post-deploy hook and
+> the Inertia browser client where the app has them, and wires the test
 > matchers. `bin/rails railwatch:doctor` prints a ✓/✗ line for every piece.
 
 ## Docs
 
-- [README](README.md): what Railwatch is, the install, embedded mode, and where each document fits.
-- [Getting started](docs/getting-started.md): the two-command embedded install, the Railwatch Cloud install and where its token comes from, the three optional lines, and deploying under Kamal, Docker/Heroku/Render, or no deploy tool at all.
-- [Embedded mode](docs/embedded.md): the default install — the dashboard inside the app, its two SQLite databases, dashboard authentication, the Puma writer process, maintenance without a job worker, disk reclaim, and optional export to Railwatch Cloud.
-- [Configuration](docs/configuration.md): every configuration option and its `RAILWATCH_*` environment variable, plus the full public facade, redaction, rejection, transport and buffering behaviour, and the rake tasks.
+- [README](README.md): what Railwatch is, where telemetry goes (Cloud, self-hosted, railwatch-server), the install, and where each document fits.
+- [Getting started](docs/getting-started.md): the install and where its token comes from, embedded with the `railwatch-server` gem, moving from 0.x embedded mode, the three optional lines, and deploying under Kamal, Docker/Heroku/Render, or no deploy tool at all.
+- [Configuration](docs/configuration.md): every configuration option and its `RAILWATCH_*` environment variable, plus the full public facade, redaction, rejection, transport and buffering behaviour, the dashboard gate railwatch-server uses, and the rake tasks.
 - [Record types](docs/records.md): every record type the gem ships and every attribute on it, including RubyLLM calls (tokens, cost, finish reason, tool calls, workflows), sourced from the code that builds it.
 - [Testing](docs/testing.md): the RSpec and Minitest matchers (`have_railwatch_queries`, `have_railwatch_n_plus_one`, `record_railwatch_span`, `record_railwatch_exception`, `have_railwatch_outgoing_requests`, `have_railwatch_http_in_transaction`) and a CI performance-gate recipe.
 - [Production source maps](docs/source-maps.md): hidden Vite maps, private upload before publishing assets, safe opt-in deletion, resolved browser stacks and default issue grouping.
-- [AI assistants and MCP](docs/ai-and-mcp.md): Railwatch Cloud's MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
+- [AI assistants and MCP](docs/ai-and-mcp.md): the server's MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
 - [Replacing Sentry](docs/replacing-sentry.md): a step-by-step migration — removing the gems, porting each option, rewriting each call site, breadcrumbs, spans, profiling, attachments, `before_send`, fingerprints, and release health.
 - [Coming from Laravel Nightwatch](docs/replacing-nightwatch.md): the record-type mapping, what "execution" means in Railwatch, sampling parity, and the facade method names in Ruby.
-- [Self-hosting](docs/self-hosting.md): pointing the gem at a self-hosted Railwatch Cloud, creating a token there, and checking the connection.
-- [Troubleshooting](docs/troubleshooting.md): every `railwatch:doctor` line, embedded and cloud, and the failure modes behind them — no records, doubled scheduled tasks, WebMock in specs, Puma fork, tail-sampling memory, missing profiler, missing deploy marker, Kamal hook, log search, empty tenants.
+- [Self-hosting](docs/self-hosting.md): pointing the gem at a self-hosted railwatch-rs, creating a token there, and checking the connection.
+- [Troubleshooting](docs/troubleshooting.md): every `railwatch:doctor` line and the failure modes behind them — no records, doubled scheduled tasks, WebMock in specs, Puma fork, tail-sampling memory, missing profiler, missing deploy marker, Kamal hook, log search, empty tenants.
 - [Security](docs/security.md): transport, capture defaults, the browser beacon, token handling, and application responsibilities.
 - [FAQ](docs/faq.md): overhead numbers and how they are measured, retention, what is redacted by default versus opt-in, SQLite, and what happens when the platform is unreachable.
 
 ## For coding agents
 
-- [AGENTS.md](AGENTS.md): how to install and use Railwatch from inside a Rails app — the facade methods, the spec matchers, `railwatch:doctor`, and the Railwatch Cloud MCP hookup.
+- [AGENTS.md](AGENTS.md): how to install and use Railwatch from inside a Rails app — the facade methods, the spec matchers, `railwatch:doctor`, and the MCP hookup.
 
 ## Optional