rails_pulse 0.4.0.pre.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50a1c2016eee54e3ceda7d6e390669b7dc3f427a637cc975a50e9d682262411a
-  data.tar.gz: dfd20c8b99bdb1f3986aa143fb8cfe5aaf3935f7ba7cd43e4c6883721de30ad7
+  metadata.gz: 851f283c6c93bde26b1f79d3053a9cb7888381eedb0cd82118fdfbae6abf2a59
+  data.tar.gz: 622ea59d374bac1a3aa0b1dea374d86537b8bf815c1546b00c1545ee1e6787f7
 SHA512:
-  metadata.gz: caaf4f2932c7c639e7684fe3a8f4a789b4fe2d7a6b888d9cbeaf302487319efe758b91699f0eef1372cdad385f12269a1a78d9989bf29f855c20bf86c1c322e2
-  data.tar.gz: 852e0524002c525ca784c981c21234a750a2e5d9bc29024290c49d653df4fc806edd0c23e767b9e26be945ed81fafa37cf7474a7354e89ff533cf92a142eafda
+  metadata.gz: f4462e133722e0ef971e3f3c75fe0ea26f23c8167f24d31a8817550c6b91fe1cfd0bf6a35f59d29bd32cc432a9951de77fecdbb09e131fb385ddfe628d6ab660
+  data.tar.gz: 0c7d9706fc3a128b7c48fc4d09b78a698ff00bdd2e9b110e360c8124d5fccb5e552e4d351da70623f5d392c4c69916dbd39f930e0c1ef62eac2d3832db481cb5

data/CHANGELOG.md

@@ -7,114 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.0.pre.4] - 2026-09-07
+## [0.4.0] - 2026-09-22
 
-## [0.4.0.pre.3] - 2026-09-06
+## [0.4.0] - 2026-09-22
 
-### Added
-
-- **Shell-based deployment tracking.** `rake rails_pulse:record_deployment` and the new `rake rails_pulse:finish_deployment[revision]` let release scripts record and close deployments without the HTTP API or a token.
-- **Standalone mode improvements.** Dashboard links now resolve correctly when served at `/`, and a new `config.standalone_authentication_method` (with an HTTP Basic fallback) replaces host-app authentication, which the standalone process can't use.
-- **`rails rails_pulse:status`.** Reports schema, migration, and tracking/auth config state in one command, and exits 1 if anything needs action before deploying.
-- **Schema drift guard.** `RailsPulse::SchemaCheck` detects tables or columns the running gem expects but that haven't been migrated yet, and pauses tracking (dashboard returns 503) with a clear warning instead of erroring. Disable with `config.schema_check_enabled = false`.
-
-### Fixed
-
-- Fixed breadcrumb links becoming protocol-relative (`//queries`) when the engine is mounted at `/`.
-- Fixed the standalone dashboard server 404ing on its own stylesheets and scripts.
-- Fixed asset responses using mixed-case headers, which `Rack::Lint` rejects under Rack 3.
-- Fixed `rails_pulse_server` ignoring `RAILS_ENV`/`RACK_ENV` and always booting `rackup` in development mode.
-- Fixed the standalone server requiring a literal `SECRET_KEY_BASE` instead of falling back to the host app's.
+Route identity changes in this release and the schema migration is irreversible, so upgrading from any 0.3.x release needs a backup and a one-time data migration. Start with "Upgrading from 0.3.x" below.
 
-### Security
-
-- Updated development dependencies mail, net-imap, and json for several CVEs (gem dev/CI only).
-- Updated development dependencies nokogiri, loofah, and rails-html-sanitizer for several CVEs (gem dev/CI only).
-- Updated development dependencies Rails, puma, websocket-driver, and concurrent-ruby for Dependabot's critical/high alerts. Host apps should update their own Rails to 8.1.3.1.
-
-### Changed
-
-- `rails generate rails_pulse:upgrade` now reports unrun migrations and outstanding route backfill instead of saying everything is up to date.
-- Cleaned up `rake test` output — no more RDoc warnings, stray blank lines, or leaked log noise.
+### Upgrading from 0.3.x
 
-## [0.4.0.pre.2] - 2026-09-04
+Applies to every 0.3.x release (0.3.0 through 0.3.3). **Back up your database first.**
 
-### Fixed
+```bash
+bundle update rails_pulse
+rails generate rails_pulse:upgrade
+rails db:migrate                  # separate Pulse database: rails db:migrate:rails_pulse
+rails rails_pulse:migrate_routes  # required — schema migrate alone leaves Action empty
+rails rails_pulse:status          # exits 1 while anything still needs action
+```
 
