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.
data/docs/faq.md CHANGED
@@ -59,17 +59,17 @@ single-writer SQLite app into a "database is locked" incident.
59
59
  ## Where does the data go, and how long is it kept?
60
60
 
61
61
  One gzip-NDJSON POST to `{ingest_url}/ingest` per batch, to Railwatch
62
- Cloud, a self-hosted railwatch-rs, or the server the `railwatch-server`
62
+ Cloud, a self-hosted railwatch-rs, or the server the `railwatch-sidecar`
63
63
  gem runs next to the app. The gem keeps nothing on disk itself.
64
64
 
65
65
  Railwatch Cloud stores each monitored environment's telemetry in its
66
66
  own database, prunes raw rows on a retention window, and keeps hourly
67
67
  rollups for the charts. Retention there is set by the account's plan
68
68
  tier, not by the gem — 7, 30, or 90 days depending on the plan. For
69
- railwatch-rs, self-hosted or through railwatch-server, retention and
69
+ railwatch-rs, self-hosted or through railwatch-sidecar, retention and
70
70
  backups are server settings
71
71
  ([railwatch-rs SELF-HOST.md](https://github.com/Rebulk/railwatch-rs/blob/main/docs/SELF-HOST.md),
72
- [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme)).
72
+ [railwatch-sidecar README](https://github.com/Rebulk/railwatch-sidecar#readme)).
73
73
 
74
74
  ## What about PII?
75
75
 
@@ -7,13 +7,13 @@ nothing else has to be wired by hand.
7
7
  The `railwatch` gem is the agent: it instruments the app and sends what
8
8
  it records over HTTPS to a Railwatch server. The server is one of:
9
9
 
10
- - **Railwatch Cloud** at <https://railwatch.rebulk.com>, the default.
10
+ - **Railwatch Cloud** at <https://app.railwatch.dev>, the default.
11
11
  - **Your own [railwatch-rs](https://github.com/Rebulk/railwatch-rs)**,
12
12
  one static binary that serves many apps
13
13
  ([Self-hosting](self-hosting.md)).
14
- - **The [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
14
+ - **The [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar)
15
15
  gem**, which runs railwatch-rs next to Puma for this one app and serves
16
- the dashboard at `/railwatch` ([below](#embedded-railwatch-server)).
16
+ the dashboard at `/railwatch` ([below](#embedded-railwatch-sidecar)).
17
17
 
18
18
  ## Install
19
19
 
@@ -31,7 +31,7 @@ secret in shell history or process arguments:
31
31
  ```sh
32
32
  bin/rails generate railwatch:install \
33
33
  --prompt-token \
34
- --url=https://railwatch.rebulk.com \
34
+ --url=https://app.railwatch.dev \
35
35
  --kamal-secrets
36
36
  ```
37
37
 
@@ -42,7 +42,7 @@ bin/rails generate railwatch:install \
42
42
  deployment secret manager, or add `.env` to `.gitignore` first. Token values
43
43
  are never printed by the generator.
44
44
  - `--url=` sets `RAILWATCH_INGEST_URL`, for a self-hosted server. Leave
45
- it off to use the default, `https://railwatch.rebulk.com`.
45
+ it off to use the default, `https://app.railwatch.dev`.
46
46
  - `--kamal-secrets` appends `RAILWATCH_TOKEN=$RAILWATCH_TOKEN` to
47
47
  `.kamal/secrets` and adds `RAILWATCH_TOKEN` under `env: secret:` in
48
48
  `config/deploy.yml`, which is the pair of edits Kamal needs to pass a
@@ -108,9 +108,9 @@ bin/rails railwatch:doctor
108
108
  ```
109
109
  ✓ token: rw_9Qv... (43 chars)
110
110
  ✓ token storage: no tracked plaintext Railwatch token found
111
- ✓ ingest url: https://railwatch.rebulk.com
111
+ ✓ ingest url: https://app.railwatch.dev
112
112
  ✓ ingest transport security: HTTPS with certificate verification
113
- ✓ ingest reachable: GET https://railwatch.rebulk.com/ingest/ping
113
+ ✓ ingest reachable: GET https://app.railwatch.dev/ingest/ping
114
114
  ✓ request middleware: Railwatch::Middleware::Request at position 0
115
115
  ✓ engine mounted: POST /railwatch/beacon -> railwatch/beacon#create
116
116
  ✓ deploy: 8f31c0a42e91 (from GIT_REV)
@@ -128,22 +128,22 @@ to do about a `✗` is in [`troubleshooting.md`](troubleshooting.md).
128
128
  `bin/rails railwatch:status` is the one-line version: it pings
129
129
  `{ingest_url}/ingest/ping` and prints the ingest URL, deploy, and server.
130
130
 
131
- ## Embedded: railwatch-server
131
+ ## Embedded: railwatch-sidecar
132
132
 
133
133
  To keep telemetry inside the app instead, add the
134
- [`railwatch-server`](https://github.com/Rebulk/railwatch-server) gem
134
+ [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar) gem
135
135
  next to this one. It bundles the railwatch-rs binary for your platform,
136
136
  runs it as its own process beside Puma, and points this agent at it:
137
137
 
138
138
  ```ruby
139
139
  # Gemfile
140
140
  gem "railwatch"
141
- gem "railwatch-server"
141
+ gem "railwatch-sidecar"
142
142
  ```
143
143
 
144
144
  ```ruby
145
145
  # config/puma.rb
146
- plugin :railwatch_server
146
+ plugin :railwatch_sidecar
147
147
  ```
148
148
 
149
149
  On first boot it provisions `storage/railwatch/<env>` and sets the
@@ -158,23 +158,32 @@ RAILS_ENV=production bin/rails railwatch:authentication:configure
158
158
  ```
159
159
 
160
160
  To use your own admin authentication instead, turn Basic off and name a
161
- base controller ([Configuration](configuration.md#dashboard-gate-railwatch-server)).
161
+ base controller ([Configuration](configuration.md#dashboard-gate-railwatch-sidecar)).
162
162
  Everything else about it (ports, data directory, email, backups) is in
163
- the [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
163
+ the [railwatch-sidecar README](https://github.com/Rebulk/railwatch-sidecar#readme).
164
164
 
165
165
  ### Coming from 0.x embedded mode
166
166
 
167
167
  Railwatch 0.x could keep telemetry in two SQLite databases of the app's
168
168
  own, written by a Puma writer process, with the dashboard served from the
169
- gem. 1.0 removes that mode. To move:
169
+ gem. 1.0 removes that mode, and that Ruby dashboard is not coming back:
170
+ there is one Railwatch engine, railwatch-rs, whether it runs next to
171
+ Puma (railwatch-sidecar), on its own box, or as Railwatch Cloud. If you
172
+ upgrade without these steps, a removed setting in the initializer stops
173
+ boot with `Railwatch::Configuration::RemovedSetting`, and `plugin
174
+ :railwatch` stops Puma, both linking back here. A leftover
175
+ `RAILWATCH_TRANSPORT=local` does not stop boot: it is ignored with one
176
+ warning in the log, and the agent sends to its `ingest_url`, which is
177
+ Railwatch Cloud unless you set one. Your telemetry would then leave the
178
+ box, so do step 1 before deploying. To move:
170
179
 
171
180
  1. Remove `c.transport = :local` (or `RAILWATCH_TRANSPORT=local`) from
172
181
  the initializer and environment.
173
182
  2. Remove `plugin :railwatch` from `config/puma.rb`. Puma refuses to boot
174
- with a plugin it cannot find.
183
+ with it.
175
184
  3. Remove the `railwatch` and `railwatch_telemetry` entries from
176
185
  `config/database.yml`.
177
- 4. Add `railwatch-server` as above, or point the app at Railwatch Cloud
186
+ 4. Add `railwatch-sidecar` as above, or point the app at Railwatch Cloud
178
187
  or a self-hosted railwatch-rs.
179
188
 
180
189
  The old files (`storage/<env>_railwatch.sqlite3`,
@@ -194,7 +203,7 @@ Records are batched in-process and flushed every `flush_interval`
194
203
  (2 seconds by default) or every 500 records, whichever comes first, so
195
204
  the request shows up on the **Requests** page (the environment in
196
205
  Railwatch Cloud or your own server, or `/railwatch` with
197
- railwatch-server) a couple of seconds after you make it —
206
+ railwatch-sidecar) a couple of seconds after you make it —
198
207
  with its queries, cache reads, view renders, and log lines already
199
208
  attached to it.
200
209
 
@@ -233,7 +242,8 @@ createRoot(el, railwatchRootOptions()).render(<App {...props} />)
233
242
  On React 18, whose roots take no error options, call
234
243
  `reportError(error, { componentStack: info.componentStack })` from the
235
244
  boundary's `componentDidCatch` instead. `startRailwatch` also takes optional
236
- `ignoreErrors`, `denyUrls`, and `tenant` settings; see
245
+ `ignoreErrors`, `denyUrls`, `tenant`, `captureQueryStrings` and
246
+ `captureConsoleArguments` settings; see
237
247
  [`docs/configuration.md`](configuration.md) and
238
248
  [`docs/replacing-sentry.md`](replacing-sentry.md).
239
249
 
@@ -276,7 +286,7 @@ up, on the account.
276
286
 
277
287
  ## Deploying
278
288
 
279
- With railwatch-server, the server's data lives under
289
+ With railwatch-sidecar, the server's data lives under
280
290
  `storage/railwatch/<env>`, which has to be on a volume that survives
281
291
  deploys (the Rails 8 Kamal template mounts `storage/`); its README covers
282
292
  deploys and two containers sharing a volume. The token steps below are
@@ -321,7 +331,7 @@ Environment variables only:
321
331
 
322
332
  ```sh
323
333
  RAILWATCH_TOKEN=rw_...
324
- RAILWATCH_INGEST_URL=https://railwatch.rebulk.com # only when self-hosting
334
+ RAILWATCH_INGEST_URL=https://monitor.example.com # only when self-hosting: your server
325
335
  RAILWATCH_DEPLOY=<release identifier>
326
336
  ```
327
337
 
data/docs/records.md CHANGED
@@ -72,7 +72,10 @@ whether child records ship, not whether an error is visible.
72
72
  ### `request`
73
73
 
74
74
  Built by the outermost Rack middleware in
75
- `lib/railwatch/middleware/request.rb`. That middleware also owns the
75
+ `lib/railwatch/middleware/request.rb`. A file `ActionDispatch::Static`
76
+ served from `public/` (a GET or HEAD no route matched, answered 2xx or
77
+ 304, whose path names a file there or its precompressed `.br`/`.gz`) is not recorded. An unmatched request
78
+ for anything else, a 404 included, is. That middleware also owns the
76
79
  `middleware_before`/`action`/`render`/`middleware_after` stage
77
80
  boundaries. The `action`/`render` boundaries come from
78
81
  `start_processing.action_controller` and `render_template.action_view` in
@@ -334,8 +337,9 @@ its own `exceptions` sample rate rolled once per execution. See
334
337
 
335
338
  The default fingerprint normalizes the message before hashing it, so one
336
339
  issue doesn't shatter into thousands. URLs, email addresses, UUIDs, ISO
337
- timestamps, IPv4 addresses, quoted strings, hex runs of six characters or
338
- more, and plain integers all become `?`. Whitespace collapses, and the
340
+ timestamps, IPv4 and IPv6 addresses (lower-case hex, full or compressed
341
+ with `::`), quoted strings, hex runs of six characters or more, and plain
342
+ integers all become `?`. Whitespace collapses, and the
339
343
  result is cut at 200 chars. For classes whose message is mostly the data
340
344
  that varied, only the message *prefix* is kept. The prefix runs up to the
341
345
  first `:` for `ActiveRecord::RecordNotFound`, `ActiveRecord::RecordInvalid`,
@@ -393,9 +397,16 @@ line with no location on it is dropped:
393
397
  | `in_app` | True when the script came from the app's own origin and is not under `node_modules/` or `vendor/`. |
394
398
 
395
399
  No source snippets: the file is on the client, not on the server. Frames
396
- are fingerprinted exactly like Ruby ones: class, top in-app frame, and
397
- the normalized message. So browser errors group, split, merge, resolve,
398
- and regress through the same Issue machinery.
400
+ are fingerprinted like Ruby ones: class, top in-app frame, and the
401
+ normalized message. So browser errors group, split, merge, resolve, and
402
+ regress through the same Issue machinery. One difference: when the top
403
+ frame's file name carries a bundler's content hash (`dist-DedfDSJv.js`,
404
+ `main.3f2a1b9c.js`, `app-5XDGVJ2T.mjs`; eight or more characters with a
405
+ digit, or mixed case that does not read as camelCase words, so
406
+ `checkout-PaymentForm.js` keeps its name), the fingerprint uses the name without the hash
407
+ (`dist.js`) and no line. Both change on every deploy of a minified
408
+ bundle, so keeping them would open a new issue each release. The frame
409
+ itself keeps the real file and line.
399
410
 
400
411
  `context` carries a `browser` key with the page `url`, the Inertia
401
412
  `component`, the `visit` the error happened in if any, the browser
@@ -6,7 +6,7 @@ produced them, and a dashboard turns them into routes, jobs, queries,
6
6
  issues, and alerts. Railwatch Cloud is the hosted option; unlike
7
7
  Nightwatch, the server can also be self-hosted
8
8
  ([railwatch-rs](self-hosting.md)) or run inside your app with the
9
- [`railwatch-server`](getting-started.md#embedded-railwatch-server) gem.
9
+ [`railwatch-sidecar`](getting-started.md#embedded-railwatch-sidecar) gem.
10
10
  If you know Nightwatch, you already know how to read Railwatch — this page maps the vocabulary and points out the three
11
11
  places the Rails answer is genuinely different.
12
12
 
@@ -9,7 +9,7 @@ depends on a conditional row.
9
9
  Install Railwatch first ([`getting-started.md`](getting-started.md)); you
10
10
  can run both for a day if you want to compare, since neither knows about
11
11
  the other. The token steps below apply to Railwatch Cloud and to a
12
- self-hosted railwatch-rs; with the `railwatch-server` gem the token is
12
+ self-hosted railwatch-rs; with the `railwatch-sidecar` gem the token is
13
13
  set for you.
14
14
 
15
15
  ## Decide whether Railwatch covers your workload
@@ -411,8 +411,9 @@ startRailwatch({
411
411
  denyUrls: [/analytics\./],
412
412
  // Only if the app scopes tenants by path or subdomain: the beacon posts
413
413
  // to /railwatch/beacon, which is outside that scoping, so the server
414
- // cannot work the tenant out for itself.
415
- tenant: () => /^\/orgs\/([^/]+)/.exec(location.pathname)?.[1],
414
+ // cannot work the tenant out for itself. Return the hint the layout
415
+ // rendered with Railwatch.beacon_tenant_hint(tenant); a bare name is ignored.
416
+ tenant: () => document.querySelector<HTMLMetaElement>('meta[name="railwatch-tenant"]')?.content,
416
417
  })
417
418
  ```
418
419
 
@@ -421,7 +422,7 @@ startRailwatch({
421
422
  | `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. |
422
423
  | `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. |
423
424
  | `environment` | Automatic — the ingest token identifies the environment. |
424
- | `ignoreErrors` | `startRailwatch({ ignoreErrors })`. Strings match anywhere in the message; regexes are tested against it. Both `ResizeObserver` messages are ignored by default. |
425
+ | `ignoreErrors` | `startRailwatch({ ignoreErrors })`. Strings match anywhere in the message; regexes are tested against it. Both `ResizeObserver` messages and the opaque cross-origin `Script error.` are ignored by default. |
425
426
  | `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. |
426
427
  | `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. |
427
428
  | `Sentry.setTag("org", …)` | `startRailwatch({ tenant })`, and `Railwatch.context(...)` for everything else. |
@@ -564,7 +565,7 @@ hook matching `rails runner …` previews, or `sentry_runner_noise.rb` under
564
565
  | 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. |
565
566
  | 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. |
566
567
  | 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. |
567
- | 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)). |
568
+ | A dashboard inside the app | The `railwatch-sidecar` 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-sidecar)). |
568
569
  | 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. |
569
570
  | 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)). |
570
571
  | 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)). |
data/docs/security.md CHANGED
@@ -3,17 +3,17 @@
3
3
  This review covers the open-source gem that runs in a customer's Rails
4
4
  application. Railwatch Cloud is a separate service and is outside this review.
5
5
 
6
- ## Dashboard gate (railwatch-server)
6
+ ## Dashboard gate (railwatch-sidecar)
7
7
 
8
- The gem serves no dashboard. With the separate `railwatch-server` gem
8
+ The gem serves no dashboard. With the separate `railwatch-sidecar` gem
9
9
  installed, a dashboard showing every query, log line and exception the app
10
10
  recorded is proxied at `/railwatch`, and its gate is this gem's settings.
11
11
  HTTP Basic authentication is on by default. With no credentials configured,
12
12
  every dashboard request is 401 in every environment except development,
13
13
  where it is open. Credentials, once set, apply in development too. An app
14
14
  that turns Basic off gates the dashboard with its own `base_controller_class`,
15
- which railwatch-server's proxy controller inherits from. See
16
- [Configuration](configuration.md#dashboard-gate-railwatch-server).
15
+ which railwatch-sidecar's proxy controller inherits from. See
16
+ [Configuration](configuration.md#dashboard-gate-railwatch-sidecar).
17
17
 
18
18
  ## Transport
19
19
 
@@ -101,8 +101,8 @@ application/deployment secret and must not be committed.
101
101
  application-specific credentials and personal data.
102
102
  - Keep secrets out of exception messages, log text, source files, tenant ids,
103
103
  user resolvers, and custom context.
104
- - With railwatch-server, set dashboard credentials (or your own gate) before
105
- deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-server).
104
+ - With railwatch-sidecar, set dashboard credentials (or your own gate) before
105
+ deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-sidecar).
106
106
  - Use HTTPS in production and keep TLS verification enabled.
107
107
  - Put a request-body limit at the reverse proxy when the public beacon is
108
108
  enabled, and choose a shared cache if rate limits must span processes.
data/docs/self-hosting.md CHANGED
@@ -11,9 +11,9 @@ install, configuration, backups and upgrades are documented in its
11
11
  The gem doesn't care which server it talks to — point it at yours and
12
12
  everything works the same.
13
13
 
14
- For a single app, the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
14
+ For a single app, the [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar)
15
15
  gem runs that same server next to Puma and wires this gem to it, with no
16
- host to set up; see [Getting started](getting-started.md#embedded-railwatch-server).
16
+ host to set up; see [Getting started](getting-started.md#embedded-railwatch-sidecar).
17
17
  The rest of this page is for a server on its own host.
18
18
 
19
19
  ## Point the gem at your server
@@ -26,7 +26,7 @@ Railwatch.configure do |c|
26
26
  end
27
27
  ```
28
28
 
29
- `ingest_url` defaults to `https://railwatch.rebulk.com`, so this is the one
29
+ `ingest_url` defaults to `https://app.railwatch.dev`, so this is the one
30
30
  setting a self-hosted install always needs; everything the gem sends —
31
31
  records, ping, deploys — hangs off that host. Pass `--url=` to the
32
32
  installer to have it written for you:
data/docs/testing.md CHANGED
@@ -28,7 +28,7 @@ require "railwatch/minitest"
28
28
 
29
29
  Railwatch must be *enabled* in the test environment or every block would look
30
30
  empty, and it is enabled only with a token present: set any non-blank
31
- `RAILWATCH_TOKEN` for the test env. railwatch-server is off under
31
+ `RAILWATCH_TOKEN` for the test env. railwatch-sidecar is off under
32
32
  `Rails.env.test` and does not set one for you. Records go to an
33
33
  in-memory transport, never over the network, and there is no database to
34
34
  prepare. If Railwatch is disabled, the matchers raise
@@ -45,7 +45,7 @@ the engine's `railwatch.subscribe` initializer returns early, so no
45
45
  subscribers and no patches are installed at all. Fix: set
46
46
  `RAILWATCH_TOKEN`, restart, and re-run `railwatch:doctor`. The `token`
47
47
  line prints the first 6 characters and the length, which is enough to
48
- spot a truncated or quoted value. With railwatch-server installed, the
48
+ spot a truncated or quoted value. With railwatch-sidecar installed, the
49
49
  token is set when the server's data directory is provisioned; its boot
50
50
  log line says whether the agent was wired.
51
51
 
@@ -7,7 +7,7 @@ require "rails/generators"
7
7
  module Railwatch
8
8
  module Generators
9
9
  # Points the coding agents working on this app at its development
10
- # Railwatch: the MCP server the railwatch-server gem serves at
10
+ # Railwatch: the MCP server the railwatch-sidecar gem serves at
11
11
  # <mount>/mcp (no token needed from this machine in development), and a
12
12
  # short note on the dev loop. Every file it touches is either its own or
13
13
  # changed only between its markers, so it can be re-run after an upgrade.
@@ -72,7 +72,7 @@ module Railwatch
72
72
  Railwatch MCP for this app (development): #{mcp_url}
73
73
  Claude Code reads .mcp.json and asks once before it uses a project server.
74
74
  Other clients: add the same URL as a streamable HTTP MCP server.
75
- No token is needed from this machine in development (railwatch-server).
75
+ No token is needed from this machine in development (railwatch-sidecar).
76
76
  Anywhere else, send one: Authorization: Bearer rwp_... (Settings -> Profile).
77
77
  STEPS
78
78
  end
@@ -121,7 +121,7 @@ module Railwatch
121
121
  dashboard_url.delete_suffix(mount_path)
122
122
  end
123
123
 
124
- # The slug railwatch-server gives the app it provisions: the app's
124
+ # The slug railwatch-sidecar gives the app it provisions: the app's
125
125
  # module name, parameterized.
126
126
  def app_slug
127
127
  name = defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : File.basename(destination_root)
@@ -129,7 +129,8 @@ module Railwatch
129
129
  end
130
130
 
131
131
  def mount_path
132
- path = defined?(Railwatch::Server) && Railwatch::Server.respond_to?(:config) ? Railwatch::Server.config.normalized_mount_path : "/railwatch"
132
+ server = [ "Sidecar", "Server" ].filter_map { |n| Railwatch.const_get(n) if Railwatch.const_defined?(n, false) }.find { _1.respond_to?(:config) }
133
+ path = server ? server.config.normalized_mount_path : "/railwatch"
133
134
  path.to_s.empty? ? "/railwatch" : path
134
135
  end
135
136
 
@@ -1,7 +1,7 @@
1
1
  ## Railwatch (performance and errors, in development)
2
2
 
3
3
  Every request, job and command this app runs in development is recorded by
4
- the `railwatch` gem into the server `railwatch-server` runs beside it: SQL
4
+ the `railwatch` gem into the server `railwatch-sidecar` runs beside it: SQL
5
5
  (with the `file:line` that ran it), N+1s, views, logs and exceptions, all
6
6
  linked to one execution.
7
7
 
@@ -10,14 +10,14 @@ module Railwatch
10
10
 
11
11
  desc "Creates config/initializers/railwatch.rb, a Kamal post-deploy hook, the browser client, and wires the test helpers. " \
12
12
  "Telemetry goes to Railwatch Cloud, or to a self-hosted Railwatch server with --url. " \
13
- "To run the server inside this app instead, add the railwatch-server gem."
13
+ "To run the server inside this app instead, add the railwatch-sidecar gem."
14
14
 
15
15
  class_option :prompt_token, type: :boolean, default: false,
16
16
  desc: "Prompt for the ingest token without echoing it."
17
17
  class_option :token_stdin, type: :boolean, default: false,
18
18
  desc: "Read the ingest token from one line on standard input."
19
19
  class_option :url, type: :string,
20
- desc: "Ingest URL, for a self-hosted Railwatch server. Defaults to https://railwatch.rebulk.com."
20
+ desc: "Ingest URL, for a self-hosted Railwatch server. Defaults to https://app.railwatch.dev."
21
21
  class_option :kamal_secrets, type: :boolean, default: false,
22
22
  desc: "Wire RAILWATCH_TOKEN through .kamal/secrets and config/deploy.yml's `env: secret:` list."
23
23
  class_option :doctor, type: :boolean, default: true,
@@ -179,9 +179,9 @@ module Railwatch
179
179
  4. Gate performance in CI: see docs/testing.md.
180
180
 
181
181
  Want the dashboard inside this app instead, with no token? Add the
182
- railwatch-server gem (gem "railwatch-server", then
183
- `plugin :railwatch_server` in config/puma.rb):
184
- https://github.com/Rebulk/railwatch-server
182
+ railwatch-sidecar gem (gem "railwatch-sidecar", then
183
+ `plugin :railwatch_sidecar` in config/puma.rb):
184
+ https://github.com/Rebulk/railwatch-sidecar
185
185
  STEPS
186
186
  end
187
187
 
@@ -4,7 +4,7 @@
4
4
  # set by the RAILWATCH_* env var named in the comment.
5
5
  Railwatch.configure do |c|
6
6
  # c.token = ENV["RAILWATCH_TOKEN"] # RAILWATCH_TOKEN (required)
7
- # c.ingest_url = "https://railwatch.rebulk.com" # RAILWATCH_INGEST_URL; your own server when self-hosting
7
+ # c.ingest_url = "https://app.railwatch.dev" # RAILWATCH_INGEST_URL; your own server when self-hosting
8
8
  # c.deploy = "release-name" # RAILWATCH_DEPLOY; platform/Git auto-detected
9
9
  # c.detect_deploy = false # RAILWATCH_DETECT_DEPLOY; default true
10
10
 
@@ -45,9 +45,12 @@ case "$INGEST" in
45
45
  ;;
46
46
  esac
47
47
 
48
+ # The token goes to curl on stdin (-H @-), not in its arguments, which any
49
+ # user on the deployer can read with `ps`. printf is a shell builtin, so it
50
+ # never appears in a process list either.
48
51
  post() {
49
- curl -sS -m 10 -X POST "$1" \
50
- -H "Authorization: Bearer $RAILWATCH_TOKEN" \
52
+ printf 'Authorization: Bearer %s\n' "$RAILWATCH_TOKEN" | curl -sS -m 10 -X POST "$1" \
53
+ -H @- \
51
54
  -H "Content-Type: application/json" \
52
55
  -d "$2" >/dev/null 2>&1 || true
53
56
  }
@@ -78,17 +78,32 @@ export interface RailwatchOptions {
78
78
  denyUrls?: RegExp[]
79
79
  // The tenant the user is looking at. The beacon posts to /railwatch/beacon,
80
80
  // which is outside whatever path or subdomain the app scopes tenants by,
81
- // so the server cannot work this out for itself. Read on every flush, so
82
- // it follows the user across tenants without a page load.
81
+ // so the server cannot work this out for itself. Read on every flush:
82
+ // return the current tenant's hint, signed by the server with
83
+ // Railwatch.beacon_tenant_hint(tenant) (in an Inertia app, a shared prop
84
+ // read from the current page; a layout meta tag only changes on a full
85
+ // page load). The beacon ignores a bare tenant name, which anyone could
86
+ // send.
83
87
  tenant?: () => string | undefined
88
+ // Send each page's query string. Off: reset, magic-link and OAuth secrets
89
+ // ride there. The server keeps one only when
90
+ // config.capture_browser_query_strings is on too. Fragments are never sent.
91
+ captureQueryStrings?: boolean
92
+ // Put what the page passed to console.error/console.warn in a breadcrumb.
93
+ // Off: the crumb says only "error" or "warn". The server keeps the
94
+ // arguments only when config.capture_browser_console_arguments is on too.
95
+ captureConsoleArguments?: boolean
84
96
  }
85
97
 
86
98
  // Browser noise that is never actionable: ResizeObserver fires from benign
87
- // layout thrash and the spec says to ignore it, and the extension URLs are
88
- // third-party code running in someone's browser that this app cannot fix.
89
- const DEFAULT_IGNORE_ERRORS = [
99
+ // layout thrash and the spec says to ignore it, "Script error." is all a
100
+ // browser says about an error in a cross-origin script (no stack, no file,
101
+ // no line), and the extension URLs are third-party code running in
102
+ // someone's browser that this app cannot fix.
103
+ const DEFAULT_IGNORE_ERRORS: (string | RegExp)[] = [
90
104
  "ResizeObserver loop limit exceeded",
91
105
  "ResizeObserver loop completed with undelivered notifications",
106
+ /^Script error\.?$/,
92
107
  ]
93
108
  const DEFAULT_DENY_URLS = [
94
109
  /extensions\//i,
@@ -125,6 +140,8 @@ let timer: number | undefined
125
140
  let ignoreErrors: (string | RegExp)[] = DEFAULT_IGNORE_ERRORS
126
141
  let denyUrls: RegExp[] = DEFAULT_DENY_URLS
127
142
  let tenantOf: (() => string | undefined) | undefined
143
+ let captureQueryStrings = false
144
+ let captureConsoleArguments = false
128
145
  // Whether the user is waiting on a request. A visit the page starts by
129
146
  // itself -- a poll, a refresh when the tab comes back, a prefetch on hover
130
147
  // -- runs without the progress bar (`showProgress: false`, which Inertia
@@ -435,10 +452,23 @@ function tag(visit: { url: unknown; headers?: Record<string, string> }) {
435
452
  }
436
453
  }
437
454
 
455
+ // A URL the page was on, without its fragment, and without its query unless
456
+ // the app opted in (captureQueryStrings).
457
+ function pageUrl(url: string): string {
458
+ const withoutFragment = url.split("#")[0]
459
+ return captureQueryStrings ? withoutFragment : withoutFragment.split("?")[0]
460
+ }
461
+
462
+ function currentPage(): string {
463
+ return pageUrl(location.pathname + location.search)
464
+ }
465
+
438
466
  // --- Breadcrumbs -------------------------------------------------------
439
467
 
440
468
  const MAX_CRUMBS = 20
441
469
  const MAX_CRUMB_TEXT = 500
470
+ // Enough of a clicked element's text to recognise a button, not a table row.
471
+ const MAX_CLICK_TEXT = 32
442
472
  // A budget for one error's whole trail, so a page that logs War and Peace to
443
473
  // the console cannot crowd out the errors themselves.
444
474
  const MAX_CRUMB_BYTES = 8000
@@ -470,7 +500,10 @@ function describeTarget(target: EventTarget | null): string {
470
500
  const text =
471
501
  target instanceof HTMLInputElement
472
502
  ? ""
473
- : (target.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 80)
503
+ : (target.textContent ?? "")
504
+ .trim()
505
+ .replace(/\s+/g, " ")
506
+ .slice(0, MAX_CLICK_TEXT)
474
507
  return `${target.tagName.toLowerCase()}${id}${classes}${text ? ` "${text}"` : ""}`
475
508
  }
476
509
 
@@ -485,7 +518,12 @@ function startBreadcrumbs() {
485
518
  ...args: unknown[]
486
519
  ) => void
487
520
  console[level] = (...args: unknown[]) => {
488
- crumb("console", `${level}: ${args.map(stringify).join(" ")}`)
521
+ crumb(
522
+ "console",
523
+ captureConsoleArguments
524
+ ? `${level}: ${args.map(stringify).join(" ")}`
525
+ : level,
526
+ )
489
527
  original(...args)
490
528
  }
491
529
  }
@@ -547,7 +585,7 @@ function capture(
547
585
  message: message.slice(0, MAX_MESSAGE),
548
586
  stack: stack?.slice(0, MAX_STACK),
549
587
  component,
550
- url: location.pathname + location.search,
588
+ url: currentPage(),
551
589
  visit: current?.url,
552
590
  session_id: liveSession(),
553
591
  tab_id: tab,
@@ -951,7 +989,7 @@ function initialVisit(): Visit | null {
951
989
  (performance.timeOrigin ?? Date.now() - performance.now()) +
952
990
  nav.startTime,
953
991
  ),
954
- url: location.pathname + location.search,
992
+ url: currentPage(),
955
993
  method: "GET",
956
994
  component,
957
995
  duration_ms: duration,
@@ -982,10 +1020,17 @@ function finalize() {
982
1020
  flush(true)
983
1021
  }
984
1022
 
1023
+ // A no-op under server-side rendering: the Inertia SSR server runs the same
1024
+ // entrypoint, with no window to measure and nothing to send a beacon from.
1025
+ // Nothing above touches the DOM until this is called, so importing the
1026
+ // module is safe there too.
985
1027
  export function startRailwatch(options: RailwatchOptions = {}) {
1028
+ if (typeof window === "undefined") return
986
1029
  ignoreErrors = [...DEFAULT_IGNORE_ERRORS, ...(options.ignoreErrors ?? [])]
987
1030
  denyUrls = [...DEFAULT_DENY_URLS, ...(options.denyUrls ?? [])]
988
1031
  tenantOf = options.tenant
1032
+ captureQueryStrings = options.captureQueryStrings ?? false
1033
+ captureConsoleArguments = options.captureConsoleArguments ?? false
989
1034
  startVitals()
990
1035
  startSession()
991
1036
  component = pageComponent()
@@ -1020,7 +1065,7 @@ export function startRailwatch(options: RailwatchOptions = {}) {
1020
1065
  }
1021
1066
  current = {
1022
1067
  started_at: Date.now(),
1023
- url: v.url.toString(),
1068
+ url: pageUrl(v.url.toString()),
1024
1069
  method: v.method,
1025
1070
  partial: Boolean(v.only?.length || v.except?.length),
1026
1071
  only: v.only,
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ # `plugin :railwatch` ran the 0.x embedded writer, which 1.0 removed. Puma
4
+ # would refuse to boot with "Unknown plugin"; refuse with the migration.
5
+ raise "[railwatch] `plugin :railwatch` was removed in 1.0: delete it from config/puma.rb. " \
6
+ "For the dashboard inside the app, add gem \"railwatch-sidecar\" and `plugin :railwatch_sidecar`. See " \
7
+ "https://github.com/Rebulk/railwatch/blob/main/docs/getting-started.md#coming-from-0x-embedded-mode"
@@ -4,7 +4,7 @@ require "yaml"
4
4
 
5
5
  module Railwatch
6
6
  # `bin/rails railwatch:authentication:configure`: stores the HTTP Basic
7
- # credentials railwatch-server's dashboard proxy checks in the current
7
+ # credentials railwatch-sidecar's dashboard proxy checks in the current
8
8
  # environment's Rails credentials, the same way Mission Control Jobs'
9
9
  # authentication:configure does. Asks for a user, generates the password,
10
10
  # appends a `railwatch:` entry to the credentials file the environment