railwatch 0.1.0 → 0.1.2

data/docs/replacing-sentry.md

@@ -12,12 +12,12 @@ the other.
 
 ## Decide whether Railwatch covers your workload
 
-Nightwatch parity and Sentry parity are different targets. Laravel
-Nightwatch is an application-monitoring product built around framework
-executions; Railwatch deliberately maps that model onto Rails. Sentry is a
-broader, multi-language managed platform with browser replay, native/mobile
-SDKs, a large integration catalog, and generic tracing. Those broader
-capabilities are not implied by Rails/Nightwatch parity.
+Railwatch and Sentry aim at different targets. Railwatch is an
+application-monitoring product built around Rails executions: a request,
+job, scheduled task, command, or channel action and everything it did.
+Sentry is a broader, multi-language managed platform with browser replay,
+native/mobile SDKs, a large integration catalog, and generic tracing.
+Railwatch does not claim those broader capabilities.
 
 | Workload or capability | Status | Boundary |
 |---|---|---|

data/docs/source-maps.md

@@ -54,7 +54,7 @@ them and cannot resolve minified locations accurately.
 
 For a custom release uploader, POST the raw `.map` bytes to
 `/ingest/sourcemaps` with `Content-Type: application/octet-stream`,
-`Authorization: Bearer lt_...`, `X-Railwatch-Deploy`, and
+`Authorization: Bearer rw_...`, `X-Railwatch-Deploy`, and
 `X-Railwatch-Filename` (the generated JavaScript URL path without a leading
 slash). A successful response is HTTP 201 with
 `{"ok":true,"filename":"vite/assets/index-abc.js","bytes":1234}`.

data/docs/testing.md

@@ -2,13 +2,13 @@
 
 Railwatch already watches every query, N+1, span, exception, and outgoing
 request your app makes. The same instrumentation works in your test suite,
-which means a spec can assert on them — and CI can fail a pull request that
+which means a spec can assert on them. CI can fail a pull request that
 adds an N+1 or doubles a page's query count.
 
 ## Set-up
 
-RSpec — add one line to `spec/rails_helper.rb` (the install generator adds it
-for you):
+RSpec: add one line to `spec/rails_helper.rb`. The install generator adds it
+for you.
 
 ```ruby
 require "rspec/rails"
@@ -18,20 +18,17 @@ require "railwatch/rspec"
 That requires `railwatch/spec_helper`, includes `Railwatch::SpecHelper` into every
 example group, and defines the matchers below.
 
-Minitest — the same thing in `test/test_helper.rb`:
+Minitest: the same thing in `test/test_helper.rb`. The require includes
+`Railwatch::Minitest` into `ActiveSupport::TestCase` on its own.
 
 ```ruby
 require "rails/test_help"
 require "railwatch/minitest"
-
-class ActiveSupport::TestCase
-  include Railwatch::Minitest
-end
 ```
 
 Railwatch must be *enabled* in the test environment or every block would look
 empty. `config.enabled?` is true when `config.enabled` is set and a token is
-present, so set any non-blank `RAILWATCH_TOKEN` for the test env — records go to
+present, so set any non-blank `RAILWATCH_TOKEN` for the test env. Records go to
 an in-memory transport, never over the network. If Railwatch is disabled, the
 matchers raise `Railwatch::SpecHelper::Disabled` rather than quietly passing.
 
@@ -50,9 +47,9 @@ expect { user.reload }.to have_railwatch_queries(exactly: 1)
 expect { Report.generate }.to have_railwatch_queries(at_least: 1)
 ```
 
-Exactly one of `at_most:`, `exactly:`, `at_least:` — passing two (or none)
-raises `ArgumentError`. On failure the message lists every statement, each
-truncated to 120 characters, so CI output says what to go and fix:
+Pass exactly one of `at_most:`, `exactly:`, `at_least:`. Passing two, or
+none, raises `ArgumentError`. On failure the message lists every statement,
+each truncated to 120 characters, so CI output says what to go and fix:
 
 ```
 expected the block to run at most 1 database queries, but it ran 3:
@@ -61,7 +58,7 @@ expected the block to run at most 1 database queries, but it ran 3:
   3. SELECT "gadgets".* FROM "gadgets" WHERE "gadgets"."id" = ?
 ```
 