-- Fixed `rails generate rails_pulse:upgrade` writing a migration that failed to parse when a column comment contained an escaped quote.
-- Fixed background tracking writes corrupting the test database connection under transactional tests. Existing installs should add `config.async = false if Rails.env.test?` to their initializer.
+Then restart **all** processes together, not as a rolling deploy. A 0.3.x process left running against the migrated schema stops tracking and 500s on the routes page. If the new gem is deployed before its migrations run, tracking pauses and the dashboard answers 503 with these commands until the schema is current.
 
-## [0.4.0.pre.1] - 2026-09-03
+Separate-database hosts: add `schema_dump: false` to the `rails_pulse` entry in `config/database.yml` and delete `db/rails_pulse_structure.sql` if it exists. Do not run `db:setup` / `db:prepare` as a substitute for `db:migrate:rails_pulse`.
 
-This release contains a **breaking schema change** and requires a one-time data migration. Back up your database first — the route migration is irreversible. See "Upgrading from 0.3.x" below.
+The upgrade generator appends this version's new settings to `config/initializers/rails_pulse.rb` without changing existing values; review them with `git diff`. Exception tracking is inserted as `config.track_exceptions = false`; set it to `true` once you have reviewed what is captured. Authentication is now on outside development and test, not only in production, so configure `config.authorize` before deploying to staging.
 
 ### Security
 
-- Job failure messages (`rails_pulse_job_runs.error_message`) are now redacted the same way exception messages are.
-- CSRF protection is now declared directly by the engine instead of depending on the host's `load_defaults` version.
-- Fixed `authentication_method` granting access when it returned a falsy-but-not-`false`/redirect value; it's now fail-closed.
-- Hardened EXPLAIN analysis against SQL injection and added a statement timeout.
-- Bounded deployment API input (revision length, metadata size, future timestamps) and capped the `rails_pulse_deployments` row count.
-- Backtrace source snippets are now limited to `app/`, `lib/`, and `config/routes.rb`, instead of any file under `Rails.root`.
-- The standalone dashboard's session cookie is now `Secure` in production.
+- Job failure messages (`rails_pulse_job_runs.error_message`) are redacted the same way exception messages are.
+- CSRF protection is declared directly by the engine instead of depending on the host's `load_defaults` version.
+- Authentication hooks fail closed: an `authentication_method` that returns a falsy-but-not-`false` or redirect value no longer grants access, and authentication is on by default outside development and test rather than only in production.
+- EXPLAIN analysis is hardened against SQL injection and runs under a statement timeout.
+- Deployment API input is bounded (revision length, metadata size, future timestamps) and the deployments table is capped.
+- Backtrace source snippets are limited to `app/`, `lib/` and `config/routes.rb` instead of any file under `Rails.root`.
+- The standalone dashboard's session cookie is `Secure` in production.
+- Development dependencies updated for several CVEs (gem dev/CI only). Host apps should keep their own Rails current.
 
 ### Added
 
-- **Exception tracking.** Captures unhandled exceptions from requests and jobs, with grouping, backtraces, and redacted params in a new Exceptions tab.
-- **`track_exceptions` config option**, off by default for existing installs and on by default for new ones.
-- **`capture_exception_params` config option** to include filtered request params with each exception occurrence.
-- **`exception_message_filter` config option** for app-specific redaction beyond the built-in rules.
-- **`authorize` config option** — a fail-closed predicate for gating dashboard access; now the recommended approach.
-- **The upgrade generator now syncs new initializer settings** into the host's config file without overwriting existing values.
+- **Exception tracking.** Unhandled exceptions from requests and jobs are grouped by class and location, with backtraces and redacted params, in a new Exceptions tab. Off after an upgrade and on for new installs (`config.track_exceptions`); `config.capture_exception_params` and `config.exception_message_filter` control what is stored.
+- **`config.authorize`**, a fail-closed predicate for gating dashboard access and now the recommended way to secure it.
+- **Schema drift guard.** When the gem is newer than its tables (deployed before `db:migrate`, or a rolling restart), tracking pauses and the dashboard answers 503 with the upgrade commands instead of erroring on every request. `config.schema_check_enabled = false` turns it off.
+- **`rails rails_pulse:status`** reports schema, migration, route backfill, initializer and summary state in one command and exits 1 when something needs action.
+- **Shell-based deployment tracking.** `rails rails_pulse:record_deployment[revision]` and `rails rails_pulse:finish_deployment[revision]` record and close deployments from release scripts without the HTTP API or a token.
+- **Standalone dashboard authentication.** `config.standalone_authentication_method` (HTTP Basic against `RAILS_PULSE_USERNAME` / `RAILS_PULSE_PASSWORD` by default) replaces the host hooks, which the standalone process cannot run.
+- **`config.async_queue_size`** bounds the background writer queue (default 1000), and `RailsPulse::Tracker.stats` reports what was dropped.
+- The upgrade generator syncs new initializer settings into the host's initializer without overwriting existing values, and reports unrun migrations and outstanding route backfill instead of saying everything is up to date.
 
 ### Changed
 
