railwatch 0.9.3 → 1.0.0

data/docs/replacing-sentry.md

@@ -8,10 +8,9 @@ depends on a conditional row.
 
 Install Railwatch first ([`getting-started.md`](getting-started.md)); you
 can run both for a day if you want to compare, since neither knows about
-the other. The default install is embedded, with the dashboard at
-`/railwatch` and no token. The token and alert steps below apply when
-you send to Railwatch Cloud, either as a cloud install or by exporting
-from embedded.
+the other. The token steps below apply to Railwatch Cloud and to a
+self-hosted railwatch-rs; with the `railwatch-server` gem the token is
+set for you.
 
 ## Decide whether Railwatch covers your workload
 
@@ -33,7 +32,7 @@ Railwatch does not claim those broader capabilities.
 | Ruby profiling | Conditional | Requires `vernier` or `stackprof`; there is no profiler bundled into the SDK. |
 | Browser monitoring | Partial | The optional Inertia client reports visits, Web Vitals, browser errors, and breadcrumbs. Session Replay, native/mobile SDKs, and Sentry's full browser/source-map workflow are outside the currently released Rails-server replacement. |
 | Runtime compatibility | Narrow today | The currently proved pair is Ruby 3.4 + Rails 8.1. A maintained compatibility matrix and any safe lowering of requirements are tracked by [#26](https://github.com/Rebulk/railwatch/issues/26). |
-| Managed integrations and operations | Partial | Railwatch Cloud delivers alerts to email, Slack, webhooks and Linear, plus self-hosting; embedded mode records alerts without delivering them. It does not promise Sentry's broader integration catalog. |
+| Managed integrations and operations | Partial | Railwatch Cloud and railwatch-rs deliver alerts to email, Slack, webhooks and Linear. It does not promise Sentry's broader integration catalog. |
 | SQL value privacy | Supported by default | Query records carry normalized SQL shapes without literal values, and Active Record binds are never sent. Raw SQL and query plans are separate opt-ins; either can contain values. |
 
 For a Rails 8.1 application whose work enters through Rack and Active Job,
@@ -73,11 +72,10 @@ deploy config once the app boots without it.
 `config/initializers/railwatch.rb` (written by the install generator) is
 where every option from `Sentry.init` lands. The mapping:
 
-- **`dsn:`** has no equivalent in embedded mode, which stores telemetry in
-  the app. For Railwatch Cloud it becomes `RAILWATCH_TOKEN`, one token per
-  environment, created in Railwatch Cloud. Self-hosting adds
-  `RAILWATCH_INGEST_URL`. On a cloud install the token is also the on/off
-  switch: with it blank, Railwatch installs nothing.
+- **`dsn:`** becomes `RAILWATCH_TOKEN`, one token per environment,
+  created in Railwatch Cloud or your own server. Self-hosting adds
+  `RAILWATCH_INGEST_URL`. The token is also the on/off switch: with it
+  blank, Railwatch installs nothing.
 - **`environment:`** becomes `c.environment`, which defaults to
   `Rails.env` — set it only to report under a different name.
 - **`release:`** becomes `c.deploy`, which auto-detects the release from
@@ -116,9 +114,7 @@ where every option from `Sentry.init` lands. The mapping:
 - **Rack `X-Request-Start` queue time** needs no setting: it is parsed
   into `queue_time` on every `request` record.
 
-A worked initializer for a cloud install, roughly what a `Sentry.init`
-block turns into (an embedded install has `c.transport = :local` instead
-of the token):
+A worked initializer, roughly what a `Sentry.init` block turns into:
 
 ```ruby
 # config/initializers/railwatch.rb
@@ -424,7 +420,7 @@ startRailwatch({
 |---|---|
 | `Sentry.init({ dsn })` | `startRailwatch()`. There is no DSN: the beacon posts to the app's own origin and the *server* decides whether to record it (`c.beacon_enabled`, and whether Railwatch is enabled). The gate you already have on whether `startRailwatch()` runs at all is the only gate. |
 | `release` | Automatic. The record is stamped with `c.deploy`, the same release the server records carry, so a browser issue and a server issue from one deploy line up without a matching pair of settings to get wrong. |
-| `environment` | Automatic — the embedded databases belong to one environment, and on Railwatch Cloud the ingest token identifies it. |
+| `environment` | Automatic — the ingest token identifies the environment. |
 | `ignoreErrors` | `startRailwatch({ ignoreErrors })`. Strings match anywhere in the message; regexes are tested against it. Both `ResizeObserver` messages are ignored by default. |
 | `denyUrls` | `startRailwatch({ denyUrls })`, matched against the top stack frame's URL. `/extensions\//i`, `/^chrome:\/\//i`, and `/^moz-extension:\/\//i` are denied by default, **and** any frame from an origin that isn't the app's own is dropped — extensions, injected widgets, tag managers. |
 | `Sentry.setUser` | Server-side. The beacon is a same-origin POST carrying the session cookie, so the server resolves the user the same way it does for a request (`Railwatch.user`) when `Current.user` or Warden is set by middleware; an app that authenticates in a `before_action` gives Railwatch the same lookup with `c.beacon_user { \|request\| ... }`. Nothing the browser sends names the user, so it cannot be forged. |
@@ -568,10 +564,10 @@ hook matching `rails runner …` previews, or `sentry_runner_noise.rb` under
 | Inertia visit timing | Real browser page-visit duration, prop byte size, partial reloads, SSR time, and Core Web Vitals, from a client the generator installs. |
 | Spec matchers as a CI gate | `have_railwatch_queries`, `have_railwatch_n_plus_one`, `have_railwatch_outgoing_requests` fail the pull request that regresses a hot path. |
 | Zero app-DB writes | The gem holds records in memory and ships them from a background thread; a bench gate asserts no `INSERT`/`UPDATE`/`DELETE` ever originates in `lib/railwatch`. This is why it is safe on single-writer SQLite. |
-| A dashboard inside the app | The default install serves the whole dashboard at `/railwatch` from two SQLite files the app owns, with no hosted service at all ([`embedded.md`](embedded.md)). |
+| A dashboard inside the app | The `railwatch-server` gem runs the server next to Puma and serves the whole dashboard at `/railwatch`, with no hosted service at all ([Getting started](getting-started.md#embedded-railwatch-server)). |
 | One SQLite database per environment | Railwatch Cloud stores each monitored environment's telemetry in its own database file, which makes retention pruning, backup, and restore per-environment operations. |
 | LLM calls | RubyLLM calls are recorded with tokens, cost, finish reason, tool calls and workflows, in the request or job that made them ([`records.md`](records.md#llm_call)). |
-| An MCP server | With Railwatch Cloud, AI assistants can ask what broke after the last deploy, list slow routes, read an execution's timeline, and search logs ([`ai-and-mcp.md`](ai-and-mcp.md)). |
+| An MCP server | AI assistants can ask what broke after the last deploy, list slow routes, read an execution's timeline, and search logs ([`ai-and-mcp.md`](ai-and-mcp.md)). |
 
 ## See also
 

data/docs/security.md

@@ -3,25 +3,20 @@
 This review covers the open-source gem that runs in a customer's Rails
 application. Railwatch Cloud is a separate service and is outside this review.
 
-## Embedded dashboard
-
-In embedded mode (the installer's default) the gem also serves a dashboard at
-the engine's mount, showing every query, log line and exception the app
-recorded. HTTP Basic authentication is on by default. With no credentials
-configured, every dashboard request is 401 in every environment except
-development, where it is open; the app logs a warning at boot outside
-development, and `railwatch:doctor` reports the gate. Credentials, once set,
-apply in development too. An app that turns Basic off gates pages with its own
-`base_controller_class` or a routes constraint; live updates over Action Cable
-are refused unless Basic, a `dashboard_user` resolver, or `dashboard_open`
-authorizes them. See [Embedded mode](embedded.md#authentication).
-
-The writer socket that web workers hand batches to is created with a 0700
-directory and a 0600 socket, so only the app's own user can connect.
+## Dashboard gate (railwatch-server)
+
+The gem serves no dashboard. With the separate `railwatch-server` gem
+installed, a dashboard showing every query, log line and exception the app
+recorded is proxied at `/railwatch`, and its gate is this gem's settings.
+HTTP Basic authentication is on by default. With no credentials configured,
+every dashboard request is 401 in every environment except development,
+where it is open. Credentials, once set, apply in development too. An app
+that turns Basic off gates the dashboard with its own `base_controller_class`,
+which railwatch-server's proxy controller inherits from. See
+[Configuration](configuration.md#dashboard-gate-railwatch-server).
 
 ## Transport
 
-This applies to a cloud install and to export from an embedded install.
 `Railwatch::Transport::Http` sends gzip NDJSON with `Net::HTTP`. HTTPS explicitly
 sets OpenSSL's `VERIFY_PEER`; a spec pins that setting. The transport does not
 implement redirect handling, so a redirect response is treated as a permanent
@@ -52,8 +47,7 @@ configuration and record specs:
   filtered. `Locals.inspect_value` rescues an `inspect` implementation that
   raises; this behavior is covered by an exception-record spec.
 - `capture_exception_source` is true. Source lines surrounding in-application
-  backtrace frames are recorded, and sent to Railwatch Cloud when the install
-  reports or exports there. Disable it if source context is outside the
+  backtrace frames are recorded and sent to the configured server. Disable it if source context is outside the
   application's telemetry policy.
 
 Log record messages are sent exactly as supplied to `Rails.logger`. Railwatch
@@ -107,8 +101,8 @@ application/deployment secret and must not be committed.
   application-specific credentials and personal data.
 - Keep secrets out of exception messages, log text, source files, tenant ids,
   user resolvers, and custom context.
-- In embedded mode, set dashboard credentials (or your own gate) before
-  deploying; see [Embedded mode](embedded.md#authentication).
+- With railwatch-server, set dashboard credentials (or your own gate) before
+  deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-server).
 - Use HTTPS in production and keep TLS verification enabled.
 - Put a request-body limit at the reverse proxy when the public beacon is
   enabled, and choose a shared cache if rate limits must span processes.

data/docs/self-hosting.md

@@ -1,14 +1,22 @@
 # Self-hosting
 
-This page is for sending telemetry to a Railwatch Cloud you run
-yourself. An [embedded](embedded.md) install keeps everything inside
-your app and needs none of it.
+This page is for sending telemetry to a Railwatch server you run
+yourself instead of Railwatch Cloud.
 
-Railwatch Cloud is a Rails app you can run yourself. The gem doesn't care
-which install it talks to — point it at yours and everything works the
-same.
+The self-hosted server is [railwatch-rs](https://github.com/Rebulk/railwatch-rs)
+(AGPL-3.0): one static binary on SQLite that serves many apps, with the
+same dashboard, alerts, MCP server and JSON API as Railwatch Cloud. Its
+install, configuration, backups and upgrades are documented in its
+[SELF-HOST.md](https://github.com/Rebulk/railwatch-rs/blob/main/docs/SELF-HOST.md).
+The gem doesn't care which server it talks to — point it at yours and
+everything works the same.
 
-## Point the gem at your platform
+For a single app, the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
+gem runs that same server next to Puma and wires this gem to it, with no
+host to set up; see [Getting started](getting-started.md#embedded-railwatch-server).
+The rest of this page is for a server on its own host.
+
+## Point the gem at your server
 
 ```ruby
 # config/initializers/railwatch.rb
@@ -21,22 +29,22 @@ end
 `ingest_url` defaults to `https://railwatch.rebulk.com`, so this is the one
 setting a self-hosted install always needs; everything the gem sends —
 records, ping, deploys — hangs off that host. Pass `--url=` to the
-installer to have it written for you (it implies `--cloud`):
+installer to have it written for you:
 
 ```sh
 bin/rails generate railwatch:install --url=https://telemetry.example.com
 ```
 
-To keep an embedded install and mirror it to your platform, set
-`RAILWATCH_INGEST_URL` and `RAILWATCH_TOKEN` and turn on
-[export](embedded.md#three-ways-to-run-it) instead.
+The railwatch-rs installer prints both values (`RAILWATCH_INGEST_URL`,
+`RAILWATCH_TOKEN`) when it finishes.
 
 ## Getting a token
 
-On your install: sign up, create an application, then create an
-environment inside it (`production`, `staging` — one token each). The
-token is shown once, right after you create the environment; a lost one
-is rotated from the environment's settings, not recovered.
+railwatch-rs prints the first environment's token once, at the end of
+its install. Each further environment (`production`, `staging` — one
+token each) gets its own, created from the dashboard or with
+`sudo railwatch env create <name>`. A token is shown once; a lost one is
+replaced, not recovered.
 
 ```sh
 bin/rails railwatch:token    # prints the URL to create/copy a token
@@ -55,14 +63,8 @@ so it works as a post-deploy smoke test.
 
 ## MCP
 
-Your install serves its own MCP endpoint at `<ingest host>/mcp` —
+Your server serves its own MCP endpoint at `<ingest host>/mcp` —
 `https://telemetry.example.com/mcp` for the example above. It authenticates
 with a per-user API token generated from Settings → Profile, the same
 token the public JSON API at `/api/v1` uses. See
 [`ai-and-mcp.md`](ai-and-mcp.md) for every client's configuration block.
-
-## Running the platform
-
-Railwatch Cloud's backend is not part of this gem repository. Licensed
-self-hosted customers receive separate platform deployment, backup, retention,
-quota, and restore documentation from Rebulk.

data/docs/testing.md

@@ -27,20 +27,12 @@ require "railwatch/minitest"
 ```
 
 Railwatch must be *enabled* in the test environment or every block would look
-empty. An embedded install (`transport = :local`) is enabled with no token. A
-cloud install needs a token present, so set any non-blank `RAILWATCH_TOKEN` for
-the test env. Either way records go to an in-memory transport, never over the
-network or into the telemetry database. If Railwatch is disabled, the matchers
-raise `Railwatch::SpecHelper::Disabled` rather than quietly passing.
-
-An embedded install adds its two databases to the `test` environment too, and
-Rails' schema check refuses to run the suite while their migrations are
-pending. `bin/rails db:test:prepare` does not create them, because they keep no
-schema file; run this once locally and as a CI setup step:
-
-```sh
-RAILS_ENV=test bin/rails db:prepare
-```
+empty, and it is enabled only with a token present: set any non-blank
+`RAILWATCH_TOKEN` for the test env. railwatch-server is off under
+`Rails.env.test` and does not set one for you. Records go to an
+in-memory transport, never over the network, and there is no database to
+prepare. If Railwatch is disabled, the matchers raise
+`Railwatch::SpecHelper::Disabled` rather than quietly passing.
 
 Sampling is forced on for the block, so a fractional `c.sample` in the app's
 test config can't turn an assertion into one that never fires either.

data/docs/troubleshooting.md

@@ -8,29 +8,9 @@ below are keyed to those lines.
 bin/rails railwatch:doctor
 ```
 
-The first lines depend on the transport. An embedded install checks its
-databases, writer and dashboard; a cloud install checks its token and
-ingest host. The task exits non-zero only on the lines marked fatal
-below. Everything else is informational: a `✗` there means a feature
-isn't wired, not that the install is broken.
-
-Embedded (`transport = :local`):
-
-| Doctor line | What a `✗` means |
-|---|---|
-| `export` | Only shown with `export_enabled` on. Export is on and cannot work: no token, no URL, a plain-HTTP URL, or an unsupported policy. Fatal. |
-| `export destination` | The export queue is blocked or deferred; the line gives the reason. `bin/rails railwatch:export:rebind` clears a credential block. |
-| `railwatch database`, `railwatch_telemetry database` | The database is missing from `config/database.yml` for this environment. Fatal. Re-run the install generator. |
-| `railwatch migrations`, `railwatch_telemetry migrations` | Migrations are pending. Fatal. Run `bin/rails db:prepare`. |
-| `telemetry disk` | The telemetry database is not in incremental auto-vacuum, so pruning never shrinks the file. See [Embedded mode](embedded.md#giving-the-disk-back). |
-| `maintenance` | No maintenance tick in the last ten minutes. Expected when the app is stopped: the clock runs in the app's processes, not in rake. |
-| `writer process` | The writer socket is not answering, `plugin :railwatch` is missing from `config/puma.rb`, or the socket path is over Linux's 108-byte limit. Expected when the app is stopped. |
-| `last write` | Shown when the writer answers: nothing written in five minutes. With the app serving traffic, the writer is stuck or workers are not reaching it. |
-| `dashboard access` | HTTP Basic is on with no credentials outside development, so every page is 401; or Basic is off and nothing else is declared. Run `bin/rails railwatch:authentication:configure`, or see [Embedded mode](embedded.md#authentication). |
-| `json compatibility` | The installed `json` gem cannot decode on this Rails; see [below](#binjobs-dies-in-a-loop-with-wrong-number-of-arguments-given-2-expected-1). |
-| `recurring.yml` | `config/recurring.yml` still lists `Railwatch::*` jobs from a pre-release. Remove them. |
-
-Cloud (`transport = :http`):
+The task exits non-zero only on the lines marked fatal below. Everything
+else is informational: a `✗` there means a feature isn't wired, not that
+the install is broken.
 
 | Doctor line | What a `✗` means |
 |---|---|
@@ -39,11 +19,6 @@ Cloud (`transport = :http`):
 | `ingest url` | `ingest_url` isn't a parseable HTTP(S) URL. |
 | `ingest transport security` | The ingest URL is plain HTTP on a non-loopback host without `RAILWATCH_ALLOW_HTTP=true`. |
 | `ingest reachable` | `GET {ingest_url}/ingest/ping` didn't return success. Fatal. The ping carries the token, so a missing or wrong token fails this line too; fix `token` first. |
-
-Both:
-
-| Doctor line | What a `✗` means |
-|---|---|
 | `request middleware` | `Railwatch::Middleware::Request` isn't in the stack, so requests aren't executions. |
 | `engine mounted` | `mount Railwatch::Engine, at: "/railwatch"` is missing from `config/routes.rb`; the browser beacon has nowhere to post. |
 | `deploy` | `config.deploy` is unset — records ship, charts get no deploy markers. |
@@ -64,32 +39,29 @@ app takes.
 Work down this list. Most of it is the same root cause seen from
 different angles: Railwatch decided not to record.
 
-**Embedded: the writer is not writing.** Run `railwatch:doctor` with the
-app serving traffic. `writer process` and `last write` say whether the
-writer is up and when it last wrote; the migrations lines catch a
-database that was never prepared.
-
-**Cloud: the token is missing or blank.** With `transport = :http`,
+**The token is missing or blank.**
 `Railwatch.enabled?` is `config.enabled && token.present?`. With no token
 the engine's `railwatch.subscribe` initializer returns early, so no
 subscribers and no patches are installed at all. Fix: set
 `RAILWATCH_TOKEN`, restart, and re-run `railwatch:doctor`. The `token`
 line prints the first 6 characters and the length, which is enough to
-spot a truncated or quoted value.
+spot a truncated or quoted value. With railwatch-server installed, the
+token is set when the server's data directory is provisioned; its boot
+log line says whether the agent was wired.
 
-**Cloud: the token is wrong.** A 401 from the ingest marks the transport
+**The token is wrong.** A 401 from the ingest marks the transport
 permanently unauthorized: no further flush is attempted for the lifetime
 of that process. Fixing the env var isn't enough. Restart the process.
 `railwatch:doctor`'s `ingest reachable` line catches this before you
 deploy.
 
-**Cloud: `RAILWATCH_INGEST_URL` points somewhere else.** Records go where
+**`RAILWATCH_INGEST_URL` points somewhere else.** Records go where
 you sent them. `railwatch:status` prints the URL it is actually using.
-Compare it against the platform you're looking at. Self-hosting: see
+Compare it against the server you're looking at. Self-hosting: see
 [`self-hosting.md`](self-hosting.md).
 
 **`config.enabled` is false.** `RAILWATCH_ENABLED=0` (or `false`/`no`/`off`)
-turns everything off, embedded or not.
+turns everything off.
 
 **Sample rates are at zero.** `c.sample = { requests: 0.0 }` means no
 request records. So does the per-route `railwatch_never_sample` macro on
@@ -329,13 +301,7 @@ hook below.
 
 **Cause and fix**, in the order the hook itself checks:
 
-- **Embedded: `RAILWATCH_TRANSPORT=local` isn't exported to the hook.**
-  The hook reads the deployer's environment, not your initializer. With
-  that variable set it runs `bin/rails railwatch:deploy[$KAMAL_VERSION]`
-  in the primary container, which writes the marker to the embedded
-  database. Without it, the hook treats the install as a cloud one and
-  exits at the next check, since an embedded install has no token.
-- **Cloud: `RAILWATCH_TOKEN` isn't exported to the hook.** The next thing
+- **`RAILWATCH_TOKEN` isn't exported to the hook.** The first thing
   `.kamal/hooks/post-deploy` does is `[ -z "$RAILWATCH_TOKEN" ] && exit 0`.
   The hook runs on the deployer machine, in your shell, not in a
   container. So a token that only exists in `.kamal/secrets` for the