-Cached queries don't count — they never become `query` records.
+Cached queries don't count. They never become `query` records.
 
 ### `have_railwatch_n_plus_one`
 
@@ -88,7 +85,7 @@ expect { importer.run }.to record_railwatch_exception(ArgumentError)
 expect { importer.run }.not_to record_railwatch_exceptions
 ```
 
-These see anything that reaches `Rails.error` — `Rails.error.handle`,
+These see anything that reaches `Rails.error`: `Rails.error.handle`,
 `Rails.error.report`, `Railwatch.report`, and unhandled exceptions a request
 spec's middleware catches. A block that raises out of the matcher still
 raises; nothing is swallowed.
@@ -116,8 +113,8 @@ produces the same statement listing on failure.
 ## Where the matchers work
 
 Anywhere. A request spec's `get "/widgets"` opens and closes its own
-execution, so its whole tree — queries, N+1s, outgoing HTTP — is visible by
-the time the block returns:
+execution. So its whole tree is visible by the time the block returns:
+queries, N+1s, outgoing HTTP.
 
 ```ruby
 expect { get "/widgets" }.to have_railwatch_queries(at_most: 6)
@@ -129,7 +126,7 @@ execution for the duration of the assertion and closed afterwards. No parent
 opened yourself has its records read straight off that execution's buffer.
 
 Under the hood every matcher calls `Railwatch::SpecHelper#railwatch_capture`,
-which is public — use it directly for anything the matchers don't cover:
+which is public. Use it directly for anything the matchers don't cover:
 
 ```ruby
 records = railwatch_capture { get "/widgets" }
@@ -164,12 +161,12 @@ RSpec.describe "performance budgets", type: :request do
 end
 ```
 
-Two ways to run it: tag these examples and run them as their own CI step
-(`bundle exec rspec --tag performance`) so a budget failure is obvious in the
-job list, or leave them in the main suite so any pull request that adds a
+Two ways to run it. Tag these examples and run them as their own CI step
+with `bundle exec rspec --tag performance`, so a budget failure is obvious in
+the job list. Or leave them in the main suite so any pull request that adds a
 query fails immediately. Either way the failure message names the statements,
 so the fix is usually an `includes` one line away.
 
 Seed enough rows in `before` that an N+1 actually crosses
-`config.n_plus_one_threshold` — with three records, a five-query threshold
+`config.n_plus_one_threshold`. With three records, a five-query threshold
 never fires and the gate passes on code that would melt in production.

data/docs/troubleshooting.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Start with `bin/rails railwatch:doctor`. It checks every piece of the
-install in one pass and prints a `✓`/`✗` line per piece; the sections
+install in one pass and prints a `✓`/`✗` line per piece. The sections
 below are keyed to those lines.
 
 ```sh
@@ -9,14 +9,14 @@ bin/rails railwatch:doctor
 ```
 
 The task exits non-zero only when **token** or **ingest reachable**
-fails. Everything else is informational — a `✗` there means a feature
+fails. Everything else is informational. A `✗` there means a feature
 isn't wired, not that the install is broken.
 
 | Doctor line | What a `✗` means |
 |---|---|
 | `token` | `RAILWATCH_TOKEN` is unset or empty. Fatal: nothing is recorded at all. |
 | `ingest url` | `ingest_url` isn't a parseable HTTP(S) URL. |
-| `ingest reachable` | `GET {ingest_url}/ingest/ping` didn't return success. Fatal. |
+| `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. |
 | `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. |
@@ -33,37 +33,38 @@ isn't wired, not that the install is broken.
 **Symptom.** The environment's pages stay empty however much traffic the
 app takes.
 