-- **BREAKING — route identity is now `[controller_action, path]`**, so different HTTP methods on the same path are tracked as distinct routes.
-- **A one-time `rails rails_pulse:migrate_routes` backfill is required** after migrating; a schema migrate alone leaves the Action column empty.
-- **The JavaScript bundle is 66% smaller** (2.19 MB → 759 KB) after tree-shaking ECharts.
+- **BREAKING: route identity is now `[controller_action, path]`.** Different HTTP methods on the same path are tracked as distinct routes, and a one-time `rails rails_pulse:migrate_routes` backfill is required after migrating.
+- **BREAKING: `rails_pulse_routes.method` is dropped and the migration is irreversible.** The HTTP verb now lives on each request. Restart all processes together after migrating.
+- **One writer thread per process.** Background tracking no longer spawns a thread per request, which could exhaust the app's connection pool under a burst. A single writer drains a bounded queue on one connection and drops the newest request when the queue is full rather than slowing the app; SQL normalisation and N+1 detection run there too, off the request thread.
+- **Summary aggregation upserts each period in bulk** instead of one statement per route, query and job, and runs its transaction on the Rails Pulse connection so separate-database installs cannot be left with partial summaries.
+- **Dashboard assets are no longer registered with Sprockets**, which fixes `assets:precompile` running out of memory on small hosts. `rails_pulse:install_assets` copies them into `public/assets` after precompile so `config.asset_host` and CDN-only CSP keep working; remove any `rails-pulse.js` / `rails-pulse.css` entries from `config.assets.precompile`.
+- Services under `app/services` autoload and reload through Zeitwerk like the rest of the engine.
+- The JavaScript bundle is 66% smaller (2.19 MB to 759 KB) after tree-shaking ECharts.
+- Ruby 3.1 is the minimum. The gem declared 3.0 but could not install there.
 
 ### Removed
 
-- **BREAKING — `rails_pulse_routes.method` is dropped**; the HTTP verb now lives on each request. Restart all processes together after migrating.
-- **BREAKING — the route migration is irreversible.** Back up your database first.
-- Removed three unused Stimulus controllers (`form`, `timezone`, `period_selector`).
-- Removed `theme.js`, a chart theme that was immediately overwritten and would have defeated ECharts tree-shaking.
-- Removed dead CSS: unused css-zero ports, old period-selector styles, and a disabled toolbox option.
-- `csp-test.js` is no longer shipped in the published gem.
+- **BREAKING: `rails_pulse_routes.method`** (see Changed).
+- `RailsPulse.warm_metric_cache!` and `RailsPulse.clear_metric_cache!`.
+- The `group_by_date` / `group_by_hour` methods the gem added to the host's `ActiveRecord::Relation`.
+- Three unused Stimulus controllers (`form`, `timezone`, `period_selector`), an unused chart theme, and dead CSS.
 
 ### Fixed
 
