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.
@@ -7,13 +7,13 @@ nothing else has to be wired by hand.
7
7
  The `railwatch` gem is the agent: it instruments the app and sends what
8
8
  it records over HTTPS to a Railwatch server. The server is one of:
9
9
 
10
- - **Railwatch Cloud** at <https://railwatch.rebulk.com>, the default.
10
+ - **Railwatch Cloud** at <https://app.railwatch.dev>, the default.
11
11
  - **Your own [railwatch-rs](https://github.com/Rebulk/railwatch-rs)**,
12
12
  one static binary that serves many apps
13
13
  ([Self-hosting](self-hosting.md)).
14
- - **The [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
14
+ - **The [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar)
15
15
  gem**, which runs railwatch-rs next to Puma for this one app and serves
16
- the dashboard at `/railwatch` ([below](#embedded-railwatch-server)).
16
+ the dashboard at `/railwatch` ([below](#embedded-railwatch-sidecar)).
17
17
 
18
18
  ## Install
19
19
 
@@ -31,7 +31,7 @@ secret in shell history or process arguments:
31
31
  ```sh
32
32
  bin/rails generate railwatch:install \
33
33
  --prompt-token \
34
- --url=https://railwatch.rebulk.com \
34
+ --url=https://app.railwatch.dev \
35
35
  --kamal-secrets
36
36
  ```
37
37
 
@@ -42,7 +42,7 @@ bin/rails generate railwatch:install \
42
42
  deployment secret manager, or add `.env` to `.gitignore` first. Token values
43
43
  are never printed by the generator.
44
44
  - `--url=` sets `RAILWATCH_INGEST_URL`, for a self-hosted server. Leave
45
- it off to use the default, `https://railwatch.rebulk.com`.
45
+ it off to use the default, `https://app.railwatch.dev`.
46
46
  - `--kamal-secrets` appends `RAILWATCH_TOKEN=$RAILWATCH_TOKEN` to
47
47
  `.kamal/secrets` and adds `RAILWATCH_TOKEN` under `env: secret:` in
48
48
  `config/deploy.yml`, which is the pair of edits Kamal needs to pass a
@@ -108,9 +108,9 @@ bin/rails railwatch:doctor
108
108
  ```
109
109
  ✓ token: rw_9Qv... (43 chars)
110
110
  ✓ token storage: no tracked plaintext Railwatch token found
111
- ✓ ingest url: https://railwatch.rebulk.com
111
+ ✓ ingest url: https://app.railwatch.dev
112
112
  ✓ ingest transport security: HTTPS with certificate verification
113
- ✓ ingest reachable: GET https://railwatch.rebulk.com/ingest/ping
113
+ ✓ ingest reachable: GET https://app.railwatch.dev/ingest/ping
114
114
  ✓ request middleware: Railwatch::Middleware::Request at position 0
115
115
  ✓ engine mounted: POST /railwatch/beacon -> railwatch/beacon#create
116
116
  ✓ deploy: 8f31c0a42e91 (from GIT_REV)
@@ -128,22 +128,22 @@ to do about a `✗` is in [`troubleshooting.md`](troubleshooting.md).
128
128
  `bin/rails railwatch:status` is the one-line version: it pings
129
129
  `{ingest_url}/ingest/ping` and prints the ingest URL, deploy, and server.
130
130
 
131
- ## Embedded: railwatch-server
131
+ ## Embedded: railwatch-sidecar
132
132
 
133
133
  To keep telemetry inside the app instead, add the
134
- [`railwatch-server`](https://github.com/Rebulk/railwatch-server) gem
134
+ [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar) gem
135
135
  next to this one. It bundles the railwatch-rs binary for your platform,
136
136
  runs it as its own process beside Puma, and points this agent at it:
137
137
 
138
138
  ```ruby
139
139
  # Gemfile
140
140
  gem "railwatch"
141
- gem "railwatch-server"
141
+ gem "railwatch-sidecar"
142
142
  ```
143
143
 
144
144
  ```ruby
145
145
  # config/puma.rb
146
- plugin :railwatch_server
146
+ plugin :railwatch_sidecar
147
147
  ```
148
148
 
149
149
  On first boot it provisions `storage/railwatch/<env>` and sets the
@@ -158,23 +158,32 @@ RAILS_ENV=production bin/rails railwatch:authentication:configure
158
158
  ```
159
159
 
160
160
  To use your own admin authentication instead, turn Basic off and name a
161
- base controller ([Configuration](configuration.md#dashboard-gate-railwatch-server)).
161
+ base controller ([Configuration](configuration.md#dashboard-gate-railwatch-sidecar)).
162
162
  Everything else about it (ports, data directory, email, backups) is in
163
- the [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
163
+ the [railwatch-sidecar README](https://github.com/Rebulk/railwatch-sidecar#readme).
164
164
 
165
165
  ### Coming from 0.x embedded mode
166
166
 
167
167
  Railwatch 0.x could keep telemetry in two SQLite databases of the app's
168
168
  own, written by a Puma writer process, with the dashboard served from the
169
- gem. 1.0 removes that mode. To move:
169
+ gem. 1.0 removes that mode, and that Ruby dashboard is not coming back:
170
+ there is one Railwatch engine, railwatch-rs, whether it runs next to
171
+ Puma (railwatch-sidecar), on its own box, or as Railwatch Cloud. If you
172
+ upgrade without these steps, a removed setting in the initializer stops
173
+ boot with `Railwatch::Configuration::RemovedSetting`, and `plugin
174
+ :railwatch` stops Puma, both linking back here. A leftover
175
+ `RAILWATCH_TRANSPORT=local` does not stop boot: it is ignored with one
176
+ warning in the log, and the agent sends to its `ingest_url`, which is
177
+ Railwatch Cloud unless you set one. Your telemetry would then leave the
178
+ box, so do step 1 before deploying. To move:
170
179
 
171
180
  1. Remove `c.transport = :local` (or `RAILWATCH_TRANSPORT=local`) from
172
181
  the initializer and environment.
173
182
  2. Remove `plugin :railwatch` from `config/puma.rb`. Puma refuses to boot
174
- with a plugin it cannot find.
183
+ with it.
175
184
  3. Remove the `railwatch` and `railwatch_telemetry` entries from
176
185
  `config/database.yml`.
177
- 4. Add `railwatch-server` as above, or point the app at Railwatch Cloud
186
+ 4. Add `railwatch-sidecar` as above, or point the app at Railwatch Cloud
178
187
  or a self-hosted railwatch-rs.
179
188
 
180
189
  The old files (`storage/<env>_railwatch.sqlite3`,
@@ -194,7 +203,7 @@ Records are batched in-process and flushed every `flush_interval`
194
203
  (2 seconds by default) or every 500 records, whichever comes first, so
195
204
  the request shows up on the **Requests** page (the environment in
196
205
  Railwatch Cloud or your own server, or `/railwatch` with
197
- railwatch-server) a couple of seconds after you make it —
206
+ railwatch-sidecar) a couple of seconds after you make it —
198
207
  with its queries, cache reads, view renders, and log lines already
199
208
  attached to it.
200
209
 
@@ -233,7 +242,8 @@ createRoot(el, railwatchRootOptions()).render(<App {...props} />)
233
242
  On React 18, whose roots take no error options, call
234
243
  `reportError(error, { componentStack: info.componentStack })` from the
235
244
  boundary's `componentDidCatch` instead. `startRailwatch` also takes optional
236
- `ignoreErrors`, `denyUrls`, and `tenant` settings; see
245
+ `ignoreErrors`, `denyUrls`, `tenant`, `captureQueryStrings` and
246
+ `captureConsoleArguments` settings; see
237
247
  [`docs/configuration.md`](configuration.md) and
238
248
  [`docs/replacing-sentry.md`](replacing-sentry.md).
239
249
 
@@ -276,7 +286,7 @@ up, on the account.
276
286
 
277
287
  ## Deploying
278
288
 
279
- With railwatch-server, the server's data lives under
289
+ With railwatch-sidecar, the server's data lives under
280
290
  `storage/railwatch/<env>`, which has to be on a volume that survives
281
291
  deploys (the Rails 8 Kamal template mounts `storage/`); its README covers
282
292
  deploys and two containers sharing a volume. The token steps below are
@@ -321,7 +331,7 @@ Environment variables only:
321
331
 
322
332
  ```sh
323
333
  RAILWATCH_TOKEN=rw_...
324
- RAILWATCH_INGEST_URL=https://railwatch.rebulk.com # only when self-hosting
334
+ RAILWATCH_INGEST_URL=https://monitor.example.com # only when self-hosting: your server
325
335
  RAILWATCH_DEPLOY=<release identifier>
326
336
  ```
327
337
 
@@ -6,7 +6,7 @@ produced them, and a dashboard turns them into routes, jobs, queries,
6
6
  issues, and alerts. Railwatch Cloud is the hosted option; unlike
7
7
  Nightwatch, the server can also be self-hosted
8
8
  ([railwatch-rs](self-hosting.md)) or run inside your app with the
9
- [`railwatch-server`](getting-started.md#embedded-railwatch-server) gem.
9
+ [`railwatch-sidecar`](getting-started.md#embedded-railwatch-sidecar) gem.
10
10
  If you know Nightwatch, you already know how to read Railwatch — this page maps the vocabulary and points out the three
11
11
  places the Rails answer is genuinely different.
12
12
 
@@ -9,7 +9,7 @@ depends on a conditional row.
9
9
  Install Railwatch first ([`getting-started.md`](getting-started.md)); you
10
10
  can run both for a day if you want to compare, since neither knows about
11
11
  the other. The token steps below apply to Railwatch Cloud and to a
12
- self-hosted railwatch-rs; with the `railwatch-server` gem the token is
12
+ self-hosted railwatch-rs; with the `railwatch-sidecar` gem the token is
13
13
  set for you.
14
14
 
15
15
  ## Decide whether Railwatch covers your workload
@@ -411,8 +411,9 @@ startRailwatch({
411
411
  denyUrls: [/analytics\./],
412
412
  // Only if the app scopes tenants by path or subdomain: the beacon posts
413
413
  // to /railwatch/beacon, which is outside that scoping, so the server
414
- // cannot work the tenant out for itself.
415
- tenant: () => /^\/orgs\/([^/]+)/.exec(location.pathname)?.[1],
414
+ // cannot work the tenant out for itself. Return the hint the layout
415
+ // rendered with Railwatch.beacon_tenant_hint(tenant); a bare name is ignored.
416
+ tenant: () => document.querySelector<HTMLMetaElement>('meta[name="railwatch-tenant"]')?.content,
416
417
  })
417
418
  ```
418
419
 
@@ -564,7 +565,7 @@ hook matching `rails runner …` previews, or `sentry_runner_noise.rb` under
564
565
  | Inertia visit timing | Real browser page-visit duration, prop byte size, partial reloads, SSR time, and Core Web Vitals, from a client the generator installs. |
565
566
  | Spec matchers as a CI gate | `have_railwatch_queries`, `have_railwatch_n_plus_one`, `have_railwatch_outgoing_requests` fail the pull request that regresses a hot path. |
566
567
  | Zero app-DB writes | The gem holds records in memory and ships them from a background thread; a bench gate asserts no `INSERT`/`UPDATE`/`DELETE` ever originates in `lib/railwatch`. This is why it is safe on single-writer SQLite. |
567
- | A dashboard inside the app | The `railwatch-server` gem runs the server next to Puma and serves the whole dashboard at `/railwatch`, with no hosted service at all ([Getting started](getting-started.md#embedded-railwatch-server)). |
568
+ | A dashboard inside the app | The `railwatch-sidecar` gem runs the server next to Puma and serves the whole dashboard at `/railwatch`, with no hosted service at all ([Getting started](getting-started.md#embedded-railwatch-sidecar)). |
568
569
  | One SQLite database per environment | Railwatch Cloud stores each monitored environment's telemetry in its own database file, which makes retention pruning, backup, and restore per-environment operations. |
569
570
  | LLM calls | RubyLLM calls are recorded with tokens, cost, finish reason, tool calls and workflows, in the request or job that made them ([`records.md`](records.md#llm_call)). |
570
571
  | An MCP server | AI assistants can ask what broke after the last deploy, list slow routes, read an execution's timeline, and search logs ([`ai-and-mcp.md`](ai-and-mcp.md)). |
data/docs/security.md CHANGED
@@ -3,17 +3,17 @@
3
3
  This review covers the open-source gem that runs in a customer's Rails
4
4
  application. Railwatch Cloud is a separate service and is outside this review.
5
5
 
6
- ## Dashboard gate (railwatch-server)
6
+ ## Dashboard gate (railwatch-sidecar)
7
7
 
8
- The gem serves no dashboard. With the separate `railwatch-server` gem
8
+ The gem serves no dashboard. With the separate `railwatch-sidecar` gem
9
9
  installed, a dashboard showing every query, log line and exception the app
10
10
  recorded is proxied at `/railwatch`, and its gate is this gem's settings.
11
11
  HTTP Basic authentication is on by default. With no credentials configured,
12
12
  every dashboard request is 401 in every environment except development,
13
13
  where it is open. Credentials, once set, apply in development too. An app
14
14
  that turns Basic off gates the dashboard with its own `base_controller_class`,
15
- which railwatch-server's proxy controller inherits from. See
16
- [Configuration](configuration.md#dashboard-gate-railwatch-server).
15
+ which railwatch-sidecar's proxy controller inherits from. See
16
+ [Configuration](configuration.md#dashboard-gate-railwatch-sidecar).
17
17
 
18
18
  ## Transport
19
19
 
@@ -101,8 +101,8 @@ application/deployment secret and must not be committed.
101
101
  application-specific credentials and personal data.
102
102
  - Keep secrets out of exception messages, log text, source files, tenant ids,
103
103
  user resolvers, and custom context.
104
- - With railwatch-server, set dashboard credentials (or your own gate) before
105
- deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-server).
104
+ - With railwatch-sidecar, set dashboard credentials (or your own gate) before
105
+ deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-sidecar).
106
106
  - Use HTTPS in production and keep TLS verification enabled.
107
107
  - Put a request-body limit at the reverse proxy when the public beacon is
108
108
  enabled, and choose a shared cache if rate limits must span processes.
data/docs/self-hosting.md CHANGED
@@ -11,9 +11,9 @@ install, configuration, backups and upgrades are documented in its
11
11
  The gem doesn't care which server it talks to — point it at yours and
12
12
  everything works the same.
13
13
 
14
- For a single app, the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
14
+ For a single app, the [`railwatch-sidecar`](https://github.com/Rebulk/railwatch-sidecar)
15
15
  gem runs that same server next to Puma and wires this gem to it, with no
16
- host to set up; see [Getting started](getting-started.md#embedded-railwatch-server).
16
+ host to set up; see [Getting started](getting-started.md#embedded-railwatch-sidecar).
17
17
  The rest of this page is for a server on its own host.
18
18
 
19
19
  ## Point the gem at your server
@@ -26,7 +26,7 @@ Railwatch.configure do |c|
26
26
  end
27
27
  ```
28
28
 
29
- `ingest_url` defaults to `https://railwatch.rebulk.com`, so this is the one
29
+ `ingest_url` defaults to `https://app.railwatch.dev`, so this is the one
30
30
  setting a self-hosted install always needs; everything the gem sends —
31
31
  records, ping, deploys — hangs off that host. Pass `--url=` to the
32
32
  installer to have it written for you:
data/docs/testing.md CHANGED
@@ -28,7 +28,7 @@ require "railwatch/minitest"
28
28
 
29
29
  Railwatch must be *enabled* in the test environment or every block would look
30
30
  empty, and it is enabled only with a token present: set any non-blank
31
- `RAILWATCH_TOKEN` for the test env. railwatch-server is off under
31
+ `RAILWATCH_TOKEN` for the test env. railwatch-sidecar is off under
32
32
  `Rails.env.test` and does not set one for you. Records go to an
33
33
  in-memory transport, never over the network, and there is no database to
34
34
  prepare. If Railwatch is disabled, the matchers raise
@@ -45,7 +45,7 @@ the engine's `railwatch.subscribe` initializer returns early, so no
45
45
  subscribers and no patches are installed at all. Fix: set
46
46
  `RAILWATCH_TOKEN`, restart, and re-run `railwatch:doctor`. The `token`
47
47
  line prints the first 6 characters and the length, which is enough to
48
- spot a truncated or quoted value. With railwatch-server installed, the
48
+ spot a truncated or quoted value. With railwatch-sidecar installed, the
49
49
  token is set when the server's data directory is provisioned; its boot
50
50
  log line says whether the agent was wired.
51
51
 
@@ -7,7 +7,7 @@ require "rails/generators"
7
7
  module Railwatch
8
8
  module Generators
9
9
  # Points the coding agents working on this app at its development
10
- # Railwatch: the MCP server the railwatch-server gem serves at
10
+ # Railwatch: the MCP server the railwatch-sidecar gem serves at
11
11
  # <mount>/mcp (no token needed from this machine in development), and a
12
12
  # short note on the dev loop. Every file it touches is either its own or
13
13
  # changed only between its markers, so it can be re-run after an upgrade.
@@ -72,7 +72,7 @@ module Railwatch
72
72
  Railwatch MCP for this app (development): #{mcp_url}
73
73
  Claude Code reads .mcp.json and asks once before it uses a project server.
74
74
  Other clients: add the same URL as a streamable HTTP MCP server.
75
- No token is needed from this machine in development (railwatch-server).
75
+ No token is needed from this machine in development (railwatch-sidecar).
76
76
  Anywhere else, send one: Authorization: Bearer rwp_... (Settings -> Profile).
77
77
  STEPS
78
78
  end
@@ -121,7 +121,7 @@ module Railwatch
121
121
  dashboard_url.delete_suffix(mount_path)
122
122
  end
123
123
 
124
- # The slug railwatch-server gives the app it provisions: the app's
124
+ # The slug railwatch-sidecar gives the app it provisions: the app's
125
125
  # module name, parameterized.
126
126
  def app_slug
127
127
  name = defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : File.basename(destination_root)
@@ -129,7 +129,8 @@ module Railwatch
129
129
  end
130
130
 
131
131
  def mount_path
132
- path = defined?(Railwatch::Server) && Railwatch::Server.respond_to?(:config) ? Railwatch::Server.config.normalized_mount_path : "/railwatch"
132
+ server = [ "Sidecar", "Server" ].filter_map { |n| Railwatch.const_get(n) if Railwatch.const_defined?(n, false) }.find { _1.respond_to?(:config) }
133
+ path = server ? server.config.normalized_mount_path : "/railwatch"
133
134
  path.to_s.empty? ? "/railwatch" : path
134
135
  end
135
136
 
@@ -1,7 +1,7 @@
1
1
  ## Railwatch (performance and errors, in development)
2
2
 
3
3
  Every request, job and command this app runs in development is recorded by
4
- the `railwatch` gem into the server `railwatch-server` runs beside it: SQL
4
+ the `railwatch` gem into the server `railwatch-sidecar` runs beside it: SQL
5
5
  (with the `file:line` that ran it), N+1s, views, logs and exceptions, all
6
6
  linked to one execution.
7
7
 
@@ -10,14 +10,14 @@ module Railwatch
10
10
 
11
11
  desc "Creates config/initializers/railwatch.rb, a Kamal post-deploy hook, the browser client, and wires the test helpers. " \
12
12
  "Telemetry goes to Railwatch Cloud, or to a self-hosted Railwatch server with --url. " \
13
- "To run the server inside this app instead, add the railwatch-server gem."
13
+ "To run the server inside this app instead, add the railwatch-sidecar gem."
14
14
 
15
15
  class_option :prompt_token, type: :boolean, default: false,
16
16
  desc: "Prompt for the ingest token without echoing it."
17
17
  class_option :token_stdin, type: :boolean, default: false,
18
18
  desc: "Read the ingest token from one line on standard input."
19
19
  class_option :url, type: :string,
20
- desc: "Ingest URL, for a self-hosted Railwatch server. Defaults to https://railwatch.rebulk.com."
20
+ desc: "Ingest URL, for a self-hosted Railwatch server. Defaults to https://app.railwatch.dev."
21
21
  class_option :kamal_secrets, type: :boolean, default: false,
22
22
  desc: "Wire RAILWATCH_TOKEN through .kamal/secrets and config/deploy.yml's `env: secret:` list."
23
23
  class_option :doctor, type: :boolean, default: true,
@@ -179,9 +179,9 @@ module Railwatch
179
179
  4. Gate performance in CI: see docs/testing.md.
180
180
 
181
181
  Want the dashboard inside this app instead, with no token? Add the
182
- railwatch-server gem (gem "railwatch-server", then
183
- `plugin :railwatch_server` in config/puma.rb):
184
- https://github.com/Rebulk/railwatch-server
182
+ railwatch-sidecar gem (gem "railwatch-sidecar", then
183
+ `plugin :railwatch_sidecar` in config/puma.rb):
184
+ https://github.com/Rebulk/railwatch-sidecar
185
185
  STEPS
186
186
  end
187
187
 
@@ -4,7 +4,7 @@
4
4
  # set by the RAILWATCH_* env var named in the comment.
5
5
  Railwatch.configure do |c|
6
6
  # c.token = ENV["RAILWATCH_TOKEN"] # RAILWATCH_TOKEN (required)
7
- # c.ingest_url = "https://railwatch.rebulk.com" # RAILWATCH_INGEST_URL; your own server when self-hosting
7
+ # c.ingest_url = "https://app.railwatch.dev" # RAILWATCH_INGEST_URL; your own server when self-hosting
8
8
  # c.deploy = "release-name" # RAILWATCH_DEPLOY; platform/Git auto-detected
9
9
  # c.detect_deploy = false # RAILWATCH_DETECT_DEPLOY; default true
10
10
 
@@ -45,9 +45,12 @@ case "$INGEST" in
45
45
  ;;
46
46
  esac
47
47
 
48
+ # The token goes to curl on stdin (-H @-), not in its arguments, which any
49
+ # user on the deployer can read with `ps`. printf is a shell builtin, so it
50
+ # never appears in a process list either.
48
51
  post() {
49
- curl -sS -m 10 -X POST "$1" \
50
- -H "Authorization: Bearer $RAILWATCH_TOKEN" \
52
+ printf 'Authorization: Bearer %s\n' "$RAILWATCH_TOKEN" | curl -sS -m 10 -X POST "$1" \
53
+ -H @- \
51
54
  -H "Content-Type: application/json" \
52
55
  -d "$2" >/dev/null 2>&1 || true
53
56
  }
@@ -78,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, so
82
- // it follows the user across tenants without a page load.
81
+ // so the server cannot work this out for itself. Read on every flush:
82
+ // return the current tenant's hint, signed by the server with
83
+ // Railwatch.beacon_tenant_hint(tenant) (in an Inertia app, a shared prop
84
+ // read from the current page; a layout meta tag only changes on a full
85
+ // page load). The beacon ignores a bare tenant name, which anyone could
86
+ // send.
83
87
  tenant?: () => string | undefined
88
+ // Send each page's query string. Off: reset, magic-link and OAuth secrets
89
+ // ride there. The server keeps one only when
90
+ // config.capture_browser_query_strings is on too. Fragments are never sent.
91
+ captureQueryStrings?: boolean
92
+ // Put what the page passed to console.error/console.warn in a breadcrumb.
93
+ // Off: the crumb says only "error" or "warn". The server keeps the
94
+ // arguments only when config.capture_browser_console_arguments is on too.
95
+ captureConsoleArguments?: boolean
84
96
  }
85
97
 
86
98
  // Browser noise that is never actionable: ResizeObserver fires from benign
@@ -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 ?? "").trim().replace(/\s+/g, " ").slice(0, 80)
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("console", `${level}: ${args.map(stringify).join(" ")}`)
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: location.pathname + location.search,
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: location.pathname + location.search,
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-server's dashboard proxy checks in the current
7
+ # credentials railwatch-sidecar's dashboard proxy checks in the current
8
8
  # environment's Rails credentials, the same way Mission Control Jobs'
9
9
  # authentication:configure does. Asks for a user, generates the password,
10
10
  # appends a `railwatch:` entry to the credentials file the environment
@@ -60,12 +60,16 @@ module Railwatch
60
60
  Rack::QueryParser::ParameterTypeError
61
61
  ].freeze
62
62
 
63
- # What railwatch-server's dashboard proxy inherits from unless the host
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-server serves at
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-server is installed.
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-server's dashboard proxy inherits from this class, so a
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
- @ingest_url = ENV.fetch("RAILWATCH_INGEST_URL", "https://railwatch.rebulk.com")
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-server's dashboard proxy calls it.
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