-Work down this list; the first five are the same root cause seen from
-different angles — Railwatch decided not to record.
+Work down this list. The first five are the same root cause seen from
+different angles: Railwatch decided not to record.
 
 **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 — this is by design, so the gem is inert in
-development. Fix: set `RAILWATCH_TOKEN`, restart, 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).
+patches are installed at all. This is by design, so the gem is inert in
+development. 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.
 
 **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.
+of that process. Fixing the env var isn't enough. Restart the process.
 `railwatch:doctor`'s `ingest reachable` line catches this before you
 deploy.
 
 **`RAILWATCH_INGEST_URL` points somewhere else.** Records go where you sent
-them. `railwatch:status` prints the URL it is actually using; compare it
+them. `railwatch:status` prints the URL it is actually using. Compare it
 against the platform 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 with a valid token present.
 
-**Sample rates are at zero.** `c.sample = { requests: 0.0 }` — or the
-per-route `railwatch_never_sample` macro on a controller — means no
-request records. The `sample rates` doctor line prints the effective
-values. Note that an unhandled exception still ships from a sampled-out
-execution, so "exceptions arrive but nothing else does" is the
-signature of a low sample rate rather than a broken install.
+**Sample rates are at zero.** `c.sample = { requests: 0.0 }` means no
+request records. So does the per-route `railwatch_never_sample` macro on
+a controller. The `sample rates` doctor line prints the effective
+values. Note that an unhandled exception can still ship from a
+sampled-out execution, subject to the `exceptions` rate. So "exceptions
+arrive but nothing else does" is the signature of a low sample rate
+rather than a broken install.
 
 **The record type is ignored.** `c.ignore` drops a type before it is
 built. The `ignored record types` doctor line prints the list. Ignoring
@@ -71,14 +72,50 @@ built. The `ignored record types` doctor line prints the list. Ignoring
 
 **You're looking at the test environment.** Requiring `railwatch/rspec`
 (or `railwatch/minitest`) swaps the reporter's transport for an in-memory
-one, so a suite records normally but never sends anything over the
+one. A suite records normally but never sends anything over the
 network. Independently: the health sampler, the session flusher, and the
 profiler all refuse to start when `Rails.env.test?`.
 
 Still nothing? Set `RAILWATCH_DEBUG=1` and restart. Internal diagnostics go
