rails_mind 0.3.2 → 0.4.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/CHANGELOG.md +30 -0
- data/CONTRIBUTING.md +6 -7
- data/README.md +3 -4
- data/docs/compatibility.md +32 -14
- data/docs/sdk.md +141 -40
- 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 +6 -3
- data/lib/rails_mind/integrations/rails.rb +14 -1
- data/lib/rails_mind/page_view.rb +275 -0
- data/lib/rails_mind/redactor.rb +2 -1
- data/lib/rails_mind/transport.rb +14 -0
- data/lib/rails_mind/version.rb +1 -1
- data/lib/rails_mind/visitor.rb +134 -0
- 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: 372c9336e641bc2e69af9ed38a5771fbc340bd67d4f416eff8faaa90258f2f8b
|
|
4
|
+
data.tar.gz: 16e987e172416a1cd6a18937da87f941c95355db87922e1a0c475c3af2130e0e
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 6af33efbf21560279d31b2fbf0c8729499afedfe5514658cef6a5d7b6edcb9922fe21067b49b9a14b4965c5adba32f4b4d5d3183840281e42986aadde3859f6d
|
|
7
|
+
data.tar.gz: 7bf58df1349bcb4740eaf44381e7878336ccf89ee9018ff1df573a157980f1bf116b3aa648fa1134486fd049f9e97e92d2bedb0c11785d5cc42db16f2e87d741
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,35 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.4.1 — 2026-11-06
|
|
4
|
+
|
|
5
|
+
Fixes for page views. Upgrade from 0.4.0 before deploying it.
|
|
6
|
+
|
|
7
|
+
- A route segment your `filter_parameters` masks is masked in the page view's `path`, as the query already was: `/passwords/:token/edit` (the Rails authentication generator's reset page) sends `/passwords/[FILTERED]/edit`, not the reset token. 0.4.0 sent the token. The whole segment goes, with any format suffix or text around the value; so do a glob value spanning segments, a long value repeated in the query, a back link to the masked page in the query, a campaign tag holding the value, and a masked mount segment in `route`. Filters receive string keys, as in Rails' own logs, and if masking fails the path is sent as `[FILTERED]`.
|
|
8
|
+
- A referrer inside the app sends only its origin, since its path can hold what the app masks in its own paths. Other sites' referrers keep their path.
|
|
9
|
+
- Only a GET whose `Accept` header asks for `text/html` counts. Pollers and scripts that accept anything (`*/*`), such as GoodJob's live dashboard and bare HTTP clients, no longer count as page views.
|
|
10
|
+
- The `Turbo::Native::` stub pages Hotwire Native apps load to recede, resume or refresh are not counted.
|
|
11
|
+
|
|
12
|
+
## 0.4.0 — 2026-11-06
|
|
13
|
+
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
- 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`.
|
|
17
|
+
- 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.
|
|
18
|
+
- RailsMind no longer receives `$visit`, `$view`, `$pageview`, `$frame_view` or `$identify`.
|
|
19
|
+
- 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.
|
|
20
|
+
- 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.
|
|
21
|
+
- 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`.
|
|
22
|
+
|
|
23
|
+
Page views:
|
|
24
|
+
|
|
25
|
+
- 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.
|
|
26
|
+
- 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.
|
|
27
|
+
- 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.
|
|
28
|
+
- 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.
|
|
29
|
+
- 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.
|
|
30
|
+
- 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.
|
|
31
|
+
- 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.
|
|
32
|
+
|
|
3
33
|
## 0.3.2 — 2026-10-13
|
|
4
34
|
|
|
5
35
|
Security fix for the scrubbing 0.3.1 turned on by default. Upgrade from 0.3.1.
|
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.1 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
|
|
@@ -68,7 +68,6 @@ Tests:
|
|
|
68
68
|
```sh
|
|
69
69
|
bundle install
|
|
70
70
|
bundle exec rake test
|
|
71
|
-
node --test javascript/rails_mind.test.js
|
|
72
71
|
bundle exec ruby script/package_smoke.rb
|
|
73
72
|
ruby script_benchmark.rb
|
|
74
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,20 @@ 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 and 0.4.1 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: 167 tests with no failures or skips at 0.4.1. 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, the
|
|
125
|
+
time-zone header and, from 0.4.1, masked route segments, same-site referrers
|
|
126
|
+
cut to their origin and the `Accept: text/html` rule.
|
|
127
|
+
|
|
128
|
+
No Rails application is booted. Routing, `ActionDispatch::RemoteIp`, the cookie
|
|
129
|
+
middleware and a CDN in front of a real app, Rails 7.2, and Rack 2.2 are not
|
|
130
|
+
covered by these tests; check them in staging.
|
data/docs/sdk.md
CHANGED
|
@@ -3,13 +3,13 @@
|
|
|
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.1 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
|
|
@@ -26,7 +26,7 @@ doctor names it and exits non-zero.
|
|
|
26
26
|
bin/rails rails_mind:doctor
|
|
27
27
|
```
|
|
28
28
|
|
|
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,
|
|
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.
|
|
30
30
|
|
|
31
31
|
## Configuration and release detection
|
|
32
32
|
|
|
@@ -42,7 +42,10 @@ RailsMind instance, set `RAILS_MIND_ENDPOINT` (for example,
|
|
|
42
42
|
default. HTTPS is required except for localhost/loopback development. The key
|
|
43
43
|
controls application/environment scope; never give it to browser JavaScript.
|
|
44
44
|
Collection stays off without a nonblank key. `apm`, `errors`, `analytics`, and
|
|
45
|
-
`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.
|
|
46
49
|
|
|
47
50
|
Release detection uses the first nonblank value in this order:
|
|
48
51
|
|
|
@@ -126,7 +129,6 @@ a signed-in workspace member.
|
|
|
126
129
|
```ruby
|
|
127
130
|
# ApplicationController: a before_action inside the SDK request boundary.
|
|
128
131
|
RailsMind.identify(
|
|
129
|
-
visitor_id: ahoy.visitor_token,
|
|
130
132
|
user_id: current_user&.id,
|
|
131
133
|
account_id: current_account&.id
|
|
132
134
|
)
|
|
@@ -138,34 +140,143 @@ RailsMind.track("Invoice paid", invoice_id: invoice.id, amount_cents: invoice.am
|
|
|
138
140
|
RailsMind.capture_exception(error, handled: true)
|
|
139
141
|
```
|
|
140
142
|
|
|
141
|
-
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.
|
|
142
144
|
|
|
143
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.
|
|
144
146
|
|
|
145
|
-
##
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
147
|
+
## Page views
|
|
148
|
+
|
|
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 whose `Accept`
|
|
151
|
+
header asks for `text/html`, answered with a 2xx `text/html` response. Browsers
|
|
152
|
+
and Turbo always ask for HTML when they load a page; pollers, scripts and bare
|
|
153
|
+
HTTP clients that accept anything (`*/*`) are not counted. These are not counted
|
|
154
|
+
either:
|
|
155
|
+
|
|
156
|
+
- Turbo Frame requests, prefetches (`Sec-Purpose` or `X-Sec-Purpose: prefetch`)
|
|
157
|
+
and XHRs;
|
|
158
|
+
- `Rails::` controllers (the `/up` health check included), `ActiveStorage::`
|
|
159
|
+
controllers and the `Turbo::Native::` stub pages Hotwire Native apps load to
|
|
160
|
+
recede, resume or refresh;
|
|
161
|
+
- a blank or known-bot user agent (crawlers, link previews, LLM fetchers, uptime
|
|
162
|
+
monitors and bare HTTP clients);
|
|
163
|
+
- anything your `ignore_page_view` hook returns true for. It receives the
|
|
164
|
+
request; a hook that raises skips that page view.
|
|
159
165
|
|
|
160
166
|
```ruby
|
|
161
|
-
|
|
162
|
-
Ahoy.api = true # Only when using the optional browser adapter.
|
|
163
|
-
Ahoy.geocode = false
|
|
164
|
-
class Ahoy::Store < RailsMind::Integrations::AhoyStore
|
|
165
|
-
end
|
|
167
|
+
config.ignore_page_view = ->(request) { request.path.start_with?("/admin") }
|
|
166
168
|
```
|
|
167
169
|
|
|
168
|
-
|
|
170
|
+
A page view is a `pageview` event named `Controller#action`, with the trace and
|
|
171
|
+
request IDs of the request event for the same action. Its properties:
|
|
172
|
+
|
|
173
|
+
| Property | What it holds |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| `route` | The route pattern, such as `/posts/:id`, without `(.:format)`; a mounted engine's starts with its mount path |
|
|
176
|
+
| `path` | The path and query string, with the app's `filter_parameters` applied to the query and to route segments, so `/passwords/:token/edit` sends `/passwords/[FILTERED]/edit` (at most 1,000 characters) |
|
|
177
|
+
| `host` | The request's host |
|
|
178
|
+
| `referrer` | Another site's scheme, host and path; its query and fragment are not sent. A link inside the app sends only its origin |
|
|
179
|
+
| `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 |
|
|
180
|
+
| `user_agent` | The user agent, at most 500 characters; RailsMind derives device, browser and OS from it |
|
|
181
|
+
| `country` | Two letters from `CF-IPCountry` or `CloudFront-Viewer-Country`, when present |
|
|
182
|
+
| `visitor_id_kind` | `cookie` or `daily_hash` (below) |
|
|
183
|
+
|
|
184
|
+
The page view also carries the visitor ID and, once `identify` has run, the
|
|
185
|
+
user and account IDs. Set `config.link_page_views_to_users = false` to keep user
|
|
186
|
+
and account IDs off page views. Other events still carry them, and RailsMind
|
|
187
|
+
also links a visitor to a user from a `RailsMind.track` event that carries both
|
|
188
|
+
IDs, such as one sent after `identify`, so the switch does not stop that link.
|
|
189
|
+
Request, job and error events never link a visitor.
|
|
190
|
+
The IP address is never sent. Every string goes through the same redaction as
|
|
191
|
+
other events. Page views are never sampled and count against the environment's
|
|
192
|
+
daily quota.
|
|
193
|
+
|
|
194
|
+
### Visitor cookie
|
|
195
|
+
|
|
196
|
+
By default the SDK keeps a random visitor ID in a first-party cookie named
|
|
197
|
+
`_rails_mind_visitor`: a UUID, `path=/`, two years, `HttpOnly`, `SameSite=Lax`,
|
|
198
|
+
and `Secure` over HTTPS. Each counted page view sets or refreshes it, and a new
|
|
199
|
+
visitor's first page view already carries the ID that response sets. Every event
|
|
200
|
+
of the request, `RailsMind.track` calls and jobs enqueued there included, carries
|
|
201
|
+
the same ID, so an anonymous visit can lead to an outcome. A request that cannot
|
|
202
|
+
become a page view (a POST, a JSON or API GET, a Turbo Frame, an XHR or a
|
|
203
|
+
prefetch) gets no new ID; it carries the cookie's ID when the visitor has one.
|
|
204
|
+
A cookie value that is not a UUID the SDK could have made is replaced.
|
|
205
|
+
|
|
206
|
+
Upgrading to 0.4.0 starts setting this cookie by default. If your privacy notice
|
|
207
|
+
or cookie consent lists the cookies your app sets, update it before you deploy,
|
|
208
|
+
or set `config.visitor_cookie = false` (below) or `config.page_views = false`.
|
|
209
|
+
|
|
210
|
+
A response marked `Cache-Control: public` never gets the cookie, so shared caches
|
|
211
|
+
keep working. Neither does a response from an `ActionController::Live`
|
|
212
|
+
controller, which sends its headers before the action ends. Their page views use
|
|
213
|
+
the visitor's cookie when they brought one, and otherwise the daily hash. For a
|
|
214
|
+
visitor without the cookie, the request's other events (the request event,
|
|
215
|
+
`RailsMind.track` calls and jobs enqueued there) then carry a fresh ID that is
|
|
216
|
+
never stored, so they are not tied to that page view.
|
|
217
|
+
|
|
218
|
+
With `config.visitor_cookie = false`, no cookie is read or set. Page views, and
|
|
219
|
+
the other events of the same request, carry a daily hash instead: an HMAC of the
|
|
220
|
+
local date, the remote IP and the user agent, keyed from the app's
|
|
221
|
+
`secret_key_base` (never the ingest key) and cut to 32 hex characters. It changes
|
|
222
|
+
every day in the app's time zone, so a person who comes back the next day counts
|
|
223
|
+
as a new visitor. Without `secret_key_base` or a remote IP, page views carry no
|
|
224
|
+
visitor ID. Behind a proxy, set `config.action_dispatch.trusted_proxies` so
|
|
225
|
+
`request.remote_ip` is the visitor's address.
|
|
226
|
+
|
|
227
|
+
### Time zone
|
|
228
|
+
|
|
229
|
+
Every batch names the app's time zone (`config.time_zone` as an IANA name, so
|
|
230
|
+
Rails' default `UTC` is `Etc/UTC`) in the `X-RailsMind-Time-Zone` header, and
|
|
231
|
+
RailsMind counts days in that zone.
|
|
232
|
+
|
|
233
|
+
### Limits
|
|
234
|
+
|
|
235
|
+
- A referrer counts as inside the app when its host matches the request's host
|
|
236
|
+
(ignoring a leading `www.`). Behind a proxy that rewrites `Host`, forward the
|
|
237
|
+
original host (`X-Forwarded-Host`) so Rails sees it; otherwise an internal
|
|
238
|
+
referrer is sent with its path.
|
|
239
|
+
- Turbo broadcast page refreshes (`broadcasts_refreshes`) reload a page the way
|
|
240
|
+
a visit does, so each refresh counts as a page view in every open tab.
|
|
241
|
+
- Turbo 8 prefetches a link on hover (`X-Sec-Purpose: prefetch`) and, when the
|
|
242
|
+
link is clicked, shows that prefetched response without asking the app again.
|
|
243
|
+
Prefetches are not counted, so a page opened that way is not counted either.
|
|
244
|
+
Add `<meta name="turbo-prefetch" content="false">` to the layout to count
|
|
245
|
+
those visits.
|
|
246
|
+
- Pages served from a CDN or a browser cache never reach the app and are not
|
|
247
|
+
counted. A `304 Not Modified` from `Rack::ConditionalGet` still counts; one
|
|
248
|
+
the controller sends through `fresh_when` or `stale?` does not, because the
|
|
249
|
+
action rendered no page.
|
|
250
|
+
- Bot filtering is a built-in user-agent list. Add your own rules with
|
|
251
|
+
`ignore_page_view`.
|
|
252
|
+
- Page views come on top of request events, so HTML traffic sends more events
|
|
253
|
+
than before; both share the collector's queue and the daily quota.
|
|
254
|
+
|
|
255
|
+
## Coming from Ahoy
|
|
256
|
+
|
|
257
|
+
Version 0.4.0 removed the Ahoy integration (`AhoyStore`, `mirror_ahoy!`) and
|
|
258
|
+
the Ahoy-based browser adapter. RailsMind counts [page views](#page-views)
|
|
259
|
+
itself and no longer receives `$visit`, `$view`, `$pageview`, `$frame_view` or
|
|
260
|
+
`$identify`. Before upgrading, delete `require "rails_mind/integrations/ahoy"`
|
|
261
|
+
and `RailsMind::Integrations.mirror_ahoy!`; the require now fails at boot.
|
|
262
|
+
|
|
263
|
+
- `ahoy.track("Invoice paid", ...)` becomes `RailsMind.track("Invoice paid", ...)`,
|
|
264
|
+
called after the outcome commits. Keep the `ahoy.track` call too if your own
|
|
265
|
+
Ahoy reports use it.
|
|
266
|
+
- Ahoy's `authenticate(user)` becomes `RailsMind.identify(user_id:, account_id:)`.
|
|
267
|
+
Stop passing `visitor_id: ahoy.visitor_token`, so page views and events carry
|
|
268
|
+
the RailsMind visitor cookie.
|
|
269
|
+
- A hosted-only `class Ahoy::Store < RailsMind::Integrations::AhoyStore` goes.
|
|
270
|
+
Remove `ahoy_matey` too, or define `class Ahoy::Store < Ahoy::BaseStore; end`,
|
|
271
|
+
because Ahoy needs an `Ahoy::Store`.
|
|
272
|
+
- Delete the copied `app/javascript/rails_mind.js`, its importmap pin, the
|
|
273
|
+
`import { start } from "rails_mind"` line and the `start(...)` call in your
|
|
274
|
+
JavaScript entry point, any asset path into the gem, and the `rails-mind-page`
|
|
275
|
+
meta tag. An import left without its pin stops the whole entry point from
|
|
276
|
+
loading. Custom events sent from the browser are no longer supported; record
|
|
277
|
+
them on the server with `RailsMind.track`.
|
|
278
|
+
|
|
279
|
+
Ahoy itself keeps working for your own reports; RailsMind no longer reads it.
|
|
169
280
|
|
|
170
281
|
## OpenTelemetry
|
|
171
282
|
|
|
@@ -205,8 +316,8 @@ uses the same selection rule, so the two samplers do not multiply probabilities.
|
|
|
205
316
|
Only completed `request` events with status 200–399, a finite duration from zero
|
|
206
317
|
to below 1,000 ms, and fewer than three repeated queries are eligible. Slow,
|
|
207
318
|
failed, unknown-duration, and repeated-query requests remain unsampled, as do
|
|
208
|
-
business events, errors, jobs, mailer observations,
|
|
209
|
-
OpenTelemetry spans. This preserves their sampling priority, not guaranteed
|
|
319
|
+
business events, page views, errors, jobs, mailer observations, flags, checks,
|
|
320
|
+
and OpenTelemetry spans. This preserves their sampling priority, not guaranteed
|
|
210
321
|
delivery: queue bounds, payload limits, outages, and the server's hard daily quota
|
|
211
322
|
still apply. Existing OpenTelemetry samplers remain authoritative; this feature
|
|
212
323
|
does not promise complete distributed traces.
|
|
@@ -308,20 +419,10 @@ callbacks if later delivery facts are needed. Keep real product outcomes such
|
|
|
308
419
|
as invitation acceptance separate, using explicit events after persistence.
|
|
309
420
|
|
|
310
421
|
|
|
311
|
-
## Flipper
|
|
422
|
+
## Flipper
|
|
312
423
|
|
|
313
424
|
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).
|
|
314
425
|
|
|
315
|
-
Run `bin/rails generate rails_mind:install --browser` to copy the optional module. Importmap users pin it, then pass their existing Ahoy instance:
|
|
316
|
-
|
|
317
|
-
```javascript
|
|
318
|
-
import ahoy from "ahoy"
|
|
319
|
-
import { start } from "rails_mind"
|
|
320
|
-
const analytics = start({ ahoy, frames: true })
|
|
321
|
-
```
|
|
322
|
-
|
|
323
|
-
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).
|
|
324
|
-
|
|
325
426
|
## Bounds, privacy, and outages
|
|
326
427
|
|
|
327
428
|
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.
|
|
@@ -337,7 +438,7 @@ RailsMind.flush(timeout: 2)
|
|
|
337
438
|
|
|
338
439
|
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.
|
|
339
440
|
|
|
340
|
-
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.
|
|
441
|
+
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.
|
|
341
442
|
|
|
342
443
|
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.
|
|
343
444
|
|
|
@@ -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)
|
data/lib/rails_mind/context.rb
CHANGED
|
@@ -39,8 +39,14 @@ module RailsMind
|
|
|
39
39
|
Thread.current[:rails_mind_context] = previous
|
|
40
40
|
end
|
|
41
41
|
|
|
42
|
-
|
|
43
|
-
|
|
42
|
+
UNSET = Object.new.freeze
|
|
43
|
+
|
|
44
|
+
# Signing in names the user and account; the visitor stays the one this
|
|
45
|
+
# request already carries unless visitor_id is passed (nil clears it).
|
|
46
|
+
def identify(user_id: nil, account_id: nil, visitor_id: UNSET)
|
|
47
|
+
values = { user_id: user_id&.to_s, account_id: account_id&.to_s }
|
|
48
|
+
values[:visitor_id] = visitor_id&.to_s unless UNSET.equal?(visitor_id)
|
|
49
|
+
current.merge!(values)
|
|
44
50
|
end
|
|
45
51
|
|
|
46
52
|
def suppressed? = Thread.current[:rails_mind_suppressed] == true
|
|
@@ -22,16 +22,19 @@ module RailsMind
|
|
|
22
22
|
release_present: !@config.release.to_s.strip.empty?,
|
|
23
23
|
enabled: @config.enabled?,
|
|
24
24
|
automatic_sampling: @config.automatic_sampling,
|
|
25
|
+
page_views: @config.page_views,
|
|
26
|
+
visitor_cookie: @config.visitor_cookie,
|
|
27
|
+
link_page_views_to_users: @config.link_page_views_to_users,
|
|
25
28
|
plan: [
|
|
26
29
|
"Add one initializer. No database migrations or Gemfile changes.",
|
|
27
30
|
"Requests: automatic sampling of routine successes; jobs via Rails notifications and errors via Rails.error stay unsampled.",
|
|
28
|
-
|
|
31
|
+
"Page views: HTML pages your controllers render are counted with a first-party visitor cookie; config.page_views, config.visitor_cookie and config.link_page_views_to_users turn parts off.",
|
|
32
|
+
("Ahoy detected: RailsMind no longer reads Ahoy and counts page views itself. Remove any require \"rails_mind/integrations/ahoy\" and RailsMind::Integrations.mirror_ahoy! call, or the app fails at boot; Ahoy keeps its own tables." if detected["ahoy_matey"]),
|
|
29
33
|
detected["opentelemetry-sdk"] ? "OpenTelemetry detected: attach RailsMind exporter after existing SDK setup; preserve sampler and exporters." : "APM traces: optionally add selected OpenTelemetry libraries and explicitly configure one provider.",
|
|
30
34
|
detected["flipper"] ? "Flipper detected: observe notifications only; preserve adapter, groups, targeting and cache." : "Flags: Flipper is optional. No flag configuration is created.",
|
|
31
35
|
"Existing error reporters stay installed. RailsMind deduplicates its own collector only.",
|
|
32
|
-
"Browser: optional Ahoy adapter; enable only after checking existing pageview handlers.",
|
|
33
36
|
"Business/error signals are not sampled; routine requests follow the hosted policy. Local opt-out does not disable server sampling or quotas. Inspect RailsMind.stats for queue losses and unconfirmed delivery."
|
|
34
|
-
],
|
|
37
|
+
].compact,
|
|
35
38
|
limitations: [ "Compatibility applies to tested versions only; this is not a historical import.",
|
|
36
39
|
"No network check is performed and credential values are never printed." ]
|
|
37
40
|
}
|