-- Fixed tag filters not matching tags containing `_` on SQLite.
-- Fixed various hand-edited or malformed query strings causing 500s instead of falling back to defaults.
-- Fixed chart click/zoom handlers accumulating on every chart tab switch, slowing clicks down over time.
-- Fixed zooming to the first column of a category chart resetting the range instead of applying it.
-- Fixed hover popovers throwing after a table refresh replaced the underlying element.
-- Fixed the time range selector's hover border being invisible due to an undefined CSS variable.
-- Fixed a duplicate CSS rule that made popover placement depend on file load order.
-- Fixed upgrading when using a separate database installation.
-- Separate-database installs now set `schema_dump: false` so `db:migrate` doesn't dump or load `db/rails_pulse_structure.sql` (#189).
-- Fixed `assets:precompile` OOMing on memory-constrained hosts by not registering dashboard assets with Sprockets.
-- Fixed SQLite's `schema.rb` dropping the partial unique index on unrecognised routes, which over-constrained paths on `db:schema:load`.
-
-### Upgrading from 0.3.x
-
-Applies to every 0.3.x release (0.3.0 through 0.3.3). **Back up your database first.**
-
-```bash
-bundle update rails_pulse
-rails generate rails_pulse:upgrade
-rails db:migrate                  # separate Pulse database: rails db:migrate:rails_pulse
-rails rails_pulse:migrate_routes  # required — schema migrate alone leaves Action empty
-```
-
-Then restart **all** processes together, not as a rolling deploy.
-
-Separate-database hosts: add `schema_dump: false` to the `rails_pulse` entry in
-`config/database.yml` and delete `db/rails_pulse_structure.sql` if it exists. Do not
-run `db:setup` / `db:prepare` as a substitute for `db:migrate:rails_pulse`.
-
-Exception tracking stays off after upgrading. Set `config.track_exceptions = true`
-once you have reviewed what is captured.
+- **Dashboard pages issue far fewer queries.** Tag filtering runs as subqueries inside each card and chart query, the route-backfill check is a single indexed query, and table sizes are cached for five minutes.
+- **Metric card sparklines are correct in time zones east of UTC.** Daily buckets follow `config.time_zone` instead of the stored UTC timestamp.
+- **Charts and metric cards honour a custom date range** instead of always showing the trailing days, and custom ranges no longer render blank charts when the server's OS time zone differs from `config.time_zone`.
+- A custom date range no longer 500s the dashboard on Marshal-backed session stores such as `activerecord-session_store`. (#252)
+- Idle periods no longer trigger false "summary job not running" warnings; `SummaryJob` records a zero-count summary for periods with no traffic. (#250)
+- The storage page reports real table sizes again instead of a leftover screenshot fixture's sample numbers.
+- Dashboard status bar badges for routes, queries and jobs are clickable, matching exceptions and storage.
+- Chart click/zoom handlers no longer accumulate on every tab switch, zooming to the first column of a category chart applies the range, hover popovers no longer throw after a table refresh, and the time range selector's hover border is visible.
+- Tag filters match tags containing `_` on SQLite, and malformed query strings fall back to defaults instead of returning 500.
+- **Lower per-query capture overhead.** The SQL, template and cache subscribers walk the call stack lazily and stop at the first app frame instead of materialising the whole stack on every event.
+- Cached SQL reads are no longer captured as operations, and `config.ignored_queries` is now applied (it was validated but never consulted).
+- The dashboard's own HTTP, mailer, job and storage events are no longer recorded.
+- `config.logger` is honoured; a custom logger set in the initializer receives all Rails Pulse output. (#244)
+- Background tracking writes no longer corrupt the test database connection under transactional tests. The initializer sets `config.async = false if Rails.env.test?`, and the tracker also writes inline whenever it detects a connection shared across threads.
+- Cleanup no longer risks statement timeouts on large tables: orphan checks use a correlated `NOT EXISTS` instead of `NOT IN`, so one stalled stage no longer blocks the rest. (#253)
+- **Standalone dashboard.** Settings forms no longer fail CSRF verification, the time range and filter pickers no longer 404, its own stylesheets and scripts are served, `RAILS_ENV` / `RACK_ENV` are respected, `SECRET_KEY_BASE` falls back to the host's, breadcrumb links are no longer protocol-relative when served at `/`, and the ignored-host-authentication notice is logged once per process.
+- Upgrading a separate-database install works, and those installs set `schema_dump: false` so `db:migrate` does not dump or load `db/rails_pulse_structure.sql`. (#189)
+- SQLite's `schema.rb` keeps the partial unique index on unrecognised routes across `db:schema:load`.
+- Asset responses use lowercase headers, which `Rack::Lint` requires under Rack 3.
 
 ## [0.3.3] - 2026-06-23
 
@@ -196,8 +173,8 @@ No changelog entry — see git history.
 
 No changelog entry — see git history.
 
-[Unreleased]: https://github.com/railspulse/rails_pulse/compare/v0.4.0.pre.1...HEAD
-[0.4.0.pre.1]: https://github.com/railspulse/rails_pulse/compare/v0.3.3...v0.4.0.pre.1
+[Unreleased]: https://github.com/railspulse/rails_pulse/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/railspulse/rails_pulse/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/railspulse/rails_pulse/compare/v0.3.2...v0.3.3
 [0.3.0]: https://github.com/railspulse/rails_pulse/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/railspulse/rails_pulse/compare/v0.2.6...v0.2.7

data/README.md

@@ -1,166 +1,138 @@
 <div align="center">
-  <img src="app/assets/images/rails_pulse/rails-pulse-logo.png" alt="Rails Pulse" width="200" />
+  <img src="app/assets/images/rails_pulse/rails-pulse-logo.png" alt="Rails Pulse" width="160" />
 </div>
 
----
-
 # Rails Pulse
 
-**Self-hosted performance monitoring for Rails apps**
+**Performance monitoring that lives inside your Rails app.** Slow requests, N+1 queries, background jobs and exceptions, stored in your own database. No agent, no account, no data leaving your servers.
 
 ![Gem Version](https://img.shields.io/gem/v/rails_pulse)
 ![Rails Version](https://img.shields.io/badge/Rails-7.2%2B-blue)
+![Ruby Version](https://img.shields.io/badge/Ruby-3.1%2B-red)
 ![License](https://img.shields.io/badge/License-MIT-green)
-![Ruby Version](https://img.shields.io/badge/Ruby-3.0%2B-red)
 
-Rails Pulse is a Rails engine that monitors your app's performance from the inside. It tracks slow requests, N+1 queries, SQL performance, background jobs, and unhandled exceptions. All data stays in your own database, no third-party cloud, no SaaS subscription, no data leaving your servers.
+Rails Pulse is a Rails engine. It hooks into the instrumentation Rails already emits, writes what it sees to a handful of tables, and mounts a dashboard that shows you where the time went. Install the gem, run one migration, schedule two jobs, and you have monitoring that works the same on SQLite, PostgreSQL and MySQL.
+
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/images/dashboard-dark.png">
+  <img src=".github/images/dashboard-light.png" alt="Rails Pulse dashboard: health bar for routes, queries, jobs, exceptions and storage; P95 response time, request rate and error rate with sparklines; response time percentiles against service level objective lines; and a ranked list of jobs and routes needing attention" width="100%">
+</picture>
+
+## What you get
 
-<table border="0">
-  <tr border="0" style="border:0">
-    <td border="0" style="border:0">
-    <img src="app/assets/images/rails_pulse/dashboard.png" alt="Dashboard" width="400" /></td>
-    <td style="border:0"><img src="app/assets/images/rails_pulse/request-show.png" alt="Request detail" width="400" /></td>
+- **The state of the app in one screen.** A health bar counts healthy, slow and critical routes, queries, jobs and exception groups. A ranked "needs attention" list tells you what to fix first.
+- **Every request, broken down.** Each request stores its route, status, duration and a timeline of the SQL, view, cache, HTTP, mailer and Active Storage operations inside it.
+- **Queries you can act on.** SQL is normalised and fingerprinted, so you see execution counts and P95 per statement shape, N+1 patterns, an EXPLAIN plan and index suggestions.
+- **Jobs and exceptions in the same place.** Duration, queue wait and failure rate for every Active Job class on any adapter. Unhandled exceptions from requests and jobs grouped by class and location, with filtered params and backtraces.
+- **Numbers over time.** Hourly, daily, weekly and monthly summaries with P50, P95 and P99, your service level objectives drawn as lines on the charts, and a marker for every deploy so a regression lines up with the release that caused it.
+- **Built for production.** Tracking is queued off the request thread and dropped rather than blocked under load. If the gem is deployed before its migrations, tracking pauses and tells you what to run. Retention is enforced by age and by row count so the tables never grow without bound.
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset=".github/images/request-dark.png">
+        <img src=".github/images/request-light.png" alt="Request detail: duration, status and response size, a performance breakdown by database, view and application time, and a request trace showing action, view and database operations on a timeline">
+      </picture>
+      <p align="center"><sub>A request and where its time went</sub></p>
+    </td>
+    <td width="50%" valign="top">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset=".github/images/query-dark.png">
+        <img src=".github/images/query-light.png" alt="Query diagnostics: query characteristics, an issue detected, an optimisation suggestion to add a composite index, and the execution plan">
+      </picture>
+      <p align="center"><sub>Diagnostics and an index suggestion for one query</sub></p>
+    </td>
   </tr>
   <tr>
-    <td style="border:0"><img src="app/assets/images/rails_pulse/query-show.png" alt="Query detail" width="400" /></td>
-    <td style="border:0"><img src="app/assets/images/rails_pulse/route-show.png" alt="Route detail" width="400" /></td>
+    <td colspan="2">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset=".github/images/route-dark.png">
+        <img src=".github/images/route-light.png" alt="Route detail: P95 response time, request rate and error rate cards, and a two-week P95 and P99 chart with service level objective lines and vertical deploy markers">
+      </picture>
+      <p align="center"><sub>One route over two weeks, with objective lines and deploy markers</sub></p>
+    </td>
   </tr>
 </table>
 
-## Installation
-
-Add to your Gemfile:
+## Quick start
 
 ```ruby
-gem 'rails_pulse'
+# Gemfile
+gem "rails_pulse"
 ```
 
-Run the installer:
-
 ```bash
 bundle install
 rails generate rails_pulse:install
 rails db:migrate
 ```
 
-Mount the dashboard in `config/routes.rb`:
-
 ```ruby
-Rails.application.routes.draw do
-  mount RailsPulse::Engine => "/rails_pulse"
-end
+# config/routes.rb
+mount RailsPulse::Engine => "/rails_pulse"
 ```
 
-Schedule the background jobs:
-
-```ruby
-RailsPulse::SummaryJob.perform_later  # cron: 5 * * * *
-RailsPulse::CleanupJob.perform_later  # cron: 0 1 * * *
+Schedule the summary job hourly and the cleanup job daily with whatever your queue adapter provides. With Solid Queue:
+
+```yaml
+# config/recurring.yml
+production:
+  rails_pulse_summary:
+    class: RailsPulse::SummaryJob
+    schedule: "5 * * * *"
+  rails_pulse_cleanup:
+    class: RailsPulse::CleanupJob
+    schedule: "0 1 * * *"
 ```
 
-Your dashboard is now at `http://localhost:3000/rails_pulse`.
+Open `http://localhost:3000/rails_pulse`. That's the whole setup.
 
-## Upgrading
+Requirements: Ruby 3.1+, Rails 7.2+ (tested on 7.2, 8.0 and 8.1), SQLite, PostgreSQL or MySQL.
 
-From 0.3.3:
+Full install guide, including a separate database and plain cron: [railspulse.com/documentation/installation](https://railspulse.com/documentation/installation)
 
-```bash
-bundle update rails_pulse
-rails generate rails_pulse:upgrade
-rails db:migrate                  # or: rails db:migrate:rails_pulse
-rails rails_pulse:migrate_routes  # required — fills Action and merges same-action paths
-```
-
-Restart all processes after migrate. This release changes how routes are stored (`method` moves off the route onto each request), so mixed old/new processes are not supported.
+## Going further
 
-The upgrade generator appends new settings to `config/initializers/rails_pulse.rb` without rewriting what you already set. Review with `git diff` and keep or discard hunks.
-
-To see where an install stands at any point — schema, unrun migration files, route backfill, initializer — run `rails rails_pulse:status`. It exits 1 when something needs action, so it can gate a deploy.
-
-Exception tracking is **off** for existing installs. The generator inserts `config.track_exceptions = false`; set it to `true` after migrating to opt in:
-
-```ruby
-config.track_exceptions = true
-config.capture_exception_params = true  # params are filtered via Rails' filter_parameters
-```
-
-Separate-database hosts: set `schema_dump: false` on the `rails_pulse` entry in `config/database.yml` and delete `db/rails_pulse_structure.sql` if that file exists.
-
-If you previously added `rails-pulse.js` / `rails-pulse.css` to `config.assets.precompile`, remove those entries — the gem no longer registers dashboard assets with Sprockets (that re-minify OOMs small hosts). Production deploys that use `config.asset_host` or a CDN-only CSP should run `assets:precompile` so `rails_pulse:install_assets` copies digested files into `public/assets`.
-
-Full install guide: [railspulse.com/documentation/installation](https://railspulse.com/documentation/installation)
-
-Separate database setup: [railspulse.com/documentation/database](https://railspulse.com/documentation/database)
-
-## Configuration
-
-Rails Pulse works out of the box with sensible defaults. To customise, edit `config/initializers/rails_pulse.rb`:
+**Lock it down.** The dashboard is authenticated by default outside development and test. Point it at your own auth with a predicate; anything but `true` is a 403.
 
 ```ruby
 RailsPulse.configure do |config|
-  config.enabled = true
-
-  config.request_thresholds = {
-    slow: 700,
-    very_slow: 2000,
-    critical: 4000
-  }
-
-  config.track_jobs = true
-  config.capture_job_arguments = false  # keep false to protect sensitive data
-
-  config.track_exceptions = true
-  config.capture_exception_params = true  # params are filtered via Rails' filter_parameters
-
-  config.full_retention_period = 30.days
+  config.authorize = ->(controller) { controller.current_user&.admin? }
 end
 ```
 
-Full configuration reference: [railspulse.com/documentation/advanced](https://railspulse.com/documentation/advanced)
+With nothing configured it falls back to HTTP Basic against `RAILS_PULSE_USERNAME` and `RAILS_PULSE_PASSWORD`. [Authentication guide](https://railspulse.com/documentation/authentication)
 
-## Authentication
+**Tune it.** Thresholds for slow, very slow and critical, service level objectives per percentile, what to ignore, what to tag, how long to keep. All in `config/initializers/rails_pulse.rb`. [Configuration reference](https://railspulse.com/documentation/advanced)
 
-Rails Pulse has no built-in user accounts; you protect the dashboard using your app's existing auth. Authentication is on by default outside development and test, and with nothing configured it falls back to HTTP Basic against `RAILS_PULSE_USERNAME` / `RAILS_PULSE_PASSWORD` (denying everything if the password is unset).
+**Run the dashboard on its own.** `bundle exec rails_pulse_server` serves the UI from a separate process with its own health endpoint, so a slow report never competes with your app for a thread. [Deployment modes](https://railspulse.com/documentation/deployment-modes)
 
-The simplest hook is a predicate that receives the controller and returns `true` to allow — anything else is a 403:
-
-```ruby
-RailsPulse.configure do |config|
-  config.authorize = ->(controller) { controller.current_user&.admin? }
-end
-```
+**Mark your deploys.** `rails rails_pulse:record_deployment[sha]` from a release script, or `POST /rails_pulse/deployments` with a token from CI, and every chart draws a line at that moment.
 
-If you need to redirect to a login page instead, use `authentication_method`, which runs inside the controller and denies by rendering or redirecting:
+**Keep it in its own database.** `rails generate rails_pulse:install --database=separate` puts the tables somewhere your primary never has to vacuum. [Database setup](https://railspulse.com/documentation/database)
 
-```ruby
-RailsPulse.configure do |config|
-  config.authentication_redirect_path = "/login"
+## Upgrading
 
-  config.authentication_method = proc {
-    unless user_signed_in? && current_user.admin?
-      redirect_to main_app.root_path, alert: "Access denied"
-    end
-  }
-end
+```bash
+bundle update rails_pulse
+rails generate rails_pulse:upgrade
+rails db:migrate                  # separate Pulse database: rails db:migrate:rails_pulse
+rails rails_pulse:status          # exits 1 while anything still needs action
 ```
 
-Returning `false` from `authentication_method` without responding is also treated as a denial, but `nil` (what `unless … end` returns on success) allows the request — so keep predicate-style checks in `authorize`.
-
-Authentication guide: [railspulse.com/documentation/authentication](https://railspulse.com/documentation/authentication)
-
-## Features
-
-- **Request monitoring** — every request is timed and stored with its route, status, SQL count, and duration. Slow requests are flagged automatically based on thresholds you control.
-- **Query analysis** — captures the queries behind each request, detects N+1 patterns, and tracks normalized SQL across requests so you can see which queries are hurting you in production, not just in development.
-- **Job tracking** — monitors background job duration, queue wait time, and failure rates. Works with any Active Job adapter.
-- **Exception tracking** — captures unhandled exceptions from web requests and background jobs, groups them by class and location, and shows full backtraces with filtered request params. See recurring errors in production without a separate error monitoring service.
-- **System health bar** — at-a-glance dashboard summary showing healthy, slow, and critical counts across your routes, queries, jobs, and storage. Lets you see the overall state of your app before drilling into specifics.
-- **No data leaves your app** — everything is stored in your own database. No third-party cloud, no SaaS subscription, no outbound connections.
-- **Low overhead** — tracking is async and uses a thread-local flag to skip recording Rails Pulse's own internal requests.
+Upgrading from 0.3.x to 0.4? **Back up first**, run `rails rails_pulse:migrate_routes` after migrating, and restart every process together. The details are in the [changelog](CHANGELOG.md).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/railspulse/rails_pulse).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/railspulse/rails_pulse). `docs/` explains how the pieces fit and why they are built the way they are.
+
+```bash
+git config core.hooksPath .githooks   # once, after cloning
+DB=sqlite3 rake test                  # or DB=postgresql / DB=mysql2
+bundle exec rubocop
+```
 
 ## License
 

data/app/controllers/concerns/session_filters_concern.rb

@@ -24,10 +24,11 @@ module SessionFiltersConcern
     session_global_filters["disabled_tags"] || []
   end
 
-  # Returns the time range preference from session
-  # Can be a symbol/string for presets or a hash for custom ranges
+  # Returns the time range preference from session, normalized so every
+  # session serializer yields the same shape: a String preset name, a
+  # string-keyed Hash for a custom range, or nil for anything unrecognized.
   def session_time_range_preference
-    session[:time_range_preference]
+    RailsPulse::TimeRangePreference.normalize(session[:time_range_preference])
   end
 
   # Returns whether deployment markers should be shown by default

data/app/controllers/concerns/time_range_concern.rb

@@ -41,6 +41,11 @@ module TimeRangeConcern
     end_time = Time.zone.now
     selected_time_range = default_key
 
+    # Normalized up front so a symbol-keyed hash from a Marshal-backed session
+    # store reads the same as the string-keyed one the cookie store produces;
+    # anything unrecognized becomes nil and falls through to later priorities.
+    session_preference = RailsPulse::TimeRangePreference.normalize(session[:time_range_preference])
+
     # Priority 1: Page-specific preset from dropdown (check this first!)
     if ransack_params[:period_start_range].present? && ransack_params[:period_start_range].to_sym != :custom
       # Predefined time range from dropdown
@@ -76,25 +81,22 @@ module TimeRangeConcern
         selected_time_range = :custom
       end
     # Priority 4: Time range selector (from session)
-    elsif session[:time_range_preference].present?
-      preference = session[:time_range_preference]
-      if preference.is_a?(Hash) && preference["type"] == "custom"
-        # Custom range from time range selector
-        start_time = parse_time_param(preference["start_time"]) || start_time
-        end_time = parse_time_param(preference["end_time"]) || end_time
-        selected_time_range = :custom
-      else
-        # Preset from time range selector
-        selected_time_range = preference.to_sym
-        start_time =
-          case selected_time_range
-          when :last_24_hours  then 1.day.ago
-          when :last_7_days    then 1.week.ago
-          when :last_14_days   then 2.weeks.ago
-          when :last_30_days   then 1.month.ago
-          else start_time
-          end
-      end
+    elsif RailsPulse::TimeRangePreference.custom?(session_preference)
+      # Custom range from time range selector
+      start_time = parse_time_param(session_preference["start_time"]) || start_time
+      end_time = parse_time_param(session_preference["end_time"]) || end_time
+      selected_time_range = :custom
+    elsif session_preference.is_a?(String) && session_preference.present?
+      # Preset from time range selector
+      selected_time_range = session_preference.to_sym
+      start_time =
+        case selected_time_range
+        when :last_24_hours  then 1.day.ago
+        when :last_7_days    then 1.week.ago
+        when :last_14_days   then 2.weeks.ago
+        when :last_30_days   then 1.month.ago
+        else start_time
+        end
     # Priority 5: Global filters (from session)
     elsif session_global_filters["start_time"].present? || session_global_filters["end_time"].present?
       start_time = parse_time_param(session_global_filters["start_time"]) || start_time
@@ -105,6 +107,14 @@ module TimeRangeConcern
 
     time_diff = (end_time.to_i - start_time.to_i) / 3600.0
 
+    # in_time_zone before rounding: a parsed custom-range string carries the
+    # server OS's local offset, not Time.zone, and beginning_of_day/_hour
+    # round in whatever offset the receiver has. Summary data is always
+    # bucketed by Time.zone, so without this the boundary can miss every
+    # summary row and render charts empty. No-op for already-Time.zone values.
+    start_time = start_time.in_time_zone
+    end_time = end_time.in_time_zone
+
     if time_diff <= 25
       start_time = start_time.beginning_of_hour
       end_time = end_time.end_of_hour

data/app/controllers/rails_pulse/application_controller.rb

@@ -86,10 +86,12 @@ module RailsPulse
         session[:time_range_preference] = preset if TIME_RANGE_PRESETS.include?(preset)
       elsif start_time && end_time
         # Store custom range
+        # String keys: a Marshal-backed session store would otherwise hand the
+        # symbol keys back verbatim, and the readers expect the JSON shape.
         session[:time_range_preference] = {
-          type: "custom",
-          start_time: start_time,
-          end_time: end_time
+          "type" => "custom",
+          "start_time" => start_time,
+          "end_time" => end_time
         }
       end
 
@@ -172,11 +174,13 @@ module RailsPulse
       run_authentication_method(hook)
     end
 
+    # Logged once per process, not once per controller: the flag lives on
+    # RailsPulse::Standalone, so RequestsController and QueriesController do
+    # not each repeat it on their first request.
     def note_ignored_host_authentication(config)
       return if config.authentication_method.nil? && config.authorize.nil?
-      return if self.class.instance_variable_get(:@_rails_pulse_standalone_auth_noted)
+      return unless RailsPulse.note_host_authentication_ignored!
 
-      self.class.instance_variable_set(:@_rails_pulse_standalone_auth_noted, true)
       logger.info "RailsPulse: standalone dashboard ignores config.authentication_method / config.authorize " \
                   "(host session helpers are not available here); using HTTP Basic auth. " \
                   "Set config.standalone_authentication_method to customise."