-to stderr prefixed `[railwatch]` (never to `Rails.logger`, so they can't
-become `log` records about themselves). `Railwatch.on_unrecoverable { |e|
-... }` gets the same failures as a callback.
+to stderr prefixed `[railwatch]`. They never go to `Rails.logger`, so they
+can't become `log` records about themselves. `Railwatch.on_unrecoverable
+{ |e| ... }` gets the same failures as a callback.
+
+## `bin/jobs` dies in a loop with `wrong number of arguments (given 2, expected 1)`
+
+**Symptom.** Every Solid Queue process crashes at boot from
+`json/common.rb` in `parse`, and Railwatch reports the same
+`ArgumentError` from source `application.solid_queue` hundreds of times.
+The web server still answers until it touches a session or a JSON column.
+
+**Cause.** Not Railwatch. `json` 3.0 (September 2026) made `JSON.parse`'s
+options keyword-only, and Active Support up to 8.1.3.1 still passes them
+positionally ([rails/rails#58685](https://github.com/rails/rails/issues/58685)).
+A fresh `rails new` resolves the newest `json`, so a new app hits this
+before Railwatch is even installed.
+
+**Fix.** Pin `json` below 3 until a Rails release includes the fix:
+
+```sh
+bundle add json --version "< 3"
+```
+
+## Deprecations are counted but never listed
+
+**Symptom.** The `deprecations` counter on an execution is non-zero, but
+the Deprecations page stays empty.
+
+**Cause.** Railwatch listens to the `deprecation.rails` notification, and
+Rails only emits it when the app's deprecation behavior includes
+`:notify`. The default in development is `:log` and in production
+`:silence`, neither of which notifies.
+
+**Fix.** Add `:notify` alongside whatever the environment already does:
+
+```ruby
+# config/environments/production.rb
+config.active_support.deprecation = [:silence, :notify]
+```
 
 ## Doubled scheduled_task records
 
@@ -86,16 +123,16 @@ become `log` records about themselves). `Railwatch.on_unrecoverable { |e|
 page, at the same minute, usually with different `drift`.
 
 **Cause.** Two Solid Queue supervisors are running against the same
-queue database — a stale `bin/jobs` left over from a previous `bin/dev`,
-`SOLID_QUEUE_IN_PUMA=true` while a dedicated job role is also booted, or
-two containers of the job role. Each supervisor has its own recurring
-scheduler and its own workers, so the job really is performed twice.
-Railwatch doesn't dedupe: it records one `scheduled_task` per
-`perform.active_job`, in whichever process performed it. The doubled
-rows are a true report of a doubled run.
+queue database. That could be a stale `bin/jobs` left over from a
+previous `bin/dev`, `SOLID_QUEUE_IN_PUMA=true` while a dedicated job role
+is also booted, or two containers of the job role. Each supervisor has
+its own recurring scheduler and its own workers, so the job really is
+performed twice. Railwatch doesn't dedupe: it records one
+`scheduled_task` per `perform.active_job`, in whichever process performed
+it. The doubled rows are a true report of a doubled run.
 
 **Fix.** Run one supervisor. `SolidQueue::Process.where(kind:
-"Supervisor")` tells you how many think they're alive; `bin/kamal app
+"Supervisor")` tells you how many think they're alive. `bin/kamal app
 logs -r job` tells you which containers are booting one. The same
 duplication also doubles the work itself, so this is worth fixing
 regardless of what the dashboard says.
@@ -111,9 +148,8 @@ fine.
 the real class never runs.
 
 **Fix.** Re-prepend the patch onto the replacement, once, before the
-suite. This is exactly what the gem's own suite does
-(`spec/spec_helper.rb`), and app suites using WebMock should do the
-same:
+suite. This is exactly what the gem's own suite does, in
+`spec/spec_helper.rb`. App suites using WebMock should do the same:
 
 ```ruby
 # WebMock replaces ::Net::HTTP with a subclass whose #request short-circuits
@@ -132,35 +168,35 @@ end
 have workers.
 
 **What actually happens.** Ruby routes `fork`, `Process.fork`, and
-`Kernel#fork` through `Process._fork`, and Railwatch registers one callback
-with Rails' own `ActiveSupport::ForkTracker` (the same hook Active Record
-uses to reset its connection pools). Before the child returns from
+`Kernel#fork` through `Process._fork`. Railwatch registers one callback
+with Rails' own `ActiveSupport::ForkTracker`, the same hook Active Record
+uses to reset its connection pools. Before the child returns from
 `fork`, it replaces the inherited reporter buffer, drop accounting,
 transport policy state, mutexes, condition variables, dead threads, and the
-profiler's process-global state (a parent's in-flight profile would
-otherwise leave the child permanently unable to profile).
+profiler's process-global state. A parent's in-flight profile would
+otherwise leave the child permanently unable to profile.
 The parent's half-finished session map is discarded too. The child then
 emits its own `process` record and starts fresh health/session threads for
-its role. Parent records remain owned by and delivered from the parent;
-they can never be replayed by every child. **No `on_worker_boot`
+its role. Parent records remain owned by and delivered from the parent.
+They can never be replayed by every child. **No `on_worker_boot`
 configuration is needed**, in Puma cluster mode or in Solid Queue's
 forked workers.
 
 The synchronization objects are replaced without locking them. That is
-deliberate: if another parent thread owned a mutex at the instant of
+deliberate. If another parent thread owned a mutex at the instant of
 `fork`, Ruby preserves the locked mutex in the child but not the thread
 that could unlock it.
 
 **When a process legitimately reports nothing.** `Health.start!` returns
 early unless the process's role is `web` or `worker`, and
 `Sessions.start!` only runs for `web`. Role detection is
