railwatch 1.6.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 +83 -0
- data/README.md +8 -8
- data/app/controllers/railwatch/beacon_controller.rb +56 -6
- data/docs/ai-and-mcp.md +14 -14
- data/docs/configuration.md +73 -14
- data/docs/faq.md +3 -3
- data/docs/getting-started.md +30 -20
- data/docs/replacing-nightwatch.md +1 -1
- data/docs/replacing-sentry.md +5 -4
- 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 +44 -7
- data/lib/puma/plugin/railwatch.rb +7 -0
- data/lib/railwatch/authentication.rb +1 -1
- data/lib/railwatch/configuration.rb +69 -7
- data/lib/railwatch/engine.rb +4 -1
- data/lib/railwatch/redactor.rb +6 -2
- data/lib/railwatch/sql_normalizer.rb +21 -19
- data/lib/railwatch/version.rb +1 -1
- data/lib/railwatch.rb +24 -0
- data/lib/tasks/railwatch_tasks.rake +6 -5
- data/llms.txt +4 -4
- metadata +4 -3
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
|
|
|
@@ -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
|
|
|
@@ -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,9 +78,21 @@ 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
|
|
@@ -128,6 +140,8 @@ let timer: number | undefined
|
|
|
128
140
|
let ignoreErrors: (string | RegExp)[] = DEFAULT_IGNORE_ERRORS
|
|
129
141
|
let denyUrls: RegExp[] = DEFAULT_DENY_URLS
|
|
130
142
|
let tenantOf: (() => string | undefined) | undefined
|
|
143
|
+
let captureQueryStrings = false
|
|
144
|
+
let captureConsoleArguments = false
|
|
131
145
|
// Whether the user is waiting on a request. A visit the page starts by
|
|
132
146
|
// itself -- a poll, a refresh when the tab comes back, a prefetch on hover
|
|
133
147
|
// -- runs without the progress bar (`showProgress: false`, which Inertia
|
|
@@ -438,10 +452,23 @@ function tag(visit: { url: unknown; headers?: Record<string, string> }) {
|
|
|
438
452
|
}
|
|
439
453
|
}
|
|
440
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
|
+
|
|
441
466
|
// --- Breadcrumbs -------------------------------------------------------
|
|
442
467
|
|
|
443
468
|
const MAX_CRUMBS = 20
|
|
444
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
|
|
445
472
|
// A budget for one error's whole trail, so a page that logs War and Peace to
|
|
446
473
|
// the console cannot crowd out the errors themselves.
|
|
447
474
|
const MAX_CRUMB_BYTES = 8000
|
|
@@ -473,7 +500,10 @@ function describeTarget(target: EventTarget | null): string {
|
|
|
473
500
|
const text =
|
|
474
501
|
target instanceof HTMLInputElement
|
|
475
502
|
? ""
|
|
476
|
-
: (target.textContent ?? "")
|
|
503
|
+
: (target.textContent ?? "")
|
|
504
|
+
.trim()
|
|
505
|
+
.replace(/\s+/g, " ")
|
|
506
|
+
.slice(0, MAX_CLICK_TEXT)
|
|
477
507
|
return `${target.tagName.toLowerCase()}${id}${classes}${text ? ` "${text}"` : ""}`
|
|
478
508
|
}
|
|
479
509
|
|
|
@@ -488,7 +518,12 @@ function startBreadcrumbs() {
|
|
|
488
518
|
...args: unknown[]
|
|
489
519
|
) => void
|
|
490
520
|
console[level] = (...args: unknown[]) => {
|
|
491
|
-
crumb(
|
|
521
|
+
crumb(
|
|
522
|
+
"console",
|
|
523
|
+
captureConsoleArguments
|
|
524
|
+
? `${level}: ${args.map(stringify).join(" ")}`
|
|
525
|
+
: level,
|
|
526
|
+
)
|
|
492
527
|
original(...args)
|
|
493
528
|
}
|
|
494
529
|
}
|
|
@@ -550,7 +585,7 @@ function capture(
|
|
|
550
585
|
message: message.slice(0, MAX_MESSAGE),
|
|
551
586
|
stack: stack?.slice(0, MAX_STACK),
|
|
552
587
|
component,
|
|
553
|
-
url:
|
|
588
|
+
url: currentPage(),
|
|
554
589
|
visit: current?.url,
|
|
555
590
|
session_id: liveSession(),
|
|
556
591
|
tab_id: tab,
|
|
@@ -954,7 +989,7 @@ function initialVisit(): Visit | null {
|
|
|
954
989
|
(performance.timeOrigin ?? Date.now() - performance.now()) +
|
|
955
990
|
nav.startTime,
|
|
956
991
|
),
|
|
957
|
-
url:
|
|
992
|
+
url: currentPage(),
|
|
958
993
|
method: "GET",
|
|
959
994
|
component,
|
|
960
995
|
duration_ms: duration,
|
|
@@ -994,6 +1029,8 @@ export function startRailwatch(options: RailwatchOptions = {}) {
|
|
|
994
1029
|
ignoreErrors = [...DEFAULT_IGNORE_ERRORS, ...(options.ignoreErrors ?? [])]
|
|
995
1030
|
denyUrls = [...DEFAULT_DENY_URLS, ...(options.denyUrls ?? [])]
|
|
996
1031
|
tenantOf = options.tenant
|
|
1032
|
+
captureQueryStrings = options.captureQueryStrings ?? false
|
|
1033
|
+
captureConsoleArguments = options.captureConsoleArguments ?? false
|
|
997
1034
|
startVitals()
|
|
998
1035
|
startSession()
|
|
999
1036
|
component = pageComponent()
|
|
@@ -1028,7 +1065,7 @@ export function startRailwatch(options: RailwatchOptions = {}) {
|
|
|
1028
1065
|
}
|
|
1029
1066
|
current = {
|
|
1030
1067
|
started_at: Date.now(),
|
|
1031
|
-
url: v.url.toString(),
|
|
1068
|
+
url: pageUrl(v.url.toString()),
|
|
1032
1069
|
method: v.method,
|
|
1033
1070
|
partial: Boolean(v.only?.length || v.except?.length),
|
|
1034
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
|
|
@@ -60,12 +60,16 @@ module Railwatch
|
|
|
60
60
|
Rack::QueryParser::ParameterTypeError
|
|
61
61
|
].freeze
|
|
62
62
|
|
|
63
|
-
# What railwatch-
|
|
63
|
+
# What railwatch-sidecar's dashboard proxy inherits from unless the host
|
|
64
64
|
# names its own.
|
|
65
65
|
DEFAULT_BASE_CONTROLLER = "ActionController::Base"
|
|
66
66
|
|
|
67
|
+
# The roles railwatch-sidecar can hand a dashboard visitor.
|
|
68
|
+
DASHBOARD_ROLES = %w[admin member].freeze
|
|
69
|
+
|
|
67
70
|
attr_accessor :enabled, :token, :ingest_url, :allow_http, :server, :environment,
|
|
68
71
|
:http_basic_auth_enabled, :http_basic_auth_user, :http_basic_auth_password, :base_controller_class,
|
|
72
|
+
:capture_browser_query_strings, :capture_browser_console_arguments,
|
|
69
73
|
:sample, :log_level, :capture_request_payload,
|
|
70
74
|
:capture_exception_source, :capture_exception_locals, :redact_headers, :redact_params,
|
|
71
75
|
:buffer_size, :buffer_bytes, :execution_buffer_bytes, :batch_bytes,
|
|
@@ -88,13 +92,13 @@ module Railwatch
|
|
|
88
92
|
:capture_console, :interactive_runner_paths, :ignored_request_paths,
|
|
89
93
|
:capture_llm_content, :timing_headers, :browser_client
|
|
90
94
|
|
|
91
|
-
attr_reader :deploy, :deploy_source, :detect_deploy, :user_resolver, :beacon_user_resolver,
|
|
95
|
+
attr_reader :dashboard_default_role, :deploy, :deploy_source, :detect_deploy, :user_resolver, :beacon_user_resolver,
|
|
92
96
|
:fingerprint_resolver, :redactors, :rejectors, :before_ingest, :backpressure_high_water
|
|
93
97
|
|
|
94
98
|
def initialize
|
|
95
99
|
@enabled = env_bool("RAILWATCH_ENABLED", true)
|
|
96
100
|
@token = ENV["RAILWATCH_TOKEN"]
|
|
97
|
-
# The gate in front of the dashboard railwatch-
|
|
101
|
+
# The gate in front of the dashboard railwatch-sidecar serves at
|
|
98
102
|
# /railwatch, the way Mission Control Jobs does it: HTTP Basic
|
|
99
103
|
# authentication is on and CLOSED by default. With no user and password
|
|
100
104
|
# configured every dashboard request is 401, so an install that forgot
|
|
@@ -103,16 +107,22 @@ module Railwatch
|
|
|
103
107
|
# by `bin/rails railwatch:authentication:configure`), from these env
|
|
104
108
|
# vars, or by assignment here. A host with its own admin auth turns
|
|
105
109
|
# Basic off and names a base controller. Nothing here reads them unless
|
|
106
|
-
# railwatch-
|
|
110
|
+
# railwatch-sidecar is installed.
|
|
107
111
|
@http_basic_auth_enabled = env_bool("RAILWATCH_HTTP_BASIC_AUTH_ENABLED", true)
|
|
108
112
|
@http_basic_auth_user = ENV["RAILWATCH_HTTP_BASIC_AUTH_USER"]
|
|
109
113
|
@http_basic_auth_password = ENV["RAILWATCH_HTTP_BASIC_AUTH_PASSWORD"]
|
|
110
|
-
# railwatch-
|
|
114
|
+
# railwatch-sidecar's dashboard proxy inherits from this class, so a
|
|
111
115
|
# host's own before_actions (require an admin, redirect to sign-in) run
|
|
112
116
|
# in front of every page. The default authenticates nothing itself
|
|
113
117
|
# beyond HTTP Basic above.
|
|
114
118
|
@base_controller_class = ENV.fetch("RAILWATCH_BASE_CONTROLLER_CLASS", DEFAULT_BASE_CONTROLLER)
|
|
115
|
-
|
|
119
|
+
# The role railwatch-sidecar gives a dashboard visitor the app did not
|
|
120
|
+
# name (no Railwatch::Sidecar.config.user): the HTTP Basic user, or the
|
|
121
|
+
# one operator. A member, so a shared Basic password or a gate that
|
|
122
|
+
# turns out to be open does not hand out token, member and integration
|
|
123
|
+
# management. "admin" restores the old behaviour.
|
|
124
|
+
self.dashboard_default_role = ENV.fetch("RAILWATCH_DASHBOARD_DEFAULT_ROLE", "member")
|
|
125
|
+
@ingest_url = ENV.fetch("RAILWATCH_INGEST_URL", "https://app.railwatch.dev")
|
|
116
126
|
@allow_http = env_bool("RAILWATCH_ALLOW_HTTP", false)
|
|
117
127
|
@project_root = defined?(Rails) ? Rails.root : Dir.pwd
|
|
118
128
|
@detect_deploy = env_bool("RAILWATCH_DETECT_DEPLOY", true)
|
|
@@ -190,6 +200,14 @@ module Railwatch
|
|
|
190
200
|
# as Sentry's allowed domains: "https://app.example.com", or a host on
|
|
191
201
|
# its own. Empty means same-origin only.
|
|
192
202
|
@beacon_allowed_origins = ENV["RAILWATCH_BEACON_ALLOWED_ORIGINS"]&.split(",")&.map(&:strip)&.reject(&:empty?) || []
|
|
203
|
+
# A page's query string is where reset, magic-link and OAuth secrets
|
|
204
|
+
# ride, so the beacon keeps only the path of the page, the visit and
|
|
205
|
+
# each navigation unless an app opts in. The fragment is always dropped.
|
|
206
|
+
@capture_browser_query_strings = env_bool("RAILWATCH_CAPTURE_BROWSER_QUERY_STRINGS", false)
|
|
207
|
+
# What the page passed to console.error/console.warn is whatever it had
|
|
208
|
+
# in hand, user data included, so a console breadcrumb keeps only its
|
|
209
|
+
# level unless an app opts in.
|
|
210
|
+
@capture_browser_console_arguments = env_bool("RAILWATCH_CAPTURE_BROWSER_CONSOLE_ARGUMENTS", false)
|
|
193
211
|
@debug = env_bool("RAILWATCH_DEBUG", false)
|
|
194
212
|
# Tail-based sampling: a head-sampled-out execution is still kept when
|
|
195
213
|
# it ran at least this long, raised, or Railwatch.keep! was called. nil = off.
|
|
@@ -313,7 +331,7 @@ module Railwatch
|
|
|
313
331
|
# Whether the request carries the configured HTTP Basic credentials.
|
|
314
332
|
# False when Basic is on and nothing is configured (closed), true when
|
|
315
333
|
# Basic is off (the host's base controller is the gate then).
|
|
316
|
-
# railwatch-
|
|
334
|
+
# railwatch-sidecar's dashboard proxy calls it.
|
|
317
335
|
def http_basic_auth_ok?(request)
|
|
318
336
|
return true unless http_basic_auth_enabled
|
|
319
337
|
return true if http_basic_auth_waived?
|
|
@@ -325,6 +343,24 @@ module Railwatch
|
|
|
325
343
|
end == true
|
|
326
344
|
end
|
|
327
345
|
|
|
346
|
+
# Whether anything stands in front of railwatch-sidecar's dashboard:
|
|
347
|
+
# HTTP Basic (which refuses everyone until credentials exist), or a base
|
|
348
|
+
# controller of the host's own whose before_actions run first. False is
|
|
349
|
+
# Basic turned off with the base controller left at ActionController::Base,
|
|
350
|
+
# which serves the dashboard to anyone. railwatch-sidecar asks this
|
|
351
|
+
# (when the gem has it) and refuses to serve outside development.
|
|
352
|
+
def dashboard_gate_configured?
|
|
353
|
+
return true if http_basic_auth_enabled
|
|
354
|
+
|
|
355
|
+
base = base_controller_class.to_s.strip.delete_prefix("::")
|
|
356
|
+
base != "" && base != DEFAULT_BASE_CONTROLLER
|
|
357
|
+
end
|
|
358
|
+
|
|
359
|
+
def dashboard_default_role=(value)
|
|
360
|
+
role = value.to_s.strip.downcase
|
|
361
|
+
@dashboard_default_role = DASHBOARD_ROLES.include?(role) ? role : "member"
|
|
362
|
+
end
|
|
363
|
+
|
|
328
364
|
def ingest_url_allowed?
|
|
329
365
|
url_allowed?(ingest_url)
|
|
330
366
|
end
|
|
@@ -420,6 +456,32 @@ module Railwatch
|
|
|
420
456
|
end
|
|
421
457
|
end
|
|
422
458
|
|
|
459
|
+
# Settings of 0.x embedded mode, which 1.0 removed: the dashboard and its
|
|
460
|
+
# storage are railwatch-sidecar (or a railwatch-rs server) now. Assigning
|
|
461
|
+
# one raises with the migration instead of a bare NoMethodError.
|
|
462
|
+
EMBEDDED_MODE_SETTINGS = %i[
|
|
463
|
+
transport issue_prefix repository_url retention_days dashboard_user dashboard_open
|
|
464
|
+
writer_socket migration_busy_timeout
|
|
465
|
+
].freeze
|
|
466
|
+
|
|
467
|
+
EMBEDDED_MODE_MIGRATION = "Railwatch 1.0 removed embedded mode: this gem is the agent only, and the " \
|
|
468
|
+
"dashboard runs in railwatch-sidecar (gem \"railwatch-sidecar\" plus `plugin :railwatch_sidecar` in " \
|
|
469
|
+
"config/puma.rb) or a railwatch-rs server. See " \
|
|
470
|
+
"https://github.com/Rebulk/railwatch/blob/main/docs/getting-started.md#coming-from-0x-embedded-mode"
|
|
471
|
+
|
|
472
|
+
class RemovedSetting < NoMethodError; end
|
|
473
|
+
|
|
474
|
+
EMBEDDED_MODE_SETTINGS.each do |name|
|
|
475
|
+
define_method(:"#{name}=") do |_value|
|
|
476
|
+
raise RemovedSetting.new("[railwatch] `#{name}` was removed. #{EMBEDDED_MODE_MIGRATION}", :"#{name}=")
|
|
477
|
+
end
|
|
478
|
+
end
|
|
479
|
+
|
|
480
|
+
# The environment variable that turned embedded mode on, if it is still set.
|
|
481
|
+
def embedded_mode_env
|
|
482
|
+
"RAILWATCH_TRANSPORT" if ENV["RAILWATCH_TRANSPORT"].to_s.strip != ""
|
|
483
|
+
end
|
|
484
|
+
|
|
423
485
|
private
|
|
424
486
|
|
|
425
487
|
def detect_release
|