rails_mind 0.3.1 → 0.4.0
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/CHANGELOG.md +35 -1
- data/CONTRIBUTING.md +6 -7
- data/README.md +11 -6
- data/docs/compatibility.md +31 -14
- data/docs/sdk.md +141 -39
- data/lib/generators/rails_mind/install/install_generator.rb +0 -12
- data/lib/generators/rails_mind/install/templates/initializer.rb.tt +8 -1
- data/lib/rails_mind/client.rb +3 -2
- data/lib/rails_mind/configuration.rb +8 -2
- data/lib/rails_mind/context.rb +8 -2
- data/lib/rails_mind/diagnostic.rb +18 -3
- data/lib/rails_mind/integrations/rails.rb +76 -9
- data/lib/rails_mind/page_view.rb +176 -0
- data/lib/rails_mind/redactor.rb +127 -12
- data/lib/rails_mind/transport.rb +14 -0
- data/lib/rails_mind/version.rb +1 -1
- data/lib/rails_mind/visitor.rb +134 -0
- data/lib/tasks/rails_mind.rake +8 -2
- metadata +5 -5
- data/javascript/rails_mind.js +0 -49
- data/lib/rails_mind/integrations/ahoy.rb +0 -68
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a103d267eb59347fc396eca15f1bb522befc858a0c45de9edebe16c90ef9ba65
|
|
4
|
+
data.tar.gz: 443a55baa5f6a775f9286ed50c3bfda99ecfd29cae9f58b2ede3d2baeeb65fbd
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 658d0c05e2cbd3dd7ee762584101a1a38d289e6684f3f2c449041f5e10f80f0b8cf4083a7eb4c52a492371b83b9f52872a34f3b7dd38092225530b8013f10ef4
|
|
7
|
+
data.tar.gz: fd4db2f36c177bc2e561e5a70478ee932e1827cf254979577ccc9ccddc75284293253f1ed63f3bebc7985824435c6cbae6248a85afcff0bd77a1b8d2ac0eb3a3
|
data/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 0.
|
|
3
|
+
## 0.4.0 — 2026-11-06
|
|
4
|
+
|
|
5
|
+
Breaking: the Ahoy integration and the Ahoy-based browser adapter are gone. RailsMind counts page views itself. An app that keeps Ahoy for its own reports keeps it unchanged.
|
|
6
|
+
|
|
7
|
+
- Removed `RailsMind::Integrations::AhoyStore`, `AhoyMirror` and `RailsMind::Integrations.mirror_ahoy!`. `require "rails_mind/integrations/ahoy"` now raises `LoadError`, so delete that require and the `mirror_ahoy!` call before upgrading or the app fails at boot. `rails_mind:doctor` names them when it finds `ahoy_matey`.
|
|
8
|
+
- Removed the browser adapter (`javascript/rails_mind.js`) and `rails_mind:install --browser`; the option is now ignored. Delete the copied `app/javascript/rails_mind.js`, its importmap pin, the `import { start } from "rails_mind"` line and the `start(...)` call in your JavaScript entry point (an import left without its pin stops the whole entry point from loading), any asset path into the gem and the `rails-mind-page` meta tag. Custom events sent from the browser are no longer supported; record them on the server.
|
|
9
|
+
- RailsMind no longer receives `$visit`, `$view`, `$pageview`, `$frame_view` or `$identify`.
|
|
10
|
+
- Migrating: `ahoy.track("Invoice paid", ...)` becomes `RailsMind.track("Invoice paid", ...)`, called after the outcome commits. Ahoy's `authenticate(user)` becomes `RailsMind.identify(user_id:, account_id:)`; stop passing `visitor_id: ahoy.visitor_token`. A hosted-only `Ahoy::Store < RailsMind::Integrations::AhoyStore` goes: remove `ahoy_matey` too, or define `class Ahoy::Store < Ahoy::BaseStore; end`. Keep any `ahoy.track` and `ahoy.authenticate` calls your own Ahoy reports need.
|
|
11
|
+
- A Gemfile pin of `~> 0.3.x` does not allow 0.4.0. 0.4.0 needs a RailsMind server that accepts the `pageview` kind; an older one rejects every batch that contains a page view.
|
|
12
|
+
- Upgrading turns page views and the `_rails_mind_visitor` cookie on. If your privacy notice or cookie consent lists the cookies your app sets, update it before you deploy, or set `config.visitor_cookie = false` (no cookie) or `config.page_views = false`.
|
|
13
|
+
|
|
14
|
+
Page views:
|
|
15
|
+
|
|
16
|
+
- Count a page view, a new `pageview` event named `Controller#action`, for each HTML page a controller renders for a person: a GET answered with a 2xx `text/html` response that is not a Turbo Frame request, a prefetch (`Sec-Purpose` or `X-Sec-Purpose`), an XHR, a `Rails::` or `ActiveStorage::` controller (the `/up` health check included), or from a blank or known-bot user agent. Page views share the request event's trace and request IDs and are never sampled.
|
|
17
|
+
- Each carries the route pattern, the path and query with the app's `filter_parameters` applied, the host, the referrer's scheme, host and path (never its query), the `utm_*` and `ref` query parameters unless `filter_parameters` masks them, the user agent, the country from `CF-IPCountry` or `CloudFront-Viewer-Country`, and which kind of visitor ID it has. Every string is capped. The IP address is never sent.
|
|
18
|
+
- Keep a random visitor ID in a first-party cookie, `_rails_mind_visitor` (a UUID, two years, `HttpOnly`, `SameSite=Lax`, `Secure` over HTTPS), set or refreshed on counted page views and never on a `Cache-Control: public` or `ActionController::Live` response. Every event of the request, `RailsMind.track` calls and enqueued jobs included, carries the same ID, so an anonymous visit can lead to an outcome. A request that cannot become a page view (a POST, a JSON or API GET, a Turbo Frame, an XHR, a prefetch) gets no new ID. On a public or Live response to a visitor without the cookie, the page view carries the daily hash and the request's other events a fresh ID that is never stored. A value that is not a UUID is replaced. `config.visitor_cookie = false` reads and sets no cookie and uses a daily hash instead: an HMAC of the local date, IP and user agent keyed from `secret_key_base`, which changes every day.
|
|
19
|
+
- Link visitors to users: page views carry the user and account IDs `identify` set, and `identify` now keeps the request's visitor ID when `visitor_id:` is not passed (passing it still replaces it, and `nil` clears it). `identify` still sends nothing itself; RailsMind links a visitor to a user from a page view or a `RailsMind.track` event carrying both (request, job and error events never link). `config.link_page_views_to_users = false` keeps user and account IDs off page views; `RailsMind.track` calls after `identify` still carry both and still link the visitor to the user.
|
|
20
|
+
- Name the app's time zone (`config.time_zone` as an IANA name, `Etc/UTC` by default) in an `X-RailsMind-Time-Zone` header on every batch, so RailsMind counts days in it.
|
|
21
|
+
- New switches, set in code and never read from the environment: `config.page_views`, `config.visitor_cookie`, `config.link_page_views_to_users` (each `true` by default and validated as a boolean) and `config.ignore_page_view`, a callable that receives the request and skips the page view when it returns true or raises. `rails_mind:doctor` reports the three switches.
|
|
22
|
+
- Known limits: Turbo broadcast page refreshes reload a page the way a visit does, so each refresh counts as a page view in every open tab. Turbo 8 shows a link's hover prefetch when it is clicked, without a new request; prefetches are not counted, so those visits are not either unless the layout turns prefetch off (`<meta name="turbo-prefetch" content="false">`). A repeat view the controller answers with `304 Not Modified` (`fresh_when`, `stale?`) is not counted; one `Rack::ConditionalGet` answers is.
|
|
23
|
+
|
|
24
|
+
## 0.3.2 — 2026-10-13
|
|
25
|
+
|
|
26
|
+
Security fix for the scrubbing 0.3.1 turned on by default. Upgrade from 0.3.1.
|
|
27
|
+
|
|
28
|
+
- An `Authorization` header in a message or string (`Bearer`, `Basic`, `Token` and other schemes; any case; `:`, `=` or `=>`; quoted, unquoted or wrapped in an array as `Net::HTTP#to_hash` prints it; `Proxy-Authorization` too) loses its credential. A `Digest` or `AWS4-HMAC-SHA256` header loses its whole value. 0.3.1 replaced only the scheme word and sent the credential after it.
|
|
29
|
+
- Userinfo goes from a URL of any scheme (`redis://:password@`, `rediss://`, `amqp://`, `postgres://`, `mysql2://`, `mongodb+srv://` and others), not only `http(s)://`, up to the last `@` before the path, so an unencoded `@` in a password leaves nothing behind.
|
|
30
|
+
- Provider credentials go without a key word next to them: GitHub tokens (`ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_`), AWS access key IDs (`AKIA`, `ASIA`), Stripe secret and restricted keys (`sk_live_`, `sk_test_`, `rk_…`), Slack tokens (`xox…-`), `sk-` API keys and JWTs.
|
|
31
|
+
- Card numbers (13 to 19 digits, grouped by spaces or dashes or not, passing the Luhn check, also next to an expiry or another number) and US social security numbers (`123-45-6789`) go from free text: messages, backtraces, event names and properties. Identity, correlation and release values (`user_id`, `account_id`, `visitor_id`, `request_id`, `release` and the like) are left alone, so a numeric account ID is never mistaken for a card. In printed hashes, `phone` and `ssn` values go too.
|
|
32
|
+
- Scrubbing reads at most 8 KB of a string, cut at whitespace, and every pass is linear, so a hostile message cannot stall the request that raised it. What is sent is still at most 1024 characters.
|
|
33
|
+
- A PostgreSQL literal ending in a backslash no longer lets the next literal through, in query shapes or database error messages. Rails runs PostgreSQL with `standard_conforming_strings`, where `\` escapes a quote only inside `E'…'`, while MySQL lets it escape one; a statement or message containing a backslash is now read both ways and anything either reading takes for a literal goes. Statements without a backslash keep their fingerprints; one with an ambiguous `\'` keeps its text only up to that literal, so its fingerprint changes.
|
|
34
|
+
- Tests: an adversarial corpus of these inputs that no secret may survive, as a message, an event property or a query shape.
|
|
35
|
+
- `rails_mind:doctor` now exits 1 and names `RAILS_MIND_KEY` or the endpoint when collection would be off.
|
|
36
|
+
|
|
37
|
+
## 0.3.1 — 2026-10-11
|
|
4
38
|
|
|
5
39
|
- Send exception messages by default, scrubbed like every other string (emails, credentials, URL queries), and further for what generic scrubbing misses: database errors lose the failing row, key values, rejected input and quoted SQL literals, and printed hashes or keyword arguments lose the values of sensitive keys. `config.capture_exception_message = false` restores the placeholder. The flag is still not validated, so an app that assigned it from ENV boots as before.
|
|
6
40
|
- Send the shape of each repeated query next to its fingerprint: the normalized SQL with literals replaced by `?`, comments removed, and at most 400 characters and 900 bytes, only for fingerprints that repeated within the request. One pass handles doubled and backslash-escaped quotes, `E''` and `$$` strings, hex numbers, comments containing quotes, a literal left open where a long statement is cut, and MySQL's double-quoted strings. `config.capture_query_shapes = false` sends fingerprints only.
|
data/CONTRIBUTING.md
CHANGED
|
@@ -1,19 +1,18 @@
|
|
|
1
1
|
# Developing RailsMind
|
|
2
2
|
|
|
3
|
-
This repository owns the MIT-licensed client SDK,
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
This repository owns the MIT-licensed client SDK, tests, and SDK documentation.
|
|
4
|
+
The hosted RailsMind application and its internal integration sample are
|
|
5
|
+
maintained separately and remain proprietary.
|
|
6
6
|
|
|
7
7
|
## Setup
|
|
8
8
|
|
|
9
|
-
CI uses Ruby 4.0.6
|
|
9
|
+
CI uses Ruby 4.0.6. Native workflow tests have also been run locally on Ruby 4.0.7; use the committed lockfile.
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
12
|
git clone https://github.com/cmartyn/rails_mind.git
|
|
13
13
|
cd rails_mind
|
|
14
14
|
bundle install
|
|
15
15
|
bundle exec rake test
|
|
16
|
-
node --test javascript/rails_mind.test.js
|
|
17
16
|
bundle exec ruby script/package_smoke.rb
|
|
18
17
|
```
|
|
19
18
|
|
|
@@ -37,7 +36,7 @@ read this public repository.
|
|
|
37
36
|
## Packaging and releases
|
|
38
37
|
|
|
39
38
|
`bundle exec ruby script/package_smoke.rb` builds a temporary gem and exercises its
|
|
40
|
-
packaged installer,
|
|
39
|
+
packaged installer, page views, and native workflow integrations. `bundle exec rake build` writes the gem to
|
|
41
40
|
`pkg/`. Neither command publishes anything.
|
|
42
41
|
|
|
43
42
|
Publishing uses [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/)
|
|
@@ -70,7 +69,7 @@ git tag -a v0.2.0 -m "Release rails_mind 0.2.0"
|
|
|
70
69
|
git push origin v0.2.0
|
|
71
70
|
```
|
|
72
71
|
|
|
73
|
-
The workflow verifies the tag/version, reruns the Ruby
|
|
72
|
+
The workflow verifies the tag/version, reruns the Ruby and package
|
|
74
73
|
checks, then publishes to RubyGems.org. Confirm the published version can be
|
|
75
74
|
installed before announcing the release. Published version numbers cannot be
|
|
76
75
|
reused; fixes need a new version.
|
data/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# RailsMind SDK
|
|
2
2
|
|
|
3
3
|
The MIT-licensed Ruby client for [RailsMind](https://railsmind.com). One bounded
|
|
4
|
-
collector for Rails requests, errors, jobs, mailer attempts,
|
|
5
|
-
observations, and selected OpenTelemetry spans. Version 0.
|
|
4
|
+
collector for Rails page views, requests, errors, jobs, mailer attempts, Flipper
|
|
5
|
+
observations, and selected OpenTelemetry spans. Version 0.4.0 is an early release; see
|
|
6
6
|
[compatibility and validation limits](docs/compatibility.md).
|
|
7
7
|
|
|
8
8
|
```ruby
|
|
9
|
-
gem "rails_mind", "~> 0.
|
|
9
|
+
gem "rails_mind", "~> 0.4.0"
|
|
10
10
|
```
|
|
11
11
|
|
|
12
12
|
Install from RubyGems.org and commit your application's `Gemfile.lock` to pin the
|
|
@@ -19,7 +19,6 @@ and [release notes](CHANGELOG.md).
|
|
|
19
19
|
bundle install
|
|
20
20
|
bin/rails generate rails_mind:install --plan
|
|
21
21
|
bin/rails generate rails_mind:install
|
|
22
|
-
bin/rails rails_mind:doctor
|
|
23
22
|
```
|
|
24
23
|
|
|
25
24
|
Set **`RAILS_MIND_KEY`** for the destination application environment. It is the only
|
|
@@ -29,7 +28,14 @@ app's deployed `REVISION` file; telemetry still works when none is available.
|
|
|
29
28
|
`RAILS_MIND_ENDPOINT` and `RAILS_MIND_RELEASE` are optional overrides. See
|
|
30
29
|
[configuration and release detection](docs/sdk.md#configuration-and-release-detection).
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
With the key in the app's environment, check the effective settings. Until the
|
|
32
|
+
key is set, doctor names it and exits non-zero.
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
bin/rails rails_mind:doctor
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Next, run `bin/rails rails_mind:verify` on the app's
|
|
33
39
|
server. Match its check ID in RailsMind **Setup** and wait for **Check processed**.
|
|
34
40
|
Then visit the app to confirm real traffic. This command sends one labeled
|
|
35
41
|
diagnostic check, consumes one event of quota, and leaves business/performance
|
|
@@ -62,7 +68,6 @@ Tests:
|
|
|
62
68
|
```sh
|
|
63
69
|
bundle install
|
|
64
70
|
bundle exec rake test
|
|
65
|
-
node --test javascript/rails_mind.test.js
|
|
66
71
|
bundle exec ruby script/package_smoke.rb
|
|
67
72
|
ruby script_benchmark.rb
|
|
68
73
|
```
|
data/docs/compatibility.md
CHANGED
|
@@ -5,25 +5,23 @@ Verified on 2026-09-14. Version numbers come from RubyGems release metadata and
|
|
|
5
5
|
| Foundation | Verified version / license | Current coverage |
|
|
6
6
|
| --- | --- | --- |
|
|
7
7
|
| Ruby / Rails | 4.0.6 / 8.1.3.1; Ruby / MIT | Real Rails sample and notification/error/ActiveJob tests. Gem allows Ruby ≥3.3, Rails ≥7.2 and <9; older combinations are candidates, not yet certified. |
|
|
8
|
-
| Ahoy | [5.5.0, MIT](https://rubygems.org/gems/ahoy_matey) | Actual custom store and mirror tests; default store data/return value preserved; stable IDs; no hosted-only analytics tables. |
|
|
9
8
|
| Flipper | [1.4.2, MIT](https://rubygems.org/gems/flipper) | Actual group targeting and adapter identity preserved; ActiveSupport observation only. No managed flag mode. |
|
|
10
9
|
| OpenTelemetry SDK | [1.13.0, Apache-2.0](https://rubygems.org/gems/opentelemetry-sdk) | Existing exporter/provider and sampler coexistence tested; sampled-out traces do not suppress errors/business events. |
|
|
11
10
|
| OTel Rails components | [0.42.0 aggregate, Apache-2.0](https://rubygems.org/gems/opentelemetry-instrumentation-rails) | Sample selects Rack 0.31.1, ActionPack 0.18.1, ActionView 0.13.0, ActiveJob 0.13.0. Request/SQL/job telemetry through actual libraries. |
|
|
12
11
|
| OTel PG / Net::HTTP | [0.37.0](https://rubygems.org/gems/opentelemetry-instrumentation-pg) / [0.29.0](https://rubygems.org/gems/opentelemetry-instrumentation-net_http), Apache-2.0 | PG statements omitted; exporter allowlist discards raw SQL/HTTP payloads. Net::HTTP auto-instrumentation installed in the sample; external HTTP service interaction not required for the demo. |
|
|
13
12
|
| GoodJob | [4.19.2, MIT](https://rubygems.org/gems/good_job) | Hosted/sample backend; ActiveJob context integration. Sample uses inline execution, so multi-process GoodJob queue/retry behavior needs staging verification. |
|
|
14
|
-
| Turbo |
|
|
13
|
+
| Turbo | Request headers only | Page views skip `Turbo-Frame` requests and `Sec-Purpose`/`X-Sec-Purpose: prefetch`. Broadcast page refreshes count as page views. No browser code ships since 0.4.0. |
|
|
15
14
|
| Other error reporters | Rails error interface; no mandatory SDK | Subscriber coexistence tested with a second subscriber. Sentry/Honeybadger/Bugsnag/Rollbar detection only; no vendor-specific version certification. |
|
|
16
15
|
| Sidekiq, Solid Queue, Delayed Job | Detection only | ActiveJob jobs inherit the shared integration when used through Rails; backend-specific APIs/direct jobs are not covered. |
|
|
17
16
|
| Bullet / Prosopite | Optional, deferred dependency | Use in development/isolated reproduction. No automatic production scans or forks. |
|
|
18
17
|
| Field Test | Optional, deferred dependency | Detect installed version; no assignment/exposure/import or experiment analysis in this release. |
|
|
19
18
|
|
|
20
|
-
Current
|
|
19
|
+
Current OTel 1.13 requires Ruby ≥3.3. No integration gems are mandatory at SDK runtime beyond Rails and Net::HTTP. Customers select optional dependencies; the installer does not silently add them. MIT/Apache licenses allow this extension strategy without maintaining forks.
|
|
21
20
|
|
|
22
|
-
The preferred foundations remain suitable for the pilot.
|
|
21
|
+
The preferred foundations remain suitable for the pilot. Flipper's authoritative configuration remains in the customer's existing adapter; managed flags need an explicit future mode. OTel Ruby tracing supplies the useful mature signal here; broad metrics/logs/exporter parity is deliberately outside this prototype. [Flipper observation contract](https://www.flippercloud.io/docs/instrumentation), [OpenTelemetry Ruby](https://opentelemetry.io/docs/languages/ruby/).
|
|
23
22
|
|
|
24
|
-
Tests are in `test
|
|
25
|
-
|
|
26
|
-
part of this public repository. Re-run the matrix when bumping dependencies.
|
|
23
|
+
Tests are in `test`. Historical end-to-end Rails checks used a separate internal
|
|
24
|
+
sample application that is not part of this public repository. Re-run the matrix when bumping dependencies.
|
|
27
25
|
No external telemetry service, vendor account, historical migration, production
|
|
28
26
|
overhead budget, or published gem installation has been verified by those checks.
|
|
29
27
|
|
|
@@ -34,17 +32,19 @@ The local sample-to-hosted HTTP/GoodJob path was exercised with 101 accepted and
|
|
|
34
32
|
```sh
|
|
35
33
|
bundle install
|
|
36
34
|
bundle exec rake test
|
|
37
|
-
node --test javascript/rails_mind.test.js
|
|
38
35
|
bundle exec ruby script/package_smoke.rb
|
|
39
36
|
```
|
|
40
37
|
|
|
41
|
-
CI runs Ruby 4.0.6 / the locked Rails 8.1.4 dependencies on Linux
|
|
42
|
-
|
|
43
|
-
and runs the installer and native workflow tests against its packaged
|
|
38
|
+
CI runs Ruby 4.0.6 / the locked Rails 8.1.4 dependencies on Linux. The package
|
|
39
|
+
smoke check builds and installs a gem in a temporary directory, loads that copy,
|
|
40
|
+
and runs the installer, page-view and native workflow tests against its packaged
|
|
41
|
+
files.
|
|
44
42
|
The sample app remains in the hosted application's repository with its own lockfile.
|
|
45
43
|
|
|
46
44
|
## 0.1.0 release verification
|
|
47
45
|
|
|
46
|
+
The browser adapter and Ahoy integration checked here were removed in 0.4.0.
|
|
47
|
+
|
|
48
48
|
Rechecked on 2026-09-25 with Ruby 4.0.6, the locked Rails 8.1.3.1 dependencies,
|
|
49
49
|
and Node 22:
|
|
50
50
|
|
|
@@ -99,9 +99,10 @@ service exposes bounded workflow metadata and leaves recipient delivery unknown.
|
|
|
99
99
|
|
|
100
100
|
The Ruby suite passes locally with Ruby 4.0.7 and the locked Rails 8.1.4
|
|
101
101
|
libraries: 105 tests and 1,311 assertions, with no failures or skips. The three
|
|
102
|
-
Node browser-adapter contract tests also
|
|
103
|
-
tests; they do not boot a Rails application or use
|
|
104
|
-
runs the packaged-gem installation smoke check on Ruby
|
|
102
|
+
Node browser-adapter contract tests also passed; the adapter was removed in 0.4.0.
|
|
103
|
+
These are isolated SDK/library tests; they do not boot a Rails application or use
|
|
104
|
+
a database. CI separately runs the packaged-gem installation smoke check on Ruby
|
|
105
|
+
4.0.6.
|
|
105
106
|
|
|
106
107
|
Coverage includes protected signals, deterministic shared selection, endpoint
|
|
107
108
|
rates, local opt-out, malformed/expired controls, monotonic expiry, queue loss,
|
|
@@ -110,3 +111,19 @@ fallback, idle zero-rate report refresh, streamed response bounds, batch byte
|
|
|
110
111
|
limits, and real process fork resets. Fake transports verify the wire contract;
|
|
111
112
|
deployed server policy behavior, cross-process traffic forecasts, and a
|
|
112
113
|
customer app's production overhead require hosted/staging validation.
|
|
114
|
+
|
|
115
|
+
## 0.4.0 page view verification
|
|
116
|
+
|
|
117
|
+
The Ruby suite passes locally with Ruby 4.0.9 and the locked Rails 8.1.4 and
|
|
118
|
+
Rack 3.2.7 libraries: 164 tests with no failures or skips. The packaged-gem
|
|
119
|
+
smoke check also runs the page-view, visitor and transport tests against the
|
|
120
|
+
built gem. Page views are tested by instrumenting `process_action.action_controller`
|
|
121
|
+
with real `ActionDispatch::Request` and `ActionDispatch::Response` objects inside
|
|
122
|
+
the SDK's request boundary: every counting rule, the properties and their caps,
|
|
123
|
+
the redactor keeping every property key, the visitor cookie (set, refreshed,
|
|
124
|
+
replaced, never on public responses), the daily hash, identity linking and the
|
|
125
|
+
time-zone header.
|
|
126
|
+
|
|
127
|
+
No Rails application is booted. Routing, `ActionDispatch::RemoteIp`, the cookie
|
|
128
|
+
middleware and a CDN in front of a real app, Rails 7.2, and Rack 2.2 are not
|
|
129
|
+
covered by these tests; check them in staging.
|
data/docs/sdk.md
CHANGED
|
@@ -3,23 +3,30 @@
|
|
|
3
3
|
The gem is `rails_mind`, namespace `RailsMind`. Install the MIT-licensed client
|
|
4
4
|
from RubyGems.org and commit the application lockfile to retain the selected
|
|
5
5
|
version. The hosted RailsMind service is a separate, proprietary application.
|
|
6
|
-
Version 0.
|
|
6
|
+
Version 0.4.0 is an early release with the [documented compatibility limits](compatibility.md).
|
|
7
7
|
|
|
8
8
|
## Install
|
|
9
9
|
|
|
10
10
|
```ruby
|
|
11
11
|
# Customer Gemfile
|
|
12
|
-
gem "rails_mind", "~> 0.
|
|
12
|
+
gem "rails_mind", "~> 0.4.0"
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
```sh
|
|
16
16
|
bundle install
|
|
17
17
|
bin/rails generate rails_mind:install --plan
|
|
18
18
|
bin/rails generate rails_mind:install
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Then set `RAILS_MIND_KEY` ([configuration](#configuration-and-release-detection)) and, with
|
|
22
|
+
it in the app's environment, check the effective settings. Until the key is set,
|
|
23
|
+
doctor names it and exits non-zero.
|
|
24
|
+
|
|
25
|
+
```sh
|
|
19
26
|
bin/rails rails_mind:doctor
|
|
20
27
|
```
|
|
21
28
|
|
|
22
|
-
The plan inspects `Gemfile.lock` and prints selected versions, coexistence decisions, and missing options. Installation adds one initializer, preserves an existing initializer even with `--force`, and does not change migrations, dependencies,
|
|
29
|
+
The plan inspects `Gemfile.lock` and prints selected versions, coexistence decisions, and missing options. Installation adds one initializer, preserves an existing initializer even with `--force`, and does not change migrations, dependencies, Flipper adapters, or OpenTelemetry providers. The doctor is read-only and does not contact the server or print credentials.
|
|
23
30
|
|
|
24
31
|
## Configuration and release detection
|
|
25
32
|
|
|
@@ -35,7 +42,10 @@ RailsMind instance, set `RAILS_MIND_ENDPOINT` (for example,
|
|
|
35
42
|
default. HTTPS is required except for localhost/loopback development. The key
|
|
36
43
|
controls application/environment scope; never give it to browser JavaScript.
|
|
37
44
|
Collection stays off without a nonblank key. `apm`, `errors`, `analytics`, and
|
|
38
|
-
`flags` can each be disabled in the initializer.
|
|
45
|
+
`flags` can each be disabled in the initializer. [Page views](#page-views) have
|
|
46
|
+
their own switches: `page_views`, `visitor_cookie` and `link_page_views_to_users`
|
|
47
|
+
(each `true` or `false`, on by default) and `ignore_page_view` (a callable that
|
|
48
|
+
receives the request). Switches are set in code, never read from the environment.
|
|
39
49
|
|
|
40
50
|
Release detection uses the first nonblank value in this order:
|
|
41
51
|
|
|
@@ -66,7 +76,9 @@ When upgrading an existing generated initializer, remove the old endpoint/releas
|
|
|
66
76
|
assignments that directly read `ENV` so they do not overwrite the new defaults
|
|
67
77
|
with `nil` or bypass platform detection. The installer preserves existing files.
|
|
68
78
|
The doctor reports whether the effective endpoint, key, and release are present,
|
|
69
|
-
without printing credential values or contacting the server.
|
|
79
|
+
without printing credential values or contacting the server. While the key is
|
|
80
|
+
missing or the endpoint is blank, it names the setting after the report and
|
|
81
|
+
exits non-zero, as `rails_mind:verify` does.
|
|
70
82
|
|
|
71
83
|
## Verify the connection
|
|
72
84
|
|
|
@@ -117,7 +129,6 @@ a signed-in workspace member.
|
|
|
117
129
|
```ruby
|
|
118
130
|
# ApplicationController: a before_action inside the SDK request boundary.
|
|
119
131
|
RailsMind.identify(
|
|
120
|
-
visitor_id: ahoy.visitor_token,
|
|
121
132
|
user_id: current_user&.id,
|
|
122
133
|
account_id: current_account&.id
|
|
123
134
|
)
|
|
@@ -129,34 +140,135 @@ RailsMind.track("Invoice paid", invoice_id: invoice.id, amount_cents: invoice.am
|
|
|
129
140
|
RailsMind.capture_exception(error, handled: true)
|
|
130
141
|
```
|
|
131
142
|
|
|
132
|
-
Context is fiber-local and restored around requests/jobs. `identify`
|
|
143
|
+
Context is fiber-local and restored around requests/jobs. `identify` sets the user and account IDs, so call it with both; passing nil or leaving one out clears it. It keeps the visitor ID the request already carries (from the [visitor cookie](#page-views)) unless you pass `visitor_id:`: a value replaces it and `nil` clears it. `identify` sends nothing by itself. Page views and `RailsMind.track` events carry the visitor ID and, once `identify` has run, the user and account IDs; RailsMind links a visitor to a user from any event that carries both, so that visitor's earlier anonymous page views join the user. Account IDs represent the current tenant, never a guessed company from email. Logout/account switching must update identity; a new request starts clean. The SDK does not rewrite or merge historical events.
|
|
133
144
|
|
|
134
145
|
ActiveJob serializes only the context identifier allowlist under `rails_mind_context`, then restores it while executing. Arguments are not inspected. This covers GoodJob through ActiveJob; direct Sidekiq jobs require a future explicit integration. Without OpenTelemetry, RailsMind creates a trace ID at a request, job, or mailer boundary and carries it across serialized ActiveJob context. An active OpenTelemetry span remains authoritative. Native IDs correlate observations; they do not invent a distributed parent/child span tree. Cross-service propagation belongs to the existing OpenTelemetry library; choose ActiveJob `propagation_style: :child` for a linked trace tree when configuring a new provider.
|
|
135
146
|
|
|
136
|
-
##
|
|
137
|
-
|
|
138
|
-
Ahoy's documented store extension points preserve existing `ahoy.track` calls. Choose one mode explicitly. [Ahoy custom stores](https://github.com/ankane/ahoy#data-stores).
|
|
139
|
-
|
|
140
|
-
For an established installation, keep the current `Ahoy::Store` definition, storage, ID generator, user method, and cookies, then add this after its configuration:
|
|
141
|
-
|
|
142
|
-
```ruby
|
|
143
|
-
require "rails_mind/integrations/ahoy"
|
|
144
|
-
RailsMind::Integrations.mirror_ahoy!(Ahoy::Store)
|
|
145
|
-
```
|
|
147
|
+
## Page views
|
|
146
148
|
|
|
147
|
-
|
|
149
|
+
With `analytics` and `page_views` on (the default), the SDK counts a page view
|
|
150
|
+
for each HTML page a controller renders for a person: a GET answered with a 2xx
|
|
151
|
+
`text/html` response. These are not counted:
|
|
148
152
|
|
|
149
|
-
|
|
153
|
+
- Turbo Frame requests, prefetches (`Sec-Purpose` or `X-Sec-Purpose: prefetch`)
|
|
154
|
+
and XHRs;
|
|
155
|
+
- `Rails::` controllers (the `/up` health check included) and `ActiveStorage::`
|
|
156
|
+
controllers;
|
|
157
|
+
- a blank or known-bot user agent (crawlers, link previews, LLM fetchers, uptime
|
|
158
|
+
monitors and bare HTTP clients);
|
|
159
|
+
- anything your `ignore_page_view` hook returns true for. It receives the
|
|
160
|
+
request; a hook that raises skips that page view.
|
|
150
161
|
|
|
151
162
|
```ruby
|
|
152
|
-
|
|
153
|
-
Ahoy.api = true # Only when using the optional browser adapter.
|
|
154
|
-
Ahoy.geocode = false
|
|
155
|
-
class Ahoy::Store < RailsMind::Integrations::AhoyStore
|
|
156
|
-
end
|
|
163
|
+
config.ignore_page_view = ->(request) { request.path.start_with?("/admin") }
|
|
157
164
|
```
|
|
158
165
|
|
|
159
|
-
|
|
166
|
+
A page view is a `pageview` event named `Controller#action`, with the trace and
|
|
167
|
+
request IDs of the request event for the same action. Its properties:
|
|
168
|
+
|
|
169
|
+
| Property | What it holds |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `route` | The route pattern, such as `/posts/:id`, without `(.:format)`; a mounted engine's starts with its mount path |
|
|
172
|
+
| `path` | The path and query string, with the app's `filter_parameters` applied (at most 1,000 characters) |
|
|
173
|
+
| `host` | The request's host |
|
|
174
|
+
| `referrer` | The referring URL's scheme, host and path; its query and fragment are not sent |
|
|
175
|
+
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `ref` | Those query parameters, at most 200 characters each; one your `filter_parameters` masks is not sent |
|
|
176
|
+
| `user_agent` | The user agent, at most 500 characters; RailsMind derives device, browser and OS from it |
|
|
177
|
+
| `country` | Two letters from `CF-IPCountry` or `CloudFront-Viewer-Country`, when present |
|
|
178
|
+
| `visitor_id_kind` | `cookie` or `daily_hash` (below) |
|
|
179
|
+
|
|
180
|
+
The page view also carries the visitor ID and, once `identify` has run, the
|
|
181
|
+
user and account IDs. Set `config.link_page_views_to_users = false` to keep user
|
|
182
|
+
and account IDs off page views. Other events still carry them, and RailsMind
|
|
183
|
+
also links a visitor to a user from a `RailsMind.track` event that carries both
|
|
184
|
+
IDs, such as one sent after `identify`, so the switch does not stop that link.
|
|
185
|
+
Request, job and error events never link a visitor.
|
|
186
|
+
The IP address is never sent. Every string goes through the same redaction as
|
|
187
|
+
other events. Page views are never sampled and count against the environment's
|
|
188
|
+
daily quota.
|
|
189
|
+
|
|
190
|
+
### Visitor cookie
|
|
191
|
+
|
|
192
|
+
By default the SDK keeps a random visitor ID in a first-party cookie named
|
|
193
|
+
`_rails_mind_visitor`: a UUID, `path=/`, two years, `HttpOnly`, `SameSite=Lax`,
|
|
194
|
+
and `Secure` over HTTPS. Each counted page view sets or refreshes it, and a new
|
|
195
|
+
visitor's first page view already carries the ID that response sets. Every event
|
|
196
|
+
of the request, `RailsMind.track` calls and jobs enqueued there included, carries
|
|
197
|
+
the same ID, so an anonymous visit can lead to an outcome. A request that cannot
|
|
198
|
+
become a page view (a POST, a JSON or API GET, a Turbo Frame, an XHR or a
|
|
199
|
+
prefetch) gets no new ID; it carries the cookie's ID when the visitor has one.
|
|
200
|
+
A cookie value that is not a UUID the SDK could have made is replaced.
|
|
201
|
+
|
|
202
|
+
Upgrading to 0.4.0 starts setting this cookie by default. If your privacy notice
|
|
203
|
+
or cookie consent lists the cookies your app sets, update it before you deploy,
|
|
204
|
+
or set `config.visitor_cookie = false` (below) or `config.page_views = false`.
|
|
205
|
+
|
|
206
|
+
A response marked `Cache-Control: public` never gets the cookie, so shared caches
|
|
207
|
+
keep working. Neither does a response from an `ActionController::Live`
|
|
208
|
+
controller, which sends its headers before the action ends. Their page views use
|
|
209
|
+
the visitor's cookie when they brought one, and otherwise the daily hash. For a
|
|
210
|
+
visitor without the cookie, the request's other events (the request event,
|
|
211
|
+
`RailsMind.track` calls and jobs enqueued there) then carry a fresh ID that is
|
|
212
|
+
never stored, so they are not tied to that page view.
|
|
213
|
+
|
|
214
|
+
With `config.visitor_cookie = false`, no cookie is read or set. Page views, and
|
|
215
|
+
the other events of the same request, carry a daily hash instead: an HMAC of the
|
|
216
|
+
local date, the remote IP and the user agent, keyed from the app's
|
|
217
|
+
`secret_key_base` (never the ingest key) and cut to 32 hex characters. It changes
|
|
218
|
+
every day in the app's time zone, so a person who comes back the next day counts
|
|
219
|
+
as a new visitor. Without `secret_key_base` or a remote IP, page views carry no
|
|
220
|
+
visitor ID. Behind a proxy, set `config.action_dispatch.trusted_proxies` so
|
|
221
|
+
`request.remote_ip` is the visitor's address.
|
|
222
|
+
|
|
223
|
+
### Time zone
|
|
224
|
+
|
|
225
|
+
Every batch names the app's time zone (`config.time_zone` as an IANA name, so
|
|
226
|
+
Rails' default `UTC` is `Etc/UTC`) in the `X-RailsMind-Time-Zone` header, and
|
|
227
|
+
RailsMind counts days in that zone.
|
|
228
|
+
|
|
229
|
+
### Limits
|
|
230
|
+
|
|
231
|
+
- Turbo broadcast page refreshes (`broadcasts_refreshes`) reload a page the way
|
|
232
|
+
a visit does, so each refresh counts as a page view in every open tab.
|
|
233
|
+
- Turbo 8 prefetches a link on hover (`X-Sec-Purpose: prefetch`) and, when the
|
|
234
|
+
link is clicked, shows that prefetched response without asking the app again.
|
|
235
|
+
Prefetches are not counted, so a page opened that way is not counted either.
|
|
236
|
+
Add `<meta name="turbo-prefetch" content="false">` to the layout to count
|
|
237
|
+
those visits.
|
|
238
|
+
- Pages served from a CDN or a browser cache never reach the app and are not
|
|
239
|
+
counted. A `304 Not Modified` from `Rack::ConditionalGet` still counts; one
|
|
240
|
+
the controller sends through `fresh_when` or `stale?` does not, because the
|
|
241
|
+
action rendered no page.
|
|
242
|
+
- Bot filtering is a built-in user-agent list. Add your own rules with
|
|
243
|
+
`ignore_page_view`.
|
|
244
|
+
- Page views come on top of request events, so HTML traffic sends more events
|
|
245
|
+
than before; both share the collector's queue and the daily quota.
|
|
246
|
+
|
|
247
|
+
## Coming from Ahoy
|
|
248
|
+
|
|
249
|
+
Version 0.4.0 removed the Ahoy integration (`AhoyStore`, `mirror_ahoy!`) and
|
|
250
|
+
the Ahoy-based browser adapter. RailsMind counts [page views](#page-views)
|
|
251
|
+
itself and no longer receives `$visit`, `$view`, `$pageview`, `$frame_view` or
|
|
252
|
+
`$identify`. Before upgrading, delete `require "rails_mind/integrations/ahoy"`
|
|
253
|
+
and `RailsMind::Integrations.mirror_ahoy!`; the require now fails at boot.
|
|
254
|
+
|
|
255
|
+
- `ahoy.track("Invoice paid", ...)` becomes `RailsMind.track("Invoice paid", ...)`,
|
|
256
|
+
called after the outcome commits. Keep the `ahoy.track` call too if your own
|
|
257
|
+
Ahoy reports use it.
|
|
258
|
+
- Ahoy's `authenticate(user)` becomes `RailsMind.identify(user_id:, account_id:)`.
|
|
259
|
+
Stop passing `visitor_id: ahoy.visitor_token`, so page views and events carry
|
|
260
|
+
the RailsMind visitor cookie.
|
|
261
|
+
- A hosted-only `class Ahoy::Store < RailsMind::Integrations::AhoyStore` goes.
|
|
262
|
+
Remove `ahoy_matey` too, or define `class Ahoy::Store < Ahoy::BaseStore; end`,
|
|
263
|
+
because Ahoy needs an `Ahoy::Store`.
|
|
264
|
+
- Delete the copied `app/javascript/rails_mind.js`, its importmap pin, the
|
|
265
|
+
`import { start } from "rails_mind"` line and the `start(...)` call in your
|
|
266
|
+
JavaScript entry point, any asset path into the gem, and the `rails-mind-page`
|
|
267
|
+
meta tag. An import left without its pin stops the whole entry point from
|
|
268
|
+
loading. Custom events sent from the browser are no longer supported; record
|
|
269
|
+
them on the server with `RailsMind.track`.
|
|
270
|
+
|
|
271
|
+
Ahoy itself keeps working for your own reports; RailsMind no longer reads it.
|
|
160
272
|
|
|
161
273
|
## OpenTelemetry
|
|
162
274
|
|
|
@@ -196,8 +308,8 @@ uses the same selection rule, so the two samplers do not multiply probabilities.
|
|
|
196
308
|
Only completed `request` events with status 200–399, a finite duration from zero
|
|
197
309
|
to below 1,000 ms, and fewer than three repeated queries are eligible. Slow,
|
|
198
310
|
failed, unknown-duration, and repeated-query requests remain unsampled, as do
|
|
199
|
-
business events, errors, jobs, mailer observations,
|
|
200
|
-
OpenTelemetry spans. This preserves their sampling priority, not guaranteed
|
|
311
|
+
business events, page views, errors, jobs, mailer observations, flags, checks,
|
|
312
|
+
and OpenTelemetry spans. This preserves their sampling priority, not guaranteed
|
|
201
313
|
delivery: queue bounds, payload limits, outages, and the server's hard daily quota
|
|
202
314
|
still apply. Existing OpenTelemetry samplers remain authoritative; this feature
|
|
203
315
|
does not promise complete distributed traces.
|
|
@@ -299,20 +411,10 @@ callbacks if later delivery facts are needed. Keep real product outcomes such
|
|
|
299
411
|
as invitation acceptance separate, using explicit events after persistence.
|
|
300
412
|
|
|
301
413
|
|
|
302
|
-
## Flipper
|
|
414
|
+
## Flipper
|
|
303
415
|
|
|
304
416
|
The SDK subscribes to `feature_operation.flipper`. It observes names, operations, boolean results, and duration without changing adapters, groups, actors, rollout logic, or cache. Flipper's existing Rails instrumentation emits these events; applications with a custom instrumenter must deliberately opt into ActiveSupport notifications. Actor IDs are not collected. An evaluation is not experiment exposure. Managed flags and experiments are not implemented in this SDK. [Flipper instrumentation](https://www.flippercloud.io/docs/instrumentation).
|
|
305
417
|
|
|
306
|
-
Run `bin/rails generate rails_mind:install --browser` to copy the optional module. Importmap users pin it, then pass their existing Ahoy instance:
|
|
307
|
-
|
|
308
|
-
```javascript
|
|
309
|
-
import ahoy from "ahoy"
|
|
310
|
-
import { start } from "rails_mind"
|
|
311
|
-
const analytics = start({ ahoy, frames: true })
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
Add `<meta name="rails-mind-page" content="Invoices#index">` to supply a stable page label. The adapter transmits no URL or query string. It counts the initial page and each completed Turbo visit once, ignores cached preview renders, and keeps `turbo:frame-load` as a separate `$frame_view` only for Frames with `data-analytics-frame`. It does not infer payment/signup success from forms or HTTP responses. Set `pageviews: false` if the application already counts pageviews. Repeated installation returns the same adapter. Browser delivery uses Ahoy's same-origin endpoint/cookies and existing CSRF policy; there is no browser ingestion credential. [Turbo events](https://turbo.hotwired.dev/reference/events).
|
|
315
|
-
|
|
316
418
|
## Bounds, privacy, and outages
|
|
317
419
|
|
|
318
420
|
Defaults are one lazy worker per process, 1,000 queued/in-flight events, 16 KiB per event, at most 100 events and 256 KiB per batch, and a two-second flush interval. Overflow drops the newest event. Retries retain the same encoded bytes/UUIDs; only HTTP 429, 5xx, and transient transport failures retry, at most three retries with bounded backoff. Other 4xx responses end delivery attempts. A failed response can follow partial server acceptance, so such events are classified as delivery unconfirmed. Redirects are not followed. Shutdown gets two seconds by default, then discards outstanding telemetry; forks start a fresh child queue rather than resending the parent's buffer.
|
|
@@ -328,7 +430,7 @@ RailsMind.flush(timeout: 2)
|
|
|
328
430
|
|
|
329
431
|
These are per-process counters. `dropped` counts known local discards, such as queue overflow or oversize payloads. `delivery_unconfirmed` counts events whose delivery attempts ended without a success response, including interrupted in-flight batches; some may have been accepted by the server. `delivered` counts submitted events in batches with a successful HTTP response; it does not prove server retention or background processing. The doctor prints stats for its process; inspect running app stats through your existing operational tooling. Only the routine-request report above sends queue-loss observations to the hosted app. All signal kinds can still undercount after crashes, rejected payloads, hooks, or outages. This is best-effort monitoring, not an accounting ledger; use a transactional outbox when durable business-event delivery is required.
|
|
330
432
|
|
|
331
|
-
Redaction occurs before buffering and again after custom `before_send`. Sensitive property names are filtered, nesting/string/collection sizes are capped, emails and common credential forms are scrubbed (exception messages included), and backtraces drop machine-home prefixes while keeping a `gems/<name>-<version>/` or `ruby/<version>/` origin for library frames. Error events also name where they happened: `role`, plus the controller action as `route` or the job's `job_class` and `queue`. Bodies, cookies, credentials, SQL binds, and job arguments are never selected by integrations. Arbitrary user-provided text may contain sensitive content that generic redaction cannot recognize: use small, explicitly reviewed business properties. Exception messages can contain whatever your code interpolated into them; review your scrubbing policy, or set `config.capture_exception_message = false` to replace every message with a placeholder before it leaves.
|
|
433
|
+
Redaction occurs before buffering and again after custom `before_send`. Sensitive property names are filtered, nesting/string/collection sizes are capped, emails and common credential forms are scrubbed (exception messages included), and backtraces drop machine-home prefixes while keeping a `gems/<name>-<version>/` or `ruby/<version>/` origin for library frames. Error events also name where they happened: `role`, plus the controller action as `route` or the job's `job_class` and `queue`. Bodies, cookies (other than the SDK's own visitor cookie), credentials, SQL binds, and job arguments are never selected by integrations. Arbitrary user-provided text may contain sensitive content that generic redaction cannot recognize: use small, explicitly reviewed business properties. Exception messages can contain whatever your code interpolated into them; review your scrubbing policy, or set `config.capture_exception_message = false` to replace every message with a placeholder before it leaves.
|
|
332
434
|
|
|
333
435
|
The final local synthetic burst benchmark on Ruby 4.0.6 processed 10,000 calls in 1.7612 seconds (176.12 μs/call), delivering all 10,000 with zero drops/retries at the 1,000-event queue bound. This measures local sanitization/enqueue with a no-op transport, not production request overhead or network delivery. Earlier runs did overflow; thread scheduling and downstream speed affect the result. Deterministic tests separately verify overflow losses and bounded shutdown during a hung transport. Run `ruby script_benchmark.rb` on the deployment hardware before setting a production budget.
|
|
334
436
|
|
|
@@ -6,7 +6,6 @@ module RailsMind
|
|
|
6
6
|
class InstallGenerator < Rails::Generators::Base
|
|
7
7
|
source_root File.expand_path("templates", __dir__)
|
|
8
8
|
class_option :plan, type: :boolean, default: false, desc: "Print the integration plan without writing files"
|
|
9
|
-
class_option :browser, type: :boolean, default: false, desc: "Copy the optional Ahoy/Turbo adapter without enabling it"
|
|
10
9
|
|
|
11
10
|
def inspect_application
|
|
12
11
|
say JSON.pretty_generate(Diagnostic.new(root: destination_root).report)
|
|
@@ -25,17 +24,6 @@ module RailsMind
|
|
|
25
24
|
def connect_agent_hint
|
|
26
25
|
say "Connect your coding agent: bin/rails generate rails_mind:agent --plan"
|
|
27
26
|
end
|
|
28
|
-
|
|
29
|
-
def add_browser_adapter
|
|
30
|
-
return if options[:plan] || !options[:browser]
|
|
31
|
-
path = "app/javascript/rails_mind.js"
|
|
32
|
-
if File.exist?(File.join(destination_root, path))
|
|
33
|
-
say_status :skip, "#{path} already exists", :yellow
|
|
34
|
-
else
|
|
35
|
-
copy_file File.expand_path("../../../../javascript/rails_mind.js", __dir__), path
|
|
36
|
-
end
|
|
37
|
-
say "Pin rails_mind in importmap.rb and start it with your existing Ahoy instance. See docs/sdk.md."
|
|
38
|
-
end
|
|
39
27
|
end
|
|
40
28
|
end
|
|
41
29
|
end
|
|
@@ -21,7 +21,14 @@ RailsMind.configure do |config|
|
|
|
21
21
|
# literals replaced and comments removed). Set false to send the fingerprints only.
|
|
22
22
|
# config.capture_query_shapes = false
|
|
23
23
|
# config.before_send = ->(event) { event } # Return nil to drop an event.
|
|
24
|
+
|
|
25
|
+
# Page views: each HTML page a controller renders for a person (not a bot, prefetch,
|
|
26
|
+
# Turbo Frame or health check) is counted, with a first-party visitor cookie.
|
|
27
|
+
# config.page_views = false # Count no page views.
|
|
28
|
+
# config.visitor_cookie = false # Count visitors by a daily hash instead of a cookie.
|
|
29
|
+
# config.link_page_views_to_users = false # Keep user and account IDs off page views.
|
|
30
|
+
# config.ignore_page_view = ->(request) { request.path.start_with?("/admin") }
|
|
24
31
|
end
|
|
25
32
|
|
|
26
|
-
# No existing
|
|
33
|
+
# No existing Flipper adapter or OpenTelemetry provider is changed.
|
|
27
34
|
# Run `bin/rails rails_mind:doctor` and follow docs/sdk.md for opt-in integrations.
|
data/lib/rails_mind/client.rb
CHANGED
|
@@ -4,7 +4,7 @@ require "digest"
|
|
|
4
4
|
|
|
5
5
|
module RailsMind
|
|
6
6
|
class Client
|
|
7
|
-
KINDS = %w[request span error event visit flag job check].freeze
|
|
7
|
+
KINDS = %w[request span error event visit pageview flag job check].freeze
|
|
8
8
|
FIELDS = %i[id kind occurred_at name duration_ms status release trace_id span_id parent_span_id request_id job_id visitor_id user_id account_id properties].freeze
|
|
9
9
|
UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
|
|
10
10
|
attr_reader :config, :collector
|
|
@@ -66,7 +66,7 @@ module RailsMind
|
|
|
66
66
|
def stable_id(value = nil)
|
|
67
67
|
return SecureRandom.uuid unless value
|
|
68
68
|
return value.to_s.downcase if value.to_s.match?(UUID)
|
|
69
|
-
# Deterministic UUID-shaped ID for
|
|
69
|
+
# Deterministic UUID-shaped ID for caller-supplied non-UUID IDs such as ULIDs.
|
|
70
70
|
hex = Digest::SHA256.hexdigest("rails_mind:#{value}")[0, 32]
|
|
71
71
|
hex[12] = "8"
|
|
72
72
|
hex[16] = "8"
|
|
@@ -97,6 +97,7 @@ module RailsMind
|
|
|
97
97
|
when "request", "span", "job" then config.apm
|
|
98
98
|
when "error" then config.errors
|
|
99
99
|
when "event", "visit" then config.analytics
|
|
100
|
+
when "pageview" then config.analytics && config.page_views
|
|
100
101
|
when "flag" then config.flags
|
|
101
102
|
else false
|
|
102
103
|
end
|
|
@@ -9,7 +9,8 @@ module RailsMind
|
|
|
9
9
|
attr_accessor :endpoint, :token, :release, :apm, :errors, :analytics, :flags,
|
|
10
10
|
:queue_capacity, :batch_size, :max_batch_bytes, :max_event_bytes, :flush_interval,
|
|
11
11
|
:max_retries, :retry_base, :open_timeout, :read_timeout, :shutdown_timeout,
|
|
12
|
-
:before_send, :capture_exception_message, :capture_query_shapes, :automatic_sampling
|
|
12
|
+
:before_send, :capture_exception_message, :capture_query_shapes, :automatic_sampling,
|
|
13
|
+
:page_views, :visitor_cookie, :link_page_views_to_users, :ignore_page_view
|
|
13
14
|
|
|
14
15
|
def initialize(env: ENV, root: nil)
|
|
15
16
|
@endpoint = nonblank(env["RAILS_MIND_ENDPOINT"]) || DEFAULT_ENDPOINT
|
|
@@ -29,6 +30,10 @@ module RailsMind
|
|
|
29
30
|
@capture_exception_message = true
|
|
30
31
|
@capture_query_shapes = true
|
|
31
32
|
@automatic_sampling = true
|
|
33
|
+
@page_views = true
|
|
34
|
+
@visitor_cookie = true
|
|
35
|
+
@link_page_views_to_users = true
|
|
36
|
+
@ignore_page_view = nil
|
|
32
37
|
end
|
|
33
38
|
|
|
34
39
|
def enabled? = !token.to_s.strip.empty? && !endpoint.to_s.strip.empty?
|
|
@@ -37,10 +42,11 @@ module RailsMind
|
|
|
37
42
|
return self unless enabled?
|
|
38
43
|
# capture_exception_message stays unvalidated as in 0.3.0, so an app that
|
|
39
44
|
# assigned it from ENV still boots after upgrading.
|
|
40
|
-
%i[automatic_sampling capture_query_shapes].each do |flag|
|
|
45
|
+
%i[automatic_sampling capture_query_shapes page_views visitor_cookie link_page_views_to_users].each do |flag|
|
|
41
46
|
value = public_send(flag)
|
|
42
47
|
raise ArgumentError, "#{flag} must be true or false" unless value == true || value == false
|
|
43
48
|
end
|
|
49
|
+
raise ArgumentError, "ignore_page_view must respond to call" unless ignore_page_view.nil? || ignore_page_view.respond_to?(:call)
|
|
44
50
|
uri = URI(endpoint)
|
|
45
51
|
loopback = %w[localhost 127.0.0.1 ::1].include?(uri.hostname)
|
|
46
52
|
raise ArgumentError, "endpoint must use HTTPS (HTTP only on loopback)" unless uri.is_a?(URI::HTTPS) || (uri.is_a?(URI::HTTP) && loopback)
|