-`Railwatch::Subscribers::ProcessInfo.role`, in this order: `worker` when
-Solid Queue is loaded and `$PROGRAM_NAME` includes `"jobs"` (or the
-command starts with `solid_queue:`), then `console`, then `command` when
-`$PROGRAM_NAME` ends in `rake`, then `web` when Puma is defined, else
-`process`. The worker check comes first deliberately — Puma is loaded in
-a job container too. A console or a rake task ships no health records by
-design, and both modules also return early in the `test` env.
+`Railwatch::Subscribers::ProcessInfo.role`, in this order. First `worker`,
+when Solid Queue is loaded and `$PROGRAM_NAME` includes `"jobs"` (or the
+command starts with `solid_queue:`). Then `console`. Then `command`, when
+`$PROGRAM_NAME` ends in `rake`. Then `web`, when Puma is defined. Else
+`process`. The worker check comes first deliberately, because Puma is
+loaded in a job container too. A console or a rake task ships no health
+records by design, and both modules also return early in the `test` env.
 
 ## Memory growth with tail sampling on
 
@@ -169,68 +205,71 @@ design, and both modules also return early in the `test` env.
 
 **Cause.** That is the trade-off, not a leak. With head sampling only, a
 sampled-out execution builds and buffers nothing. With tail sampling on,
-*every* execution buffers its child records — queries, cache events,
-logs, view renders — for its whole lifetime, because the keep-or-discard
-decision can't be made until it ends.
+*every* execution buffers its child records for its whole lifetime:
+queries, cache events, logs, view renders. The keep-or-discard decision
+can't be made until it ends.
 
 **What to check.**
 
 - Per execution, the buffer is capped at `Execution::MAX_RECORDS`
-  (10,000). Past that, records are dropped and counted, and the count is
+  (10,000). Past that, records are dropped and counted. The count is
   added to the reporter's drop counter so the loss is visible on the
   platform rather than silent.
 - `c.buffer_size` (default 10,000, the same as `MAX_RECORDS`) caps the
   process-wide queue between the app and the reporter thread.
-  Oldest-dropped-first, also counted. Do not set it below `MAX_RECORDS`:
-  an execution's tree is written to the queue in one go when it ends, so
-  a tree larger than the queue loses its own first records -- typically
-  the outgoing requests a long job made before it started writing.
-  Keeping far more executions than before means far more records
-  arriving at this queue; raise it, or lower what you keep.
-- `c.profile_slow_ms` compounds it: it profiles every tail-buffering
+  Oldest-dropped-first, also counted. Do not set it below `MAX_RECORDS`.
+  An execution's tree is written to the queue in one go when it ends, so
+  a tree larger than the queue loses its own first records. Typically
+  those are the outgoing requests a long job made before it started
+  writing. Keeping far more executions than before means far more
+  records arriving at this queue. Raise it, or lower what you keep.
+- `c.profile_slow_ms` compounds it. It profiles every tail-buffering
   execution from its first line and throws away the fast ones, so the
   profiler's stack table is held alongside the record buffer.
 - `c.failure_context` buffers sampled-out executions too, but a ring of
   that many records each rather than all of them. If RSS climbed after
-  setting it, lower the count: it is a per-execution bound, so the
+  setting it, lower the count. It is a per-execution bound, so the
   process-wide cost is that many records times the executions running
   concurrently.
 
-**Fix.** Lower `tail_sample_slow_ms` so fewer executions qualify to be
-buffered, drop the highest-volume child types for tail-kept traffic with
-`c.ignore`, or use `Railwatch.keep!` on the specific paths you care about
-instead of a global threshold.
+**Fix.** The threshold decides what is kept, not what is buffered:
+with tail sampling on, every execution buffers until it ends, so
+lowering `tail_sample_slow_ms` keeps more trees rather than fewer. To
+buffer less, turn tail sampling off and use `Railwatch.keep!` on the
+specific paths you care about, or drop the highest-volume child types
+with `c.ignore` so they are never buffered.
 
 ## Profiles never appear
 
 **Symptom.** `c.profile_sample` is set but no `profile` records ship and
 no request is marked `profiled`.
 
