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