railwatch 1.5.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: fd59ae7a65fbd673b2069d096802144c04277a08379fa42285d32677ad5502c6
4
- data.tar.gz: 49ff48d1ec8340609c23c12a117ae1e381ac938f7fbdfb6aa914b7e33505a25c
3
+ metadata.gz: 0d8b4beb4f3c9b09c993613dec68aed93c246f1e2a5b94bdea9419ca6114e816
4
+ data.tar.gz: cc362cca02b6088d47b19b98c2308a808df074345b30171715d65e945410dccb
5
5
  SHA512:
6
- metadata.gz: 9c45c3639f2787b16b9104afed286ff712bfb63028e13fd83eda44323544ddb9a156c60566287d5465d6daaeffb46b4a8379addb8a51ebf90ab178f9c17a41d4
7
- data.tar.gz: 31fe3a1492400bf823ef7dbd04ee22a45edda63349168032b93a3f8e429525cf9cb205b15b96eb6238819a6386916457a75ed3f4de52164227c39e39c8a1a576
6
+ metadata.gz: 238763021bae762a9d689b05484f8b62f9a204113c605639b328effc2153a43ed6c03eb44c58326293001481654738f958c256efa4ed805f5f1f20b5f5e3bf27
7
+ data.tar.gz: ce8b885961ee5f2bc7c2f3c2b057ee970a0a92a7b2e2f86727fb736b79e6278594702490a19b8103ab31bd061e4b250523c99805c1af1c393443019e490b400a
data/AGENTS.md CHANGED
@@ -5,9 +5,9 @@ this into that application's repository. Index of everything else:
5
5
  [`llms.txt`](llms.txt).
6
6
 
7
7
  Railwatch instruments a Rails app end to end and sends linked telemetry over