-**Cause.** No profiler backend is installed. Railwatch doesn't vendor one:
+**Cause.** No profiler backend is installed. Railwatch doesn't vendor one.
 `Railwatch::Profiler.available?` is false unless `vernier` or `stackprof`
 loads, and every profiling setting is inert while it is. The doctor's
 `profiler backend` line reports this.
 
 **Fix.** Add `gem "vernier"` (Ruby ≥ 3.2, preferred) or
 `gem "stackprof"`. Two other reasons a profile can be absent even with a
-backend: `c.profiler` pinned to a name that doesn't load (profiling
-stays off rather than falling back), and the `test` env, where profiling
-is skipped unless `profile_sample` is explicitly non-zero. Both backends
-are process-global, so an execution that starts while another one is
-being profiled is simply not profiled — expected, not a bug.
+backend. One is `c.profiler` pinned to a name that doesn't load; profiling
+stays off rather than falling back. The other is the `test` env, where
+profiling is skipped unless `profile_sample` is explicitly non-zero. Both
+backends are process-global, so an execution that starts while another
+one is being profiled is simply not profiled. That is expected, not a
+bug.
 
 ## No deploy marker on the charts
 
 **Symptom.** Charts have no vertical deploy lines; the Releases page
 groups everything under one blank release.
 
-**Cause.** `config.deploy` is unset. The doctor's `deploy` line says so,
-and when it is set, names the environment variable, `REVISION`, Git checkout,
-or initializer it came from.
+**Cause.** `config.deploy` is unset. The doctor's `deploy` line says so.
+When it is set, the line names the environment variable, `REVISION`, Git
+checkout, or initializer it came from.
 
 **Fix.** Set one of them; they are read in this order:
 
-1. `RAILWATCH_DEPLOY` — the explicit override on any platform.
+1. `RAILWATCH_DEPLOY`, the explicit override on any platform.
 2. `KAMAL_VERSION`.
 3. `GIT_REV`, `GIT_SHA`, `SOURCE_VERSION`, `HEROKU_SLUG_COMMIT`,
    `RENDER_GIT_COMMIT`, the tag from `FLY_IMAGE_REF`,
@@ -243,8 +282,8 @@ Full 40-character SHAs are shortened to 12 characters. Or assign `deploy` in
 the initializer. Set `detect_deploy`/`RAILWATCH_DETECT_DEPLOY` to false to ignore
 steps 3–5. The value is stamped on every record, so a change only affects
 records shipped after the restart. Note that
-`config.deploy` and the deploy *marker* are two different things: the
-marker (with its commit list) comes from `railwatch:deploy` or the Kamal
+`config.deploy` and the deploy *marker* are two different things. The
+marker, with its commit list, comes from `railwatch:deploy` or the Kamal
 hook below.
 
 ## The Kamal hook doesn't fire
