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 +4 -4
- data/AGENTS.md +9 -9
- data/CHANGELOG.md +107 -0
- data/README.md +8 -8
- data/app/controllers/railwatch/beacon_controller.rb +58 -7
- data/docs/ai-and-mcp.md +14 -14
- data/docs/configuration.md +79 -15
- data/docs/faq.md +3 -3
- data/docs/getting-started.md +30 -20
- data/docs/records.md +17 -6
- data/docs/replacing-nightwatch.md +1 -1
- data/docs/replacing-sentry.md +6 -5
- data/docs/security.md +6 -6
- data/docs/self-hosting.md +3 -3
- data/docs/testing.md +1 -1
- data/docs/troubleshooting.md +1 -1
- data/lib/generators/railwatch/agents/agents_generator.rb +5 -4
- data/lib/generators/railwatch/agents/templates/agents_block.md.tt +1 -1
- data/lib/generators/railwatch/install/install_generator.rb +5 -5
- data/lib/generators/railwatch/install/templates/initializer.rb.tt +1 -1
- data/lib/generators/railwatch/install/templates/post-deploy +5 -2
- data/lib/generators/railwatch/install/templates/railwatch.ts +55 -10
- data/lib/puma/plugin/railwatch.rb +7 -0
- data/lib/railwatch/authentication.rb +1 -1
- data/lib/railwatch/backtrace.rb +35 -0
- data/lib/railwatch/configuration.rb +69 -7
- data/lib/railwatch/engine.rb +4 -1
- data/lib/railwatch/middleware/request.rb +31 -0
- data/lib/railwatch/redactor.rb +6 -2
- data/lib/railwatch/sql_normalizer.rb +21 -19
- data/lib/railwatch/subscribers/exceptions.rb +19 -1
- data/lib/railwatch/version.rb +1 -1
- data/lib/railwatch.rb +36 -0
- data/lib/tasks/railwatch_tasks.rake +6 -5
- data/llms.txt +4 -4
- metadata +4 -3
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-
|
|
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-
|
|
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-
|
|
72
|
+
[railwatch-sidecar README](https://github.com/Rebulk/railwatch-sidecar#readme)).
|
|
73
73
|
|
|
74
74
|
## What about PII?
|
|
75
75
|
|
data/docs/getting-started.md
CHANGED
|
@@ -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.
|
|
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-
|
|
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-
|
|
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.
|
|
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.
|
|
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.
|
|
111
|
+
✓ ingest url: https://app.railwatch.dev
|
|
112
112
|
✓ ingest transport security: HTTPS with certificate verification
|
|
113
|
-
✓ ingest reachable: GET https://railwatch.
|
|
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-
|
|
131
|
+
## Embedded: railwatch-sidecar
|
|
132
132
|
|
|
133
133
|
To keep telemetry inside the app instead, add the
|
|
134
|
-
[`railwatch-
|
|
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-
|
|
141
|
+
gem "railwatch-sidecar"
|
|
142
142
|
```
|
|
143
143
|
|
|
144
144
|
```ruby
|
|
145
145
|
# config/puma.rb
|
|
146
|
-
plugin :
|
|
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-
|
|
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-
|
|
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
|
|
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
|
|
183
|
+
with it.
|
|
175
184
|
3. Remove the `railwatch` and `railwatch_telemetry` entries from
|
|
176
185
|
`config/database.yml`.
|
|
177
|
-
4. Add `railwatch-
|
|
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-
|
|
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`,
|
|
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-
|
|
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://
|
|
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`.
|
|
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
|
|
338
|
-
|
|
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
|
|
397
|
-
|
|
398
|
-
|
|
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-
|
|
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
|
|
data/docs/replacing-sentry.md
CHANGED
|
@@ -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-
|
|
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
|
-
|
|
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-
|
|
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-
|
|
6
|
+
## Dashboard gate (railwatch-sidecar)
|
|
7
7
|
|
|
8
|
-
The gem serves no dashboard. With the separate `railwatch-
|
|
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-
|
|
16
|
-
[Configuration](configuration.md#dashboard-gate-railwatch-
|
|
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-
|
|
105
|
-
deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-
|
|
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-
|
|
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-
|
|
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.
|
|
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-
|
|
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
|
data/docs/troubleshooting.md
CHANGED
|
@@ -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-
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
-
|
|
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-
|
|
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-
|
|
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.
|
|
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-
|
|
183
|
-
`plugin :
|
|
184
|
-
https://github.com/Rebulk/railwatch-
|
|
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.
|
|
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
|
|
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
|
|
82
|
-
//
|
|
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,
|
|
88
|
-
//
|
|
89
|
-
|
|
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 ?? "")
|
|
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(
|
|
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:
|
|
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:
|
|
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-
|
|
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
|