8
- HTTPS to a Railwatch server: Railwatch Cloud (`https://railwatch.rebulk.com`,
8
+ HTTPS to a Railwatch server: Railwatch Cloud (`https://app.railwatch.dev`,
9
9
  the default), a self-hosted [railwatch-rs](https://github.com/Rebulk/railwatch-rs),
10
- or the one the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
10
+ or the one the [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar)
11
11
  gem runs next to Puma. Every request, job attempt, scheduled task run, and command is
12
12
  an **execution**; every query, cache read, log line, outgoing HTTP call, LLM
13
13
  call, view render, exception, and span is a child of one, linked by
@@ -32,7 +32,7 @@ inert. Configuration lives only in that initializer; every option also has a
32
32
  `RAILWATCH_*` environment variable.
33
33
 
34
34
  Embedded (the dashboard inside the app, no token to manage): add
35
- `gem "railwatch-server"` to the Gemfile and `plugin :railwatch_server` to
35
+ `gem "railwatch-sidecar"` to the Gemfile and `plugin :railwatch_sidecar` to
36
36
  `config/puma.rb`. It provisions `storage/railwatch/<env>` on first boot and
37
37
  points this agent at it. Its dashboard at `/railwatch` is gated by this gem's
38
38
  `http_basic_auth_*` settings (open in development, 401 elsewhere until
@@ -41,14 +41,14 @@ password) or, with Basic off, by `c.base_controller_class`.
41
41
 
42
42
  Railwatch 0.x's in-gem embedded mode (`c.transport = :local`, `plugin :railwatch`,
43
43
  the `railwatch`/`railwatch_telemetry` databases) is gone in 1.0; remove all three
44
- and add railwatch-server. Its old SQLite files are not migrated.
44
+ and add railwatch-sidecar. Its old SQLite files are not migrated.
45
45
 
46
46
  ## Rake tasks
47
47
 
48
48
  | Task | Does |
49
49
  |---|---|
50
50
  | `bin/rails railwatch:doctor` | ✓/✗ per check: token, token storage, ingest URL, reachability, middleware, engine mount, deploy, sample rates, ignored types, Kamal hook, browser client and whether an entrypoint calls it, profiler backend, test matchers. Exits non-zero on a missing or tracked token, or an unreachable host. **Run this first when telemetry is missing.** |
51
- | `bin/rails railwatch:authentication:configure` | Sets the HTTP Basic credentials that gate railwatch-server's dashboard, for the current `RAILS_ENV`. |
51
+ | `bin/rails railwatch:authentication:configure` | Sets the HTTP Basic credentials that gate railwatch-sidecar's dashboard, for the current `RAILS_ENV`. |
52
52
  | `bin/rails railwatch:token` | Where to create an ingest token for this app on the server `ingest_url` points at. |
53
53
  | `bin/rails railwatch:mcp` | Paste-ready MCP client configuration for that server. |
54
54
  | `bin/rails railwatch:deploy[ref,name,url]` | Records a deploy marker on the server. Use as a release step when not deploying with Kamal. |
@@ -93,7 +93,7 @@ Per action, in a controller class body: `railwatch_sample 0.01, only: :index`,
93
93
 
94
94
  `require "railwatch/rspec"` in `spec/rails_helper.rb` (or `"railwatch/minitest"` in
95
95
  `test/test_helper.rb`). Railwatch must be enabled in the test env, which
96
- needs any non-blank `RAILWATCH_TOKEN` there (railwatch-server is off in test
96
+ needs any non-blank `RAILWATCH_TOKEN` there (railwatch-sidecar is off in test
97
97
  and does not set one). Records
98
98
  go to an in-memory transport, never over the wire. All matchers are block
99
99
  matchers.
@@ -121,15 +121,15 @@ melt in production.
121
121
  ## MCP
122
122
 
123
123
  Railwatch Cloud and railwatch-rs are MCP servers at `<ingest host>/mcp`
124
- (with railwatch-server: the app's host plus `/railwatch/mcp`).
124
+ (with railwatch-sidecar: the app's host plus `/railwatch/mcp`).
125
125
  Generate a personal token at Settings → Profile → "API & MCP token", then:
126
126
 
127
127
  ```sh
128
- claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
128
+ claude mcp add railwatch --transport http https://app.railwatch.dev/mcp \
129
129
  --header "Authorization: Bearer rwp_your_token_here"
130
130
  ```
131
131
 
132
- In development with railwatch-server no token is needed from the same
132
+ In development with railwatch-sidecar no token is needed from the same
133
133
  machine: `claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp`,
134
134
  or `bin/rails generate railwatch:agents` to write `.mcp.json`, a marked
135
135
  block in `AGENTS.md`/`CLAUDE.md` and a Claude Code skill. Development
data/CHANGELOG.md CHANGED
@@ -6,6 +6,113 @@
6
6
  filled in by the release commit, which is also the only commit that
7
7
  touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
8
8
 
9
+ ## 1.6.1 (2026-11-18)
10
+
11
+ - Security fixes from the 2026-11 review:
12
+ - **Browser URLs no longer carry query strings or fragments.** Reset,
13
+ magic-link and OAuth links put their secret there. The beacon now
14
+ stores only the path of a visit's `url`, an error's page `url` and
15
+ `visit`, and each navigation breadcrumb, the way server-side request
16
+ records always have; URL userinfo is dropped too. An app that wants
17
+ queries opts in on both sides: `c.capture_browser_query_strings = true`
18
+ (`RAILWATCH_CAPTURE_BROWSER_QUERY_STRINGS`) and
19
+ `startRailwatch({ captureQueryStrings: true })`.
20
+ - **Console breadcrumbs keep only the level** (`error`/`warn`), not what
21
+ was logged; opt in with `c.capture_browser_console_arguments = true`
22
+ and `startRailwatch({ captureConsoleArguments: true })`. A click
23
+ breadcrumb quotes at most 32 characters of the element's text (was 80).
24
+ - The server applies all of this to every beacon, so an app still running
25
+ an older copy of the browser client is covered as soon as it upgrades
26
+ the gem. The client file itself is copied into the app and is not
27
+ updated by `bundle update`: take the new one with
28
+ `bin/rails generate railwatch:install --force --no-doctor` (or copy
29
+ `Railwatch.browser_client_path` over `lib/railwatch.ts`), so the
30
+ browser stops sending queries in the first place.
31
+ - **The beacon's tenant hint must be signed.** The beacon takes no
32
+ credential, so anyone could file browser errors and session events
33
+ under any tenant. `startRailwatch({ tenant })` must now return
34
+ `Railwatch.beacon_tenant_hint(tenant)`, rendered into the page by the
35
+ server (for example in a `<meta>` tag); a bare tenant name is ignored
36
+ and the records carry no tenant. A tenant the server resolves for
37
+ itself still wins. **Breaking** for apps that derived the tenant in
38
+ the browser.
39
+ - **railwatch-sidecar's default dashboard role is `member`**, not
40
+ `admin`, for a visitor the app did not name (the HTTP Basic user or the
41
+ single operator): `c.dashboard_default_role`
42
+ (`RAILWATCH_DASHBOARD_DEFAULT_ROLE`), `"admin"` restores the old
43
+ behaviour. Takes effect with a railwatch-sidecar release that reads it.
44
+ - New `Railwatch.config.dashboard_gate_configured?`: false when HTTP Basic
45
+ is off and `base_controller_class` is still `ActionController::Base`,
46
+ which leaves the dashboard open to anyone. railwatch-sidecar uses it to
47
+ refuse to serve the dashboard outside development in that configuration.
48
+ - More headers are masked by default: `X-Forwarded-Email`,
49
+ `X-Forwarded-User`, `X-Remote-User`, `X-Client-Cert`,
50
+ `X-Forwarded-Client-Cert`, `Ocp-Apim-Subscription-Key`, `X-Session-Id`,
51
+ `X-Password` (any name with a `password`, `session-id`,
52
+ `subscription-key`, `client-cert`, or forwarded/remote user or email
53
+ segment).
54
+ - SQL from a connection whose adapter is unknown (or reported as empty)
55
+ could leave literals in the normalized statement:
56
+ `path = 'C:\' AND ssn = '123-45-6789' AND email = 'a@b.com'` kept
57
+ `a@b.com`. When the two backslash readings disagree on where a quoted
58
+ value ends, the rest of the statement is now masked.
59
+ - The generated Kamal `post-deploy` hook passes the ingest token to curl
60
+ on stdin instead of its command line, where `ps` showed it. Existing
61
+ hooks are not rewritten: regenerate with
62
+ `bin/rails generate railwatch:install --force --no-doctor`, or change
63
+ `-H "Authorization: Bearer $RAILWATCH_TOKEN"` to
64
+ `printf 'Authorization: Bearer %s\n' "$RAILWATCH_TOKEN" | curl ... -H @-`.
65
+
66
+ - Railwatch Cloud moved to **app.railwatch.dev**: it is the default
67
+ `ingest_url` now (was railwatch.rebulk.com, which still accepts
68
+ telemetry and redirects its pages). An app with `RAILWATCH_INGEST_URL`
69
+ set is unaffected. `railwatch:token` treats both names as the hosted
70
+ platform.
71
+ - The gem that runs the dashboard inside an app is **railwatch-sidecar**
72
+ (renamed from railwatch-server; the old name still works there). Messages,
73
+ generators and docs say `gem "railwatch-sidecar"` and
74
+ `plugin :railwatch_sidecar`; the agents generator reads the mount path from
75
+ `Railwatch::Sidecar` or the older `Railwatch::Server`.
76
+
77
+ - An app upgrading from 0.x embedded mode is told how to move instead of
78
+ failing obscurely. The Ruby dashboard and its storage stay retired: the
79
+ dashboard is railwatch-server (the railwatch-rs engine next to Puma) or
80
+ a railwatch-rs server, the one Railwatch engine.
81
+ - Assigning a removed setting (`transport`, `issue_prefix`,
82
+ `repository_url`, `retention_days`, `dashboard_user`,
83
+ `dashboard_open`, `writer_socket`, `migration_busy_timeout`) raises
84
+ `Railwatch::Configuration::RemovedSetting` (a `NoMethodError`) that
85
+ names the setting and links the migration. Before, this was a bare
86
+ `undefined method 'transport='`.
87
+ - `plugin :railwatch` in `config/puma.rb` stops boot with the same
88
+ migration instead of Puma's `Unable to find plugin: railwatch`.
89
+ - A leftover `RAILWATCH_TRANSPORT` logs one warning at boot that it is
90
+ ignored.
91
+
92
+ ## 1.6.0 (2026-10-29)
93
+
94
+ - An IPv6 address in an exception message is masked like an IPv4 one, so
95
+ "scrape trap followed from 2607:fb90:..." groups with "...from
96
+ 40.77.167.14" instead of opening an issue per address. Full and
97
+ `::`-compressed forms are both covered. A clock time (`12:30:45`) and a
98
+ constant path (`Foo::Bar`) are left alone.
99
+ - A browser error in a content-hashed bundle (`vite/assets/dist-DedfDSJv.js`)
100
+ is fingerprinted on the name without the hash (`vite/assets/dist.js`)
101
+ and without the line, so the same error no longer opens a new issue
102
+ every deploy. In a minified bundle the line moves with any change
103
+ before it. The stored frames keep the real file and line.
104
+ - The browser client ignores "Script error." by default. It is all a
105
+ browser reports for an error in a cross-origin script, with no stack.
106
+ - A file `ActionDispatch::Static` serves from `public/` (a 2xx or 304 for
107
+ a GET or HEAD no route matched) is no longer recorded as a `GET
108
+ unmatched` request, nor counted in its session. In rebulk-system that
109
+ was 3,168 of 36,131 requests a day and about 23 journey rows per page
110
+ load. Unmatched 404s are still recorded. Routed requests never touch
111
+ the filesystem for this.
112
+ - `startRailwatch()` does nothing when there is no `window`, so an
113
+ Inertia SSR entrypoint that calls it at its top level no longer crashes
114
+ with "document is not defined".
115
+
9
116
  ## 1.5.0 (2026-10-28)
10
117
 
11
118
  - The browser session is one per browser, shared by every tab, as in GA4
data/README.md CHANGED
@@ -10,10 +10,10 @@ The gem is the agent. It sends what it records over HTTPS to a
10
10
  Railwatch server, which stores it, groups exceptions into issues, sends
11
11
  alerts, and serves the dashboard and an MCP server:
12
12
 
13
- - **Railwatch Cloud** at <https://railwatch.rebulk.com>, the default.
13
+ - **Railwatch Cloud** at <https://app.railwatch.dev>, the default.
14
14
  - **Self-hosted [railwatch-rs](https://github.com/Rebulk/railwatch-rs)**,
15
15
  one static binary for many apps ([Self-hosting](docs/self-hosting.md)).
16
- - **Embedded**: the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
16
+ - **Embedded**: the [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar)
17
17
  gem runs that server next to Puma for one app and serves the dashboard
18
18
  at `/railwatch`, with nothing else to run.
19
19
 
@@ -37,18 +37,18 @@ gem "railwatch", github: "Rebulk/railwatch"
37
37
 
38
38
  ### Embedded
39
39
 
40
- To keep everything inside the app, add `railwatch-server` next to this
40
+ To keep everything inside the app, add `railwatch-sidecar` next to this
41
41
  gem:
42
42
 
43
43
  ```ruby
44
44
  # Gemfile
45
45
  gem "railwatch"
46
- gem "railwatch-server"
46
+ gem "railwatch-sidecar"
47
47
  ```
48
48
 
49
49
  ```ruby
50
50
  # config/puma.rb
51
- plugin :railwatch_server
51
+ plugin :railwatch_sidecar
52
52
  ```
53
53
 
54
54
  It provisions its data under `storage/railwatch/<env>` on first boot and
@@ -57,9 +57,9 @@ points this gem at it, so there is no token to manage. The dashboard at
57
57
  give it a password with
58
58
  `RAILS_ENV=production bin/rails railwatch:authentication:configure`, or
59
59
  put it behind your own admin authentication
60
- ([Configuration](docs/configuration.md#dashboard-gate-railwatch-server)).
60
+ ([Configuration](docs/configuration.md#dashboard-gate-railwatch-sidecar)).
61
61
  Everything else is in the
62
- [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
62
+ [railwatch-sidecar README](https://github.com/Rebulk/railwatch-sidecar#readme).
63
63
 
64
64
  Railwatch 0.x kept embedded telemetry in two SQLite databases written by
65
65
  `plugin :railwatch`. 1.0 removes that mode; see
@@ -107,7 +107,7 @@ expect { get "/widgets" }.not_to have_railwatch_n_plus_one
107
107
  ## Documentation
108
108
 
109
109
  - [Getting started](docs/getting-started.md) — the install and its token,
110
- embedded with railwatch-server, moving from 0.x embedded mode, the three
110
+ embedded with railwatch-sidecar, moving from 0.x embedded mode, the three
111
111
  optional lines, and deploying with Kamal, Docker, Heroku, Render, or none
112
112
  of them.
113
113
  - [Configuration](docs/configuration.md) — every option and `RAILWATCH_*`
@@ -20,6 +20,16 @@ module Railwatch
20
20
  MAX_ERROR_STACK = 8192
21
21
  MAX_BREADCRUMBS = 20
22
22
  MAX_CRUMB_TEXT = 500
23
+ # A click crumb names the element and quotes a little of its visible
24
+ # text, which is page content: enough to recognise a button, not a row.
25
+ MAX_CLICK_TEXT = 32
26
+ # A browser URL is cleaned at up to this length, then stored at 2048.
27
+ MAX_URL_INPUT = 16_384
28
+ CLICK_TEXT = /\A(?<target>[^"]*) "(?<text>.*)"\z/m
29
+ # The same, cut to MAX_CRUMB_TEXT before its closing quote arrived.
30
+ CLICK_TEXT_UNTERMINATED = /\A(?<target>[^"]*) "(?<text>.*)\z/m
31
+ NAVIGATE_TEXT = /\A(?<method>[A-Z]+) (?<url>.*)\z/m
32
+ CONSOLE_LEVEL = /\A(?<level>error|warn)\b/
23
33
  MAX_CONTEXT_KEYS = 20
24
34
  MAX_CONTEXT_VALUE = 4096
25
35
  CRUMB_KINDS = %w[console click navigate].freeze
@@ -43,7 +53,7 @@ module Railwatch
43
53
  group: Record.group_hash(safe_string(v["component"], 255)),
44
54
  timestamp: safe_float(v["started_at"]) / 1000.0,
45
55
  component: safe_string(v["component"], 255),
46
- url: safe_string(v["url"], 2048),
56
+ url: browser_url(v["url"]),
47
57
  method: safe_string(v["method"], 10),
48
58
  duration: (safe_float(v["duration_ms"]) * 1000).round,
49
59
  status: safe_string(v["status"], 20),
@@ -202,9 +212,11 @@ module Railwatch
202
212
  # through whatever path or subdomain the app scopes tenants by, so an
203
213
  # app that scopes them at all resolves nothing here -- the client's hint
204
214
  # (startRailwatch({ tenant })) fills that gap, and never overrides a
205
- # tenant the server did resolve for itself.
215
+ # tenant the server did resolve for itself. The beacon takes no
216
+ # credential, so the hint counts only when the app signed it into the
217
+ # page (Railwatch.beacon_tenant_hint); a bare name is anyone's to choose.
206
218
  def beacon_tenant(hint)
207
- Context.current_tenant || (hint.is_a?(String) ? safe_string(hint, 255).presence : nil)
219
+ Context.current_tenant || Railwatch.verified_beacon_tenant(hint)&.then { |t| safe_string(t, 255).presence }
208
220
  end
209
221
 
210
222
  # The flush's session id, for an error that does not name its own (a
@@ -226,8 +238,9 @@ module Railwatch
226
238
  message = safe_string(error["message"], MAX_ERROR_MESSAGE)
227
239
  frames = Backtrace.js_frames(safe_string(error["stack"], MAX_ERROR_STACK), origin: origin)
228
240
  top = Subscribers::Exceptions.top_frame(frames)
241
+ file, line = Backtrace.js_fingerprint_location(top)
229
242
  parts = Subscribers::Exceptions.cap_fingerprint(
230
- [ name, top[:file], top[:line], Subscribers::Exceptions.normalize_message(message) ])
243
+ [ name, file, line, Subscribers::Exceptions.normalize_message(message) ])
231
244
  Railwatch.record(:exception,
232
245
  group: Record.group_hash(*parts),
233
246
  timestamp: safe_float(error["at"]).positive? ? safe_float(error["at"]) / 1000.0 : nil,
@@ -240,9 +253,9 @@ module Railwatch
240
253
  line: top[:line],
241
254
  frames: frames,
242
255
  context: Context.serialized_with(error_context(error["context"]).merge(browser: {
243
- url: safe_string(error["url"], 2048).presence,
256
+ url: browser_url(error["url"]).presence,
244
257
  component: safe_string(error["component"], 255).presence,
245
- visit: safe_string(error["visit"], 2048).presence,
258
+ visit: browser_url(error["visit"]).presence,
246
259
  session: session_id,
247
260
  tab: Sessions.browser_id(error["tab_id"]),
248
261
  user_agent: safe_string(request.user_agent, 256).presence,
@@ -264,12 +277,50 @@ module Railwatch
264
277
  next unless crumb
265
278
  kind = safe_string(crumb["kind"], 20)
266
279
  next unless CRUMB_KINDS.include?(kind)
267
- text = safe_string(crumb["text"], MAX_CRUMB_TEXT)
280
+ text = crumb_text(kind, safe_string(crumb["text"], MAX_CRUMB_TEXT))
268
281
  next if text.empty?
269
282
  { at: safe_float(crumb["at"]), kind: kind, text: text }
270
283
  end
271
284
  end
272
285
 
286
+ # The browser client trims these itself now, but a copy generated before
287
+ # it did sends the full URL of each navigation, a click's text, and the
288
+ # arguments of every console call, so the server holds the line too.
289
+ def crumb_text(kind, text)
290
+ case kind
291
+ when "navigate"
292
+ match = NAVIGATE_TEXT.match(text) or return browser_url(text)
293
+ "#{match[:method]} #{browser_url(match[:url])}"
294
+ when "click"
295
+ match = CLICK_TEXT.match(text) || CLICK_TEXT_UNTERMINATED.match(text) or return text
296
+ quoted = match[:text][0, MAX_CLICK_TEXT]
297
+ quoted.empty? ? match[:target] : %(#{match[:target]} "#{quoted}")
298
+ when "console"
299
+ return text if Railwatch.config.capture_browser_console_arguments
300
+
301
+ CONSOLE_LEVEL.match(text)&.[](:level) || "console"
302
+ else
303
+ text
304
+ end
305
+ end
306
+
307
+ # A page URL the browser sent, without its fragment or userinfo, and
308
+ # without its query unless the app opted in
309
+ # (config.capture_browser_query_strings): reset, magic-link and OAuth
310
+ # secrets ride there. The same treatment a server-side request URL gets.
311
+ #
312
+ # Cleaned at the length the beacon carried it, and cut to 2048 only
313
+ # after: cut first, a long userinfo loses its "@" and survives.
314
+ def browser_url(value)
315
+ url = safe_string(value, MAX_URL_INPUT)
316
+ return Record.url_without_sensitive_components(url, limit: 2048) unless Railwatch.config.capture_browser_query_strings
317
+
318
+ url = url[0, url.index("#")] if url.include?("#")
319
+ path, query = url.split("?", 2)
320
+ clean = Record.url_without_sensitive_components(path, limit: 2048)
321
+ query ? "#{clean}?#{query}"[0, 2048] : clean
322
+ end
323
+
273
324
  # Whatever the app handed Railwatch's reportError -- a React error
274
325
  # boundary's component stack, most often. Flattened to strings so a
275
326
  # cyclic or enormous object cannot ride in on it.
data/docs/ai-and-mcp.md CHANGED
@@ -11,11 +11,11 @@ priority, leave a comment — and every write is signed with your user and the
11
11
  agent's name in the issue's activity feed.
12
12
 
13
13
  The endpoint is `<your ingest host>/mcp`. For the hosted platform that's
14
- `https://railwatch.rebulk.com/mcp`; if you self-host, it is your own host (see
15
- [`self-hosting.md`](self-hosting.md)). With the `railwatch-server` gem the
14
+ `https://app.railwatch.dev/mcp`; if you self-host, it is your own host (see
15
+ [`self-hosting.md`](self-hosting.md)). With the `railwatch-sidecar` gem the
16
16
  server runs under the app's dashboard path, so the endpoint is the app's own
17
17
  host plus `/railwatch/mcp`; see the
18
- [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
18
+ [railwatch-sidecar README](https://github.com/Rebulk/railwatch-sidecar#readme).
19
19
  In development that endpoint needs no token from the same machine (see
20
20
  [In development](#in-development) below). For Railwatch Cloud and a
21
21
  self-hosted server the gem knows which one you're on:
@@ -28,7 +28,7 @@ prints every block below with your platform's host already filled in.
28
28
 
29
29
  ### In development
30
30
 
31
- With `railwatch-server`, the app's own `bin/dev` serves MCP at
31
+ With `railwatch-sidecar`, the app's own `bin/dev` serves MCP at
32
32
  `http://localhost:3000/railwatch/mcp`, and the proxy signs agent requests
33
33
  for you, so no token is needed:
34
34
 
@@ -42,7 +42,7 @@ That holds only in development, for a request from the same machine to a
42
42
  `localhost`/`127.0.0.1`/`::1` host name, so anyone who can reach the dev
43
43
  server's port from this machine can read and comment on its development
44
44
  data, as they can already open its dashboard. Other environments need a
45
- token unless the app sets `Railwatch::Server.config.agent_access = true`.
45
+ token unless the app sets `Railwatch::Sidecar.config.agent_access = true`.
46
46
  Each recorded development response also carries `Server-Timing` and
47
47
  `X-Railwatch-Execution-Id` (`timing_headers` in
48
48
  [`configuration.md`](configuration.md)), so an agent can `curl -i` a page and
@@ -64,13 +64,13 @@ each with a copy button — so the fastest path is: generate, copy, paste.
64
64
 
65
65
  ## 2. Connect a client
66
66
 
67
- Everything below uses `https://railwatch.rebulk.com/mcp`; substitute your own
67
+ Everything below uses `https://app.railwatch.dev/mcp`; substitute your own
68
68
  host if you self-host, and `rwp_your_token_here` for the token.
69
69
 
70
70
  ### Claude Code
71
71
 
72
72
  ```sh
73
- claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
73
+ claude mcp add railwatch --transport http https://app.railwatch.dev/mcp \
74
74
  --header "Authorization: Bearer rwp_your_token_here"
75
75
  ```
76
76
 
@@ -87,7 +87,7 @@ Claude Desktop speaks stdio, so it needs the `mcp-remote` bridge. In
87
87
  "args": [
88
88
  "-y",
89
89
  "mcp-remote",
90
- "https://railwatch.rebulk.com/mcp",
90
+ "https://app.railwatch.dev/mcp",
91
91
  "--header",
92
92
  "Authorization: Bearer rwp_your_token_here"
93
93
  ]
@@ -104,7 +104,7 @@ Claude Desktop speaks stdio, so it needs the `mcp-remote` bridge. In
104
104
  {
105
105
  "mcpServers": {
106
106
  "railwatch": {
107
- "url": "https://railwatch.rebulk.com/mcp",
107
+ "url": "https://app.railwatch.dev/mcp",
108
108
  "headers": { "Authorization": "Bearer rwp_your_token_here" }
109
109
  }
110
110
  }
@@ -120,7 +120,7 @@ Claude Desktop speaks stdio, so it needs the `mcp-remote` bridge. In
120
120
  "servers": {
121
121
  "railwatch": {
122
122
  "type": "http",
123
- "url": "https://railwatch.rebulk.com/mcp",
123
+ "url": "https://app.railwatch.dev/mcp",
124
124
  "headers": { "Authorization": "Bearer rwp_your_token_here" }
125
125
  }
126
126
  }
@@ -140,7 +140,7 @@ Claude Desktop speaks stdio, so it needs the `mcp-remote` bridge. In
140
140
  "args": [
141
141
  "-y",
142
142
  "mcp-remote",
143
- "https://railwatch.rebulk.com/mcp",
143
+ "https://app.railwatch.dev/mcp",
144
144
  "--header",
145
145
  "Authorization: Bearer rwp_your_token_here"
146
146
  ]
@@ -152,7 +152,7 @@ Claude Desktop speaks stdio, so it needs the `mcp-remote` bridge. In
152
152
  ### Check it without a client
153
153
 
154
154
  ```sh
155
- curl -sS https://railwatch.rebulk.com/mcp \
155
+ curl -sS https://app.railwatch.dev/mcp \
156
156
  -H "Authorization: Bearer rwp_your_token_here" \
157
157
  -H "Content-Type: application/json" \
158
158
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
@@ -160,8 +160,8 @@ curl -sS https://railwatch.rebulk.com/mcp \
160
160
 
161
161
  A JSON body listing tools means the token works. A `401` means it doesn't.
162
162
 
163
- `GET https://railwatch.rebulk.com/mcp` and
164
- `GET https://railwatch.rebulk.com/.well-known/mcp.json` describe the server —
163
+ `GET https://app.railwatch.dev/mcp` and
164
+ `GET https://app.railwatch.dev/.well-known/mcp.json` describe the server —
165
165
  name, version, protocol version, transport, tool and prompt names, and how
166
166
  to authenticate — with no token at all, for clients that probe a host before
167
167
  they're configured.
@@ -12,8 +12,8 @@ values set in the initializer always win over the env var.
12
12
  | Attribute | Env var | Default | Meaning |
13
13
  |---|---|---|---|
14
14
  | `enabled` | `RAILWATCH_ENABLED` | `true` | Master switch. `Railwatch.enabled?` is also `false` whenever `token` is blank, so setting only `RAILWATCH_TOKEN` is enough to turn an install on. |
15
- | `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required; with railwatch-server installed it is set for you. |
16
- | `ingest_url` | `RAILWATCH_INGEST_URL` | `https://railwatch.rebulk.com` | Server base URL. Point at a self-hosted railwatch-rs to override. |
15
+ | `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required; with railwatch-sidecar installed it is set for you. |
16
+ | `ingest_url` | `RAILWATCH_INGEST_URL` | `https://app.railwatch.dev` | Server base URL. Point at a self-hosted railwatch-rs to override. |
17
17
  | `allow_http` | `RAILWATCH_ALLOW_HTTP` | `false` | Permit a non-loopback plain HTTP ingest URL. HTTPS is required by default; `localhost`, `127.0.0.1`, and `::1` remain available for local self-hosted development. |
18
18
  | `deploy` | `RAILWATCH_DEPLOY` | auto-detected (order below), then nil | Version tag stamped on every record and used by `railwatch:deploy`. Full 40-character SHAs are shortened to 12 characters. |
19
19
  | `detect_deploy` | `RAILWATCH_DETECT_DEPLOY` | `true` | Detect deploys beyond `RAILWATCH_DEPLOY` and `KAMAL_VERSION`. Set false when the app deliberately reports no inferred deploy. |
@@ -23,6 +23,8 @@ values set in the initializer always win over the env var.
23
23
  | `timing_headers` | `RAILWATCH_TIMING_HEADERS` | on in development, off elsewhere | Adds `Server-Timing` (`total`, `db` with the query count in `desc`, `view`, `other`) and `X-Railwatch-Execution-Id` to every recorded request's response, so `curl -i`, the browser's network panel, or a coding agent sees the cost and the execution to pass to `get_execution`. The id is left out when the request was sampled out. An existing `Server-Timing` (Rails' `config.server_timing`) is appended to. Off outside development by default because it tells every visitor how the app spends its time. Costs about 4 µs per request when on. |
24
24
  | `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. |
25
25
  | `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. |
26
+ | `capture_browser_query_strings` | `RAILWATCH_CAPTURE_BROWSER_QUERY_STRINGS` | `false` | Keep the query string of a browser visit's `url`, an error's page `url` and `visit`, and each navigation breadcrumb. Off: only the path is stored, because reset, magic-link and OAuth secrets ride in the query. Fragments and URL userinfo are always dropped. The browser client sends a query only with `startRailwatch({ captureQueryStrings: true })`. |
27
+ | `capture_browser_console_arguments` | `RAILWATCH_CAPTURE_BROWSER_CONSOLE_ARGUMENTS` | `false` | Keep what the page passed to `console.error`/`console.warn` in a breadcrumb. Off: the crumb is just `error` or `warn`. The browser client sends the arguments only with `startRailwatch({ captureConsoleArguments: true })`. |
26
28
  | `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. |
27
29
 
28
30
  `Railwatch.enabled?` delegates to `config.enabled?`, which is `@enabled &&
@@ -309,8 +311,12 @@ raised an exception. See `request` in `docs/records.md`.
309
311
 
310
312
  Header names containing a credential-shaped segment are always masked as
311
313
  a safe default. The segments are `api-key`, `access-key`, `private-key`,
312
- `auth`, `bearer`, `credential`, `hmac`, `jwt`, `token`, `secret`, and
313
- `signature`. This holds even when they arrive as concatenated Rack
314
+ `auth`, `bearer`, `credential`, `hmac`, `jwt`, `token`, `secret`,
315
+ `signature`, `password`, `session-id`, `subscription-key` (Azure API
316
+ Management's `Ocp-Apim-Subscription-Key`), `client-cert`
317
+ (`X-Forwarded-Client-Cert`), and the identity headers an authenticating
318
+ proxy adds (`X-Forwarded-User`, `X-Forwarded-Email`, `X-Remote-User`).
319
+ This holds even when they arrive as concatenated Rack
314
320
  aliases such as `X-AuthToken`, `X-ApiToken`, `X-AccessToken`,
315
321
  `X-ClientToken`, `X-SessionToken`, `X-RefreshToken`, `X-SecretKey`,
316
322
  `X-HmacSignature`, or `X-CSRFToken`. Add application-specific aliases to
@@ -748,14 +754,14 @@ call `startRailwatch()` from your Inertia entrypoint. It is generated at
748
754
  `app/frontend/lib/railwatch.ts` (see Getting started for how the directory
749
755
  is chosen and how to update the copy).
750
756
 
751
- `startRailwatch` takes three optional settings, none of which has a
752
- server-side equivalent. They are decisions about the browser the code is
753
- running in:
757
+ `startRailwatch` takes five optional settings. They are decisions about the
758
+ browser the code is running in:
754
759
 
755
760
  ```ts
756
761
  startRailwatch({
757
762
  // Messages never worth an issue, added to the defaults (both
758
- // "ResizeObserver loop ..." messages). Strings match anywhere in the
763
+ // "ResizeObserver loop ..." messages, and the bare "Script error." a
764
+ // browser gives for a cross-origin script). Strings match anywhere in the
759
765
  // message; regexes are tested against it.
760
766
  ignoreErrors: [/Failed to fetch dynamically imported module/],
761
767
  // Scripts whose failures are not this app's, matched against the top
@@ -765,12 +771,47 @@ startRailwatch({
765
771
  denyUrls: [/analytics\./],
766
772
  // Only for apps that scope tenants by path or subdomain: the beacon
767
773
  // posts to /railwatch/beacon, outside that scoping, so the server cannot
768
- // resolve the tenant itself. Read on every flush. A tenant the server
769
- // does resolve (`Context.current_tenant`) always wins.
770
- tenant: () => /^\/orgs\/([^/]+)/.exec(location.pathname)?.[1],
774
+ // resolve the tenant itself. Read on every flush. Return the hint the
775
+ // server signed into the page (Railwatch.beacon_tenant_hint(tenant)); the
776
+ // beacon ignores a bare tenant name, which anyone could send. A tenant
777
+ // the server does resolve (`Context.current_tenant`) always wins.
778
+ tenant: () => document.querySelector<HTMLMetaElement>('meta[name="railwatch-tenant"]')?.content,
779
+ // Both off by default. A page's query string is where reset, magic-link
780
+ // and OAuth secrets ride, and console arguments are whatever the page
781
+ // had in hand. Each also needs its server setting
782
+ // (capture_browser_query_strings, capture_browser_console_arguments).
783
+ captureQueryStrings: false,
784
+ captureConsoleArguments: false,
771
785
  })
772
786
  ```
773
787
 
788
+ with the hint rendered by the layout:
789
+
790
+ ```erb
791
+ <meta name="railwatch-tenant" content="<%= Railwatch.beacon_tenant_hint(Current.account&.slug) %>">
792
+ ```
793
+
794
+ The layout renders on a full page load only. In an Inertia app, where
795
+ switching tenant is a visit and not a page load, that meta tag keeps the
796
+ first tenant's hint. Send the hint as a shared prop instead, and read it
797
+ from the current page on every flush:
798
+
799
+ ```ruby
800
+ # app/controllers/application_controller.rb
801
+ inertia_share railwatch_tenant: -> { Railwatch.beacon_tenant_hint(Current.account&.slug) }
802
+ ```
803
+
804
+ ```ts
805
+ import { router } from "@inertiajs/react"
806
+
807
+ let tenantHint: string | undefined
808
+ router.on("navigate", (event) => { tenantHint = event.detail.page.props.railwatch_tenant as string | undefined })
809
+ startRailwatch({ tenant: () => tenantHint })
810
+ ```
811
+
812
+ An app that only changes tenant with a full page load can use the meta
813
+ tag as it is.
814
+
774
815
  The same file exports two more things. `railwatchRootOptions()` returns
775
816
  React 19's `onCaughtError`/`onUncaughtError` root options, used as
776
817
  `createRoot(el, railwatchRootOptions())`. That is what reports an error a
@@ -781,6 +822,10 @@ does the same thing. See
781
822
  [`docs/replacing-sentry.md`](replacing-sentry.md) for what is and is not
782
823
  captured versus `@sentry/react`.
783
824
 
825
+ The client is safe to import from an SSR bundle: nothing in it touches
826
+ the DOM at import time, and `startRailwatch()` returns without doing
827
+ anything when there is no `window`.
828
+
784
829
  SSR timing needs no configuration. `Railwatch::Patches::Inertia` prepends
785
830
  `InertiaRails::Renderer#ssr_render` whenever `inertia_rails` SSR is
786
831
  enabled. The resulting `ssr_ms` lands on the `request` record's
@@ -928,10 +973,10 @@ in `lib/railwatch.rb`, unless noted:
928
973
  `instrument_outgoing`, `flush`, `debug { }`. `pause`/`resume` are the
929
974
  ignore block's building blocks, and are nestable.
930
975
 
931
- ## Dashboard gate (railwatch-server)
976
+ ## Dashboard gate (railwatch-sidecar)
932
977
 
933
978
  These settings do nothing on their own. They gate the dashboard that the
934
- [`railwatch-server`](https://github.com/Rebulk/railwatch-server) gem
979
+ [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar) gem
935
980
  serves at `/railwatch` inside the app, so one setting covers it whichever
936
981
  way it is installed.
937
982
 
@@ -949,10 +994,29 @@ In development with no credentials configured, it is open. An initializer
949
994
  or env var that sets them wins over credentials.
950
995
 
951
996
  An app with its own admin authentication turns Basic off and names a
952
- base controller. railwatch-server's proxy controller inherits from
997
+ base controller. railwatch-sidecar's proxy controller inherits from
953
998
  `base_controller_class`, so the app's own `before_action`s (require an
954
999
  admin, redirect to sign-in) run in front of every dashboard request.
955
1000
 
1001
+ Basic off with `base_controller_class` left at `ActionController::Base` is
1002
+ no gate at all. `Railwatch.config.dashboard_gate_configured?` is false
1003
+ then. railwatch-sidecar 0.2.1 and later refuse to serve the dashboard
1004
+ outside development in that configuration (a 503 that says what to set,
1005
+ and an error at boot), and sign a visitor the app does not name as a
1006
+ `member`. railwatch-sidecar 0.2.0 and earlier (and railwatch-server) do
1007
+ neither: they serve that configuration to anyone, as an admin. Upgrade
1008
+ the sidecar, or keep Basic on.
1009
+
1010
+ ```ruby
1011
+ c.dashboard_default_role = "member" # RAILWATCH_DASHBOARD_DEFAULT_ROLE; "member" or "admin"
1012
+ ```
1013
+
1014
+ The role railwatch-sidecar gives a visitor the app did not name (no
1015
+ `Railwatch::Sidecar.config.user`): the HTTP Basic user, or the single
1016
+ operator. `member` by default, so a shared Basic password does not hand out
1017
+ token, member and integration management; set `admin` for the old
1018
+ behaviour, or name users and their roles with `Railwatch::Sidecar.config.user`.
1019
+
956
1020
  ## Rake tasks
957
1021
 
958
1022
  Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
@@ -981,7 +1045,7 @@ Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
981
1045
  is empty inside an app container, which has no `.git`. That is why the
982
1046
  hook below posts from the deployer instead.
983
1047
  - **`railwatch:authentication:configure`** writes the
984
- [dashboard gate](#dashboard-gate-railwatch-server)'s HTTP Basic
1048
+ [dashboard gate](#dashboard-gate-railwatch-sidecar)'s HTTP Basic
985
1049
  credentials to the current environment's Rails credentials.
986
1050
  - **`railwatch:token`** and **`railwatch:mcp`** print where to create an
987
1051
  ingest token and paste-ready MCP client configuration for the server