@@ -255,14 +294,14 @@ hook below.
 
 - **`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
-  *app* isn't necessarily in the deployer's environment. Export it there
-  (or source the same secret store your CI uses).
+  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
+  *app* isn't necessarily in the deployer's environment. Export it there,
+  or source the same secret store your CI uses.
 - **`curl` or `ruby` isn't on the deployer, or `RAILWATCH_INGEST_URL`
   isn't set.** Then the hook falls back to
   `bin/kamal app exec --primary --reuse "bin/rails railwatch:deploy[$KAMAL_VERSION]"`,
-  which records the same deploy **minus the commit list** — a container
+  which records the same deploy **minus the commit list**. A container
   has the code but not the git history. If your deploys show up without
   commits, this is the path you're on.
 - **The hook isn't there.** The install generator only writes it when
@@ -278,8 +317,8 @@ it exits 0 regardless.
 fewer lines and highlights nothing.
 
 **Cause.** Full-text search uses SQLite's FTS5 (`logs_fts`). The
-platform checks for both — a SQLite adapter *and* the `logs_fts` table —
-and when either is absent falls back to `message LIKE '%...%'`. That
+platform checks for both a SQLite adapter *and* the `logs_fts` table.
+When either is absent it falls back to `message LIKE '%...%'`. That
 fallback is a plain substring match: no phrase or negation syntax, and no
 snippet highlighting.
 
@@ -294,11 +333,11 @@ self-hosted platform operator should rebuild the documented search index.
 **Symptom.** Every other page has data; Tenants shows nothing.
 
 **Cause.** `tenant` is a column on every telemetry row, filled from
-`Railwatch::Context.current_tenant`, and a tenant only exists as a GROUP BY
+`Railwatch::Context.current_tenant`. A tenant only exists as a GROUP BY
 over those rows. If nothing ever sets it, every row has a null tenant and
 there is nothing to group.
 
-**Fix.** Apps on `activerecord-tenanted` get it free — Railwatch reads
+**Fix.** Apps on `activerecord-tenanted` get it free. Railwatch reads
 `ActiveRecord::Base.current_tenant` / `TenantRecord.current_tenant` with
 no configuration. Everyone else sets it explicitly, as early in the
 request as the tenant is known:
@@ -313,7 +352,7 @@ does not retroactively apply to it.
 
 ## See also
 
-- [`configuration.md`](configuration.md) — every option and its default.
-- [`records.md`](records.md) — what each record type contains.
-- [`faq.md`](faq.md) — overhead, retention, PII, and what happens when
+- [`configuration.md`](configuration.md): every option and its default.
+- [`records.md`](records.md): what each record type contains.
+- [`faq.md`](faq.md): overhead, retention, PII, and what happens when
   the platform is unreachable.

data/lib/railwatch/minitest.rb

@@ -7,10 +7,9 @@ module Railwatch
   # assert_/refute_. Add to test/test_helper.rb:
   #
   #   require "railwatch/minitest"
-  #   class ActiveSupport::TestCase
-  #     include Railwatch::Minitest
-  #   end
   #
+  # That includes the module into ActiveSupport::TestCase (through its load
+  # hook, so the require order against rails/test_help does not matter).
   # Includes Railwatch::SpecHelper, so `railwatch_records(:query)` is available
   # too. See docs/testing.md.
   module Minitest
@@ -41,3 +40,5 @@ module Railwatch
     end
   end
 end
+
+ActiveSupport.on_load(:active_support_test_case) { include Railwatch::Minitest } if defined?(ActiveSupport.on_load)

data/lib/railwatch/secret_safety.rb

@@ -6,7 +6,9 @@ module Railwatch
   # Read-only Git checks used by the installer and doctor. Tokens are never
   # returned in diagnostics: callers get a path or a short prefix only.
   module SecretSafety
-    TOKEN_PATTERN = /\blt_[A-Za-z0-9_-]{6,}\b/
+    # rw_ is the ingest token prefix; lt_ was the prefix before 0.1.1 and is
+    # still matched so a token minted earlier is still caught in a tracked file.
+    TOKEN_PATTERN = /\b(?:rw|lt)_[A-Za-z0-9_-]{6,}\b/
     TOKEN_FILE_GLOBS = [ ".env", ".env.*", ".kamal/secrets", "config/deploy.yml",
                          "config/initializers/*.rb" ].freeze
 

data/lib/railwatch/subscribers/exceptions.rb

@@ -87,6 +87,13 @@ module Railwatch
       def capture(error, handled:, severity:, context: {}, source: nil, fingerprint: nil)
         return unless Railwatch.enabled?
         return if ignored?(error)
+        # Solid Queue re-raises a failed job's error out of the worker thread,
+        # where its executor reports it to Rails.error a second time
+        # (source application.solid_queue) after the job_attempt execution
+        # has already finished and reported it. The execution's own
+        # first_exception_report? bookkeeping is gone by then, so the error
+        # object itself remembers that its unhandled report has shipped.
+        return if !handled && reported_unhandled?(error)
 
         exe = execution
         if exe&.first_exception_observation?(error, handled)
@@ -151,9 +158,22 @@ module Railwatch
           # children (Railwatch.tail_keep?).
           exe.exception_reported = true if exe
           Railwatch.record_now(:exception, group: group, **rec)
+          remember_reported(error)
         end
       end
 
+      def reported_unhandled?(error)
+        error.instance_variable_defined?(:@__railwatch_reported)
+      rescue StandardError
+        false
+      end
+
+      def remember_reported(error)
+        error.instance_variable_set(:@__railwatch_reported, true)
+      rescue StandardError
+        nil
+      end
+
       # The group hash `capture` would assign this error. Public so
       # Railwatch.attach can file an attachment against the same issue without
       # having to re-derive the bucketing rule (source snippets are skipped:

data/lib/railwatch/subscribers/process_info.rb

@@ -84,9 +84,12 @@ module Railwatch
 
       # Puma is loaded in every process of an app that bundles it, so a Solid
       # Queue worker is recognised first, by how it was started (bin/jobs or
-      # `rake solid_queue:start`).
+      # `rake solid_queue:start`) or by the procline Solid Queue gives every
+      # process it forks ("solid-queue-worker(1.7.0): ..."), which replaces
+      # $PROGRAM_NAME after boot and would otherwise turn the supervisor,
+      # dispatcher, and scheduler into "web" on every health sample.
       def role
-        if defined?(::SolidQueue) && ($PROGRAM_NAME.include?("jobs") || ARGV.first.to_s.start_with?("solid_queue:")) then "worker"
+        if defined?(::SolidQueue) && ($PROGRAM_NAME.include?("jobs") || $PROGRAM_NAME.start_with?("solid-queue-") || ARGV.first.to_s.start_with?("solid_queue:")) then "worker"
         elsif defined?(::Rails::Console) then "console"
         elsif $PROGRAM_NAME.end_with?("rake") then "command"
         elsif defined?(::Puma) then "web"

data/lib/railwatch/version.rb

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

data/lib/tasks/railwatch_tasks.rake

@@ -186,11 +186,11 @@ namespace :railwatch do
 
       1. Sign in (or sign up) at #{base.url("/dashboard")}
       2. New application, then New environment (production, staging, ...)
-      3. The environment's token (lt_...) is shown once, right after it is created.
+      3. The environment's token (rw_...) is shown once, right after it is created.
 
       Then set it where this app reads its environment:
 
-        RAILWATCH_TOKEN=lt_...#{"\n  RAILWATCH_INGEST_URL=#{base.host_url}" if base.self_hosted?}
+        RAILWATCH_TOKEN=rw_...#{"\n  RAILWATCH_INGEST_URL=#{base.host_url}" if base.self_hosted?}
 
       With Kamal:  bin/rails generate railwatch:install --prompt-token --kamal-secrets
       Verify:      bin/rails railwatch:doctor
@@ -204,12 +204,12 @@ namespace :railwatch do
   task mcp: :environment do
     base = Railwatch::Endpoints.new(Railwatch.config)
     mcp = base.url("/mcp")
-    token = "lnt_your_token_here"
+    token = "rwp_your_token_here"
     puts <<~TEXT
       Railwatch MCP server: #{mcp}
 
       An MCP token is per person, not per app: Settings -> Profile -> "API & MCP
-      token" at #{base.url("/settings/profile")}. It starts with lnt_ and is
+      token" at #{base.url("/settings/profile")}. It starts with rwp_ and is
       shown once. Everything below is scoped to whatever accounts that user
       belongs to.