solid_observer 0.1.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2e83e38f795537bcacb9a431fe39543476b615cb205904fd5af324a4a1886e8
-  data.tar.gz: cf501ff1b33535eb7a2b4f4858289bea3c93af7371af83bb867255b3f00de462
+  metadata.gz: a9c3e774c9276371b59f696226979b922772191e0531a4d9ba2dbb09b8e3e452
+  data.tar.gz: 570ae5aacef981358f68998d3df14bfc532e2af48cbdd21c6cd18ecbfa7132e7
 SHA512:
-  metadata.gz: 58fb350eda47268f65f13b71ac4f317fe7a9cd6274a05c636a4d7a91477ad5a6269a652a7bb537255cbce8e690231c6bd33507530baf6fb626e672b738bf175b
-  data.tar.gz: 9042759cdeca68bf9fd50a0c62493c6e9d057915b714cb8d68ef81f36028e6437c8f85dfeab8bac971419bc8471b147840051aa881a01871f720640f4abdfdb9
+  metadata.gz: 50684bd0b286fc9b93f77a57f5d0b60c3e0334b6d7804bf63307b8cdc05a78cab5bb586305b96617f5fe0e76f76cd89112c6cb6e059a45d190ca6dc7c49fa885
+  data.tar.gz: 9e456400209630d4e3b777355bf1d1a651e0bac1d90d6d40de4272c9cce8afb322bf5ff9afed10fe1a9e0911c7e84c15d02e6b2de3360e04f5d4d349bbf02f34

data/CHANGELOG.md

@@ -1,3 +1,87 @@
+## [0.4.0] - 2026-06-03
+
+Headline: **Solid Cache observability** — multi-component foundation, cache dashboard, operational controls, and shared storage health.
+
+### Added
+- **Multi-component SolidObserver foundation** (SO-070) — refactored engine, configuration, and storage to support multiple Solid Stack components alongside Solid Queue. Introduced `observe_cache` config flag (default `false`).
+- **Cache telemetry foundation** (SO-071) — `CacheSubscriber` hooks into `ActiveSupport::Notifications` cache events; collects hit/miss/write/delete/prune operations with duration and error tracking. Keys and values are never recorded.
+- **Cache metrics aggregation** (SO-072) — `CacheMetricsAggregator` computes hit rate, operations/sec, error rate, and average duration from raw cache events; scoped to configurable time windows.
+- **Multi-component storage health** (SO-073) — Storage page aggregates Queue Observer DB, Cache Observer, and SolidCache table sizes into unified per-component rows with status indicators.
+- **Cache operational controls** (SO-074) — Cache controls dashboard page; `solid_observer:cache:clear` and `solid_observer:cache:prune` rake tasks; CSRF-protected prune/clear actions in the Web UI.
+- **Cache dashboard** (SO-075) — `/solid_observer/cache_dashboard` — hit rate, ops/sec, error rate, avg duration, storage footprint, activity trend sparklines, and stability pill.
+- **Cache overview activity trends and health parity** (SO-077) — activity trend sparklines on the cache dashboard; stability indicator parity with the Queue dashboard.
+
+### Fixed
+- **SolidCache storage snapshot TypeError** (SO-076) — `StorageInfoSnapshot` raised `TypeError: nil can't be coerced into Integer` on PostgreSQL hosts when SolidCache table names resolved to `nil`. Fixed with a nil-table-name guard on the PG size query path.
+- **Failed-job error payload read as Hash** (SO-079) — `Jobs::Show` raised `NoMethodError` when the serialised `SolidQueue::FailedExecution#error` payload was a plain `Hash` instead of an `ActiveSupport::HashWithIndifferentAccess`. Now reads both representations safely.
+
+### Changed
+- **Cross-tab styling consistency** (SO-078) — unified badge colours, font sizes, and border radii across Queue and Cache dashboard tabs so both surfaces share the same visual language.
+- **Dashboard headers, select heights, and Storage nav** (SO-080) — normalised `<h1>` sizing, select control heights, and Storage navigation link to be consistent across all component tabs; Storage promoted to top-level nav item.
+
+## [0.3.0] - 2026-05-25
+
+> Note: there is no separate `0.2.0` gem release — work originally scoped for v0.2.0 (stability + refactoring, SO-040 through SO-049) was folded into this release.
+
+Headline: **Web UI Dashboard** + stability hardening from pre-release review.
+
+### Added
+- Web UI dashboard at `/solid_observer` — queue stats, jobs browser, events log, storage info, responsive layout, optional HTTP Basic Auth
+- Web UI config: `ui_enabled`, `ui_username`, `ui_password`, `ui_base_controller`, `ui_refresh_interval`
+- Dashboard "Live" toggle: when enabled, only the Right-Now card region (`so_right_now` Turbo Frame) reloads on the configured cadence (`SolidObserver.config.ui_refresh_interval`). Scoped cards stay frozen until the range selector changes. Toggle state lives in the `?live=on` URL param so it survives range navigations.
+- Dashboard now supports a Time-Range selector (`15m`, `30m`, `1h`, `7h`, `1d`, `7d`, `14d`, default `1h`) that scopes the new "Last <range>" card region (Performed / Failed / Enqueue rate). The "Right Now" region (Ready / Scheduled / Claimed / Failed-awaiting-retry / Workers) is unaffected by the range and reflects current SolidQueue state.
+- Retry / discard actions with confirmation dialogs and CSRF protection
+- `QueueEventBuffer#metrics` and `#shutdown` (graceful drain on app exit)
+- Configuration: `max_buffer_size` (default 10_000), `buffer_overflow_strategy` (`:drop_old` / `:drop_new`), `filter_cache_ttl`
+- `Services::DatabaseSize` for cross-adapter table-size measurement; composite indexes and `distinct_job_classes` / `distinct_queue_names` scopes
+- Dashboard now shows three throughput counters (Performed last hour, Failed last 24h, Enqueue rate last 5 min) sourced from the events table, alongside existing point-in-time counters. Throughput counters are persistence-mode only.
+- Stat counter subtitles ("queued" / "future runs" / "in progress" / "awaiting retry" / "active processes") clarify SolidQueue lifecycle terminology.
+- Conceptual hint banner on the dashboard explains the difference between Jobs tab (in-flight + failed) and Events tab (historical record).
+- Jobs tab now has an empty state with a hint pointing to Events tab for completed-job history.
+- Dashboard polled chart strip and unified card grid: a JSON-fed polling client refreshes six stat cards (Ready, Scheduled, Claimed, Workers, Failed, Enqueue Rate) and three sparklines (Performed/min, Ready depth, Failed/min) every `SolidObserver.config.ui_refresh_interval` seconds (default `30`, `0` disables polling). In realtime mode only the Ready sparkline renders and the Enqueue Rate card is omitted. Toggle in the dashboard top bar enables/disables polling; state lives in `?live=on` URL param. Hand-rolled inline-SVG sparklines, no JS framework, no external chart library.
+
+### Fixed
+- **Duration was displayed off by 1000x.** `RecordEvent` stored `ActiveSupport::Notifications::Event#duration` (milliseconds) directly; `format_duration` interpreted it as seconds. Fixed by converting ms → seconds at write time. No data migration needed (fixed before v0.3.0 release); run `bin/rails solid_observer:storage:purge` to clear pre-fix local data.
+- **Dashboard chart strip renders populated polylines on first paint** instead of empty placeholders. Server-side `spark_points` helper mirrors the JS `Sparkline.render` projection formula so the first HTML response ships with real data; the first JS poll appends one additional segment with no visible "empty → full" transition.
+- **Live toggle cadence label stays in sync with toggle state.** The `.so-toggle__cadence` span now carries `aria-live="polite"` and is updated in the same synchronous tick as the `--on` class toggle. Server-side ERB hardcodes `"5s"` / `"off"` matching the JS literals.
+- Jobs details page no longer crashes for `SolidQueue::FailedExecution`; Queue and Priority now fall back to underlying `SolidQueue::Job` values and show `N/A` when unavailable.
+- Web UI now works on API-only Rails hosts. The engine ships its own Cookies / Session::CookieStore (`key: "_solid_observer_session"`) / Flash middleware stack, so requests routed to `/solid_observer/*` get the middleware they need regardless of whether the host app strips them via `config.api_only = true`. Previously, API-only hosts hit `NoMethodError: undefined method 'flash' for an instance of ActionDispatch::Request` rendering the dashboard layout.
+- `bin/rails solid_observer:install:migrations` now respects `migrations_paths` from the `solid_observer_queue` connection in `config/database.yml`. When the host configures a dedicated migration folder (e.g. `db/solid_observer_migrate`), the install task copies migrations directly there instead of `db/migrate/`. Previously, operators in multi-database setups had to manually move the files after install to prevent cross-database migration contamination.
+- Web UI now degrades gracefully when the `solid_observer_queue` database is missing or unreachable at request time. Previously, requests to `/solid_observer/*` raised `ActiveRecord::NoDatabaseError` / `ConnectionNotEstablished` with a raw 500 stack trace. The engine now renders a 503 "Storage unavailable" page using the dashboard layout, with an actionable hint to run migrations or check `database.yml`. Realtime mode is unaffected. Boot-time resilience (Engine activation skip) was already in place; this closes the equivalent gap at request time.
+- Engine boot no longer requires a live DB (Docker/CI/K8s safe); table check uses `BaseEvent.connection_pool` (multi-DB safe); broader rescue covering adapter-specific connection errors
+- `QueueEventBuffer` hard-caps at `max_buffer_size` with overflow strategy; uses a single persistent `Concurrent::TimerTask` instead of spawning a thread per flush
+- Storage monitoring uses adapter-native size queries (SQLite / PostgreSQL / MySQL / Trilogy) — fixes `0 MB` readings off SQLite
+- `EventsController` and `JobsController` filter dropdowns no longer full-table-scan on every request (cached via `filter_cache_ttl`)
+- `RecordEvent` correctly handles real `ActiveJob::Base` payload objects (with hash fallback)
+
+### Security
+- Job arguments removed from persisted event metadata and the jobs detail view (PII reduction)
+- Web UI HTTP Basic Auth now requires **both** `ui_username` and `ui_password` to be configured. Previously, setting only `ui_username` (with `ui_password` missing or `nil`) would still trigger an auth challenge that any blank-password request would pass `secure_compare("", "")`, granting unauthenticated access. The README's "both must be set" guidance now matches the implementation; misconfigured auth now ships unauthenticated rather than allowing a bypass.
+- Boot-time `Engine.check_ui_authentication` now warns on partial misconfiguration (exactly one of `ui_username` / `ui_password` set), naming the missing credential. Previously the check exited silently as soon as `ui_username.present?`, hiding the fail-open auth misconfiguration from operators.
+
+### Documentation
+- Documented multi-adapter installation (PG host + SQLite observer DB) inline in Database Setup, with explicit `adapter:` override, `gem "sqlite3"` Bundler note, `migrations_paths` migration-isolation guidance, and cross-reference from the install steps.
+
+### Removed
+- Removed the legacy implicit dashboard auto-refresh (`<meta http-equiv="refresh">` plus inline fetch/DOM-swap script for `.so-content`). Replaced by explicit, opt-in Live Mode targeting only the Right-Now frame.
+- Removed the legacy `GET /solid_observer/right_now` HTML endpoint and its action template (it was the SO-060-era polling target that returned a partial-only HTML response wrapped in a turbo-frame). Replaced by `GET /solid_observer/poll_data` which returns JSON for the polling client. The `live_poll.js` script-delivery route is unchanged.
+- **Removed `SolidObserver.config.ui_refresh_interval`** (was unreliable; cadence is now hardcoded at 5s). Upgrade note: remove the line from your initializer or boot will raise `NoMethodError`.
+
+### Changed
+- Web UI controllers refactored to thin actions + query/param/presenter objects; Rails built-in number helpers replace custom ones
+- Specs: `allow_any_instance_of` → `instance_double`; sleep-based timer specs use deterministic synchronisation; dead private-method `describe` blocks removed
+- `.reek.yml` suppressions trimmed; hot-path services/buffer/engine methods refactored to pass `TooManyStatements` without new suppressions
+- `SolidObserver.config.ui_refresh_interval` now controls Live Mode polling cadence instead of implicit full-page dashboard refresh. Default value is unchanged.
+- Dashboard default range is `15m` (was `1h`); aligns with poll default.
+- Live polling pauses while the tab is hidden and resumes on return (one immediate tick on visibility return so the user doesn't wait up to 5s for fresh data).
+- Jobs tab default filter changed from `status=ready` to `status=all_active` (ready + scheduled + claimed + failed).
+- Duration values on the Events index and detail pages now use per-event-type semantic context via `<abbr title="...">` tooltips so operators can distinguish enqueue call latency (`job_enqueued`) from perform-time duration (`job_completed` / `job_failed` / `job_discarded`).
+- Refreshed the engine UI to a minimalist visual language: light surfaces, near-black text, restrained semantic colour accents reserved for badges/state, hairline separators, consistent rounding. Sidebar moves from dark slate to a light surface. No external CSS dependencies, no JS, no dark mode (single light theme).
+- Dashboard: replaced the multi-line "Recent Failures" panel with a single-line **Stability** indicator (pill badge + summary + "View failures" link). Three states based on rolling failure counts: **Stable** (no failures in last 24h), **Degraded** (failures in last 24h but none in last hour), **Critical** (any failure in the last hour). Click-through targets the Events page filtered to `job_failed`.
+- Dashboard: removed the "Jobs tab / Events tab" orientation banner. The distinction is discoverable via navigation; the dashboard is reserved for signal.
+- Dashboard layout consolidated: dropped the previous two-frame split (Right-Now + Scoped) and the redundant Performed-in-range / Failed-in-range cards (those metrics now live in the polled sparkline strip).
+- Live toggle restyled as a pill switch with cadence visible in-line ("Live · 2s" / "Live · off") and a pulsing dot when active.
+
 ## [0.1.1] - 2026-02-10
 
 ### Added

data/README.md

@@ -2,40 +2,44 @@
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset=".github/solid_logo_dark.svg">
     <source media="(prefers-color-scheme: light)" srcset=".github/solid_logo_light.svg">
-    <img alt="SolidObserver" src=".github/solid_logo_light.svg" width="250">
+    <img alt="SolidObserver" src=".github/solid_logo_light.svg" width="220">
   </picture>
 </p>
 
 <p align="center">
-  <strong>Observe your Solid Stack like a pro!</strong>
-</p>
-
-<p align="center">
-  <a href="https://github.com/bart-oz/solid_observer/releases"><img src="https://img.shields.io/badge/version-0.1.1-blue.svg" alt="Version"></a>
+  <a href="https://github.com/bart-oz/solid_observer/releases"><img src="https://img.shields.io/badge/version-0.4.0-blue.svg" alt="Version"></a>
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
   <a href="https://github.com/bart-oz/solid_observer/actions"><img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests"></a>
-  <a href="https://github.com/bart-oz/solid_observer/actions"><img src="https://img.shields.io/badge/coverage-93.06%25-brightgreen.svg" alt="Coverage"></a>
+  <a href="https://github.com/bart-oz/solid_observer/actions"><img src="https://img.shields.io/badge/coverage-96.22%25-brightgreen.svg" alt="Coverage"></a>
 </p>
 
 ---
+<p align="center">
+  <a href=".github/assets/dash_1.png"><img src=".github/assets/dash_1.png" alt="SolidObserver dashboard overview" width="700"></a>
+</p>
+
+SolidObserver is a production-grade observability solution for Rails 8's Solid Stack. v0.4.0 covers both **Solid Queue** and **Solid Cache** with a unified Web UI dashboard, CLI tools, metrics collection, and distributed tracing support.
 
-SolidObserver is a production-grade observability solution for Rails 8's Solid Stack. Starting with **Solid Queue** monitoring in v0.1.0, it provides unified visibility into your background job processing with CLI tools, metrics collection, and distributed tracing support.
+## Features (v0.4.0)
 
-## Features (v0.1.1)
+| | Solid Queue | Solid Cache |
+|---|---|---|
+| **Web UI Dashboard** | Queue stats, jobs browser, events log | Hit rate, ops/sec, error rate, avg duration |
+| **Storage footprint** | DB size, event counts | SolidCache table size, row counts |
+| **Activity trends** | Sparklines (Performed, Ready, Failed) | Activity trend sparklines |
+| **Stability indicator** | Stable / Degraded / Critical badge | Stability pill badge |
+| **Operational controls** | Retry / discard failed jobs | Prune expired entries, clear all entries |
+| **CLI tools** | status, jobs:list/show/retry/discard | cache:prune, cache:clear |
+| **Privacy** | Job arguments excluded from persisted events | Keys and values **never** shown |
+| **Operating modes** | Real-time (no DB) or persistence (full history) | Persistence mode only |
 
-- 📊 **Real-time Queue Status** — Monitor jobs across all states (ready, scheduled, claimed, failed)
-- 🔍 **Job Management CLI** — List, inspect, retry, and discard failed jobs
-- 💾 **Storage Monitoring** — Track database size and event counts
-- 🔗 **Distributed Tracing** — Correlate jobs with APM tools (Datadog, Sentry, OpenTelemetry)
-- ⚡ **High Performance** — Buffered writes, configurable sampling, minimal overhead
-- 🛡️ **Production Ready** — Automatic cleanup, size limits, retention policies
-- 🚀 **Two Operating Modes** — Real-time (no migrations) or persistence (full event history)
+Additional: 🔗 APM distributed tracing · ⚡ buffered writes · 🛡️ Docker/CI/K8s safe boot
 
 ## Requirements
 
 - Ruby 3.2+
 - Rails 8.0+
-- Solid Queue (properly configured for all environments)
+- Solid Queue (configured with `connects_to` in all environments)
 
 > **Note:** Ensure Solid Queue is configured with `connects_to` in all environments, not just production. See [Troubleshooting](#troubleshooting) if you encounter database connection issues.
 
@@ -69,7 +73,9 @@ That's it. You now have access to queue status, job listing, retry, and discard
 
 ### Persistence Mode (default)
 
-Store event history, metrics, and storage snapshots in a dedicated SQLite database. This gives you everything in real-time mode plus long-term event tracking, buffered writes, and retention-based cleanup.
+Store event history, metrics, and storage snapshots in a dedicated observer database. This gives you everything in real-time mode plus long-term event tracking, buffered writes, and retention-based cleanup. The install generator defaults to SQLite; the database can use any Rails-supported adapter for record persistence, and storage-size monitoring is implemented for SQLite, PostgreSQL/PostGIS, MySQL, and Trilogy. See [Database Setup](#database-setup-persistence-mode) below.
+
+> If your host app uses a different adapter than SQLite (e.g. PostgreSQL or MySQL), see [Multi-adapter setup](#multi-adapter-setup) before running these commands.
 
 ```bash
 bin/rails solid_observer:install:migrations
@@ -77,7 +83,7 @@ bin/rails db:create
 bin/rails db:migrate
 ```
 
-No additional configuration needed — persistence is the default `storage_mode`.
+For SQLite-default apps, no further configuration is needed — persistence is the default `storage_mode`.
 
 ## Quick Start
 
@@ -134,8 +140,17 @@ bin/rails "solid_observer:jobs:retry[JOB_ID]"
 bin/rails "solid_observer:jobs:discard[JOB_ID]"
 ```
 
+### Events Page Filters (Web UI)
+
+Filter dropdowns on `/solid_observer/events` (job class and queue) are cached for 1 minute by default and scoped to the configured retention window.
+Tune the cache TTL with `config.filter_cache_ttl`.
+
 ### Check Storage (Persistence Mode)
 
+Storage monitoring is cross-adapter: SQLite, PostgreSQL, MySQL, and Trilogy are supported.
+SolidObserver uses adapter-native SQL queries to measure size (not filesystem `File.size`),
+so production deployments report real values even when the database is remote.
+
 ```bash
 bin/rails solid_observer:storage
 ```
@@ -154,8 +169,122 @@ Configuration:
   Warning:   80% threshold
 ```
 
+## Web UI Dashboard
+
+SolidObserver ships with a zero-dependency Web UI (no asset pipeline, no JS framework) at `/solid_observer`.
+
+### Mount
+
+The install generator mounts it for you. To mount manually:
+
+```ruby
+# config/routes.rb
+mount SolidObserver::Engine, at: "/solid_observer"
+```
+
+### Auth Configuration
+
+```ruby
+SolidObserver.configure do |config|
+  config.ui_enabled          = !Rails.env.production?  # default: true outside production
+  config.ui_username         = "admin"                 # HTTP Basic Auth: BOTH username AND password must be set
+  config.ui_password         = ENV["SOLID_OBSERVER_PASSWORD"]
+  config.ui_base_controller  = "ApplicationController" # name of your host app's base controller (used for API-only detection)
+end
+```
+
+| Option | Default | Purpose |
+|---|---|---|
+| `ui_enabled` | `!Rails.env.production?` | Master switch for the Web UI |
+| `ui_username` / `ui_password` | `nil` | HTTP Basic Auth. Auth is enabled only when **both** are set |
+| `ui_base_controller` | `"ApplicationController"` | Detect API-only apps to include rendering modules |
+
+For production hardening (fail-loud on missing env var vs. fail-open), see [Configuration](#configuration) below.
+
+### Caveats
+
+- **Realtime mode** — Events and Storage navigation links are hidden. Direct visits redirect with a flash alert.
+- **API-only apps** — the Web UI works without manual configuration. The engine ships its own Cookies/Session/Flash middleware stack scoped to `/solid_observer/*`.
+- **Host-app callbacks are not inherited.** Use `ui_username` / `ui_password` for built-in HTTP Basic Auth.
+- **Auth misconfiguration is fail-open, but loud.** If `ui_username` is set but `ui_password` resolves to `nil`, the UI ships unauthenticated and logs a boot `WARNING`.
+
+See the full component breakdown in [Components](#components) below.
+
+## Components
+
+### Solid Queue Observability
+
+Live queue stats, job browser (all states: ready/scheduled/claimed/failed), events log, time-range selector (15m → 14d), sparklines for Performed/Ready/Failed, stability indicator, retry/discard with confirmation dialogs. Realtime and persistence modes supported.
+
+<table>
+  <tr>
+    <td align="center"><a href=".github/assets/dash_2.png"><img src=".github/assets/dash_2.png" alt="Queue overview — 1d range" width="340"></a></td>
+    <td align="center"><a href=".github/assets/dash_3.png"><img src=".github/assets/dash_3.png" alt="Jobs list" width="340"></a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href=".github/assets/dash_4.png"><img src=".github/assets/dash_4.png" alt="Failed job detail" width="340"></a></td>
+    <td align="center"><a href=".github/assets/dash_5.png"><img src=".github/assets/dash_5.png" alt="Events stream" width="340"></a></td>
+  </tr>
+</table>
+
+**CLI commands (Solid Queue):**
+
+```bash
+bin/rails solid_observer:status                                # Queue overview
+bin/rails solid_observer:jobs:list                             # All active jobs
+bin/rails "solid_observer:jobs:list[failed]"                   # Failed jobs
+bin/rails "solid_observer:jobs:show[JOB_ID]"                   # Job details
+bin/rails "solid_observer:jobs:retry[JOB_ID]"                  # Retry failed job
+bin/rails "solid_observer:jobs:discard[JOB_ID]"                # Discard failed job
+bin/rails solid_observer:buffer:flush                          # Flush event buffer
+bin/rails solid_observer:buffer:clear                          # Clear buffer without saving
+```
+
+### Solid Cache Observability
+
+Cache dashboard shows hit rate, operations/sec, error rate, average duration, storage footprint, activity trend sparklines, and a stability pill. Cache controls page provides prune and clear operations. **Keys and values are never shown** — only aggregate metrics are collected.
+
+<table>
+  <tr>
+    <td align="center"><a href=".github/assets/dash_6.png"><img src=".github/assets/dash_6.png" alt="Cache overview dashboard" width="340"></a></td>
+    <td align="center"><a href=".github/assets/dash_7.png"><img src=".github/assets/dash_7.png" alt="Cache operational controls" width="340"></a></td>
+  </tr>
+</table>
+
+**Enabling Cache observability:**
+
+SolidCache must be configured in your host app (Rails 8 default). Then enable in the SolidObserver initializer:
+
+```ruby
+SolidObserver.configure do |config|
+  config.observe_cache = true  # default: false
+end
+```
+
+`solid_cache_enabled?` is `true` when both `observe_cache = true` and SolidCache is available in the host app.
+
+**CLI commands (Solid Cache):**
+
+```bash
+bin/rails solid_observer:cache:clear  # Clear all SolidCache entries (with confirmation)
+bin/rails solid_observer:cache:prune  # Prune expired SolidCache entries
+```
+
+### Storage
+
+The Storage page aggregates per-component health rows: Queue Observer database, Cache Observer, and SolidCache table sizes. Each row reports size, record counts, and a status indicator.
+
+<p align="center">
+  <a href=".github/assets/dash_8.png"><img src=".github/assets/dash_8.png" alt="Component health — Queue Observer + Cache Observer + SolidCache" width="700"></a>
+</p>
+
+For adapter notes and multi-adapter setup, see [Database Setup](#database-setup-persistence-mode) below.
+
 ## Configuration
 
+<details>
+<summary>Show full configuration reference</summary>
+
 After installation, configure SolidObserver in `config/initializers/solid_observer.rb`:
 
 ```ruby
@@ -168,6 +297,9 @@ SolidObserver.configure do |config|
   # Enable queue monitoring (default: true)
   config.observe_queue = true
 
+  # Enable cache monitoring (default: false; requires SolidCache in host app)
+  config.observe_cache = true
+
   # Data Retention (persistence mode only)
   config.event_retention = 30.days    # Keep events for 30 days
   config.metrics_retention = 90.days  # Keep metrics for 90 days
@@ -185,8 +317,6 @@ end
 
 ### APM Integration
 
-Connect SolidObserver with your Application Performance Monitoring tool for distributed tracing:
-
 ```ruby
 SolidObserver.configure do |config|
   # Datadog APM
@@ -213,6 +343,26 @@ end
 
 When configured, all job events will include your correlation ID, allowing you to trace jobs back to the originating request.
 
+### Production hardening (recommended)
+
+```ruby
+# Option A: fail at boot if the password env var is missing
+SolidObserver.configure do |config|
+  config.ui_username = "admin"
+  config.ui_password = ENV.fetch("SOLID_OBSERVER_PASSWORD")  # raises KeyError if unset
+end
+
+# Option B: only enable auth when the env var is present (no auth otherwise)
+SolidObserver.configure do |config|
+  if (password = ENV["SOLID_OBSERVER_PASSWORD"]).present?
+    config.ui_username = "admin"
+    config.ui_password = password
+  end
+end
+```
+
+</details>
+
 ## CLI Reference
 
 **Available in both modes (real-time and persistence):**
@@ -234,8 +384,10 @@ When configured, all job events will include your correlation ID, allowing you t
 | `solid_observer:buffer:clear` | Clear buffer without saving |
 | `solid_observer:storage:cleanup` | Run retention-based cleanup |
 | `solid_observer:storage:purge` | Delete ALL SolidObserver data |
+| `solid_observer:cache:clear` | Clear all SolidCache entries (with confirmation) |
+| `solid_observer:cache:prune` | Prune expired SolidCache entries |
 
-> **Note:** Storage commands manage **SolidObserver's storage** (event logs, metrics, snapshots) — not Solid Queue's jobs. To manage jobs, use `jobs:discard` or `jobs:retry`.
+> **Note:** Storage commands manage **SolidObserver's storage** (event logs, metrics, snapshots) — not Solid Queue's jobs. Cache commands operate on SolidCache entries in the host app's cache store.
 
 ### Jobs List Arguments
 
@@ -249,62 +401,82 @@ Arguments are positional: `[status, queue, job_class, limit]`
 | 4th | Max results (default: 20) | `50` |
 
 ```bash
-# Examples
 bin/rails solid_observer:jobs:list                           # All ready jobs
 bin/rails "solid_observer:jobs:list[failed]"                 # Failed jobs
 bin/rails "solid_observer:jobs:list[ready,mailers]"          # Ready jobs in mailers queue
 bin/rails "solid_observer:jobs:list[failed,,,50]"            # 50 failed jobs (skip queue/class)
 ```
 
-### Buffer & Storage Management (Persistence Mode)
+## Database Setup (Persistence Mode)
 
-```bash
-# Flush in-memory buffer to database
-bin/rails solid_observer:buffer:flush
+> **Tip:** If you're using real-time mode (`storage_mode: :realtime`), you can skip this section entirely — no database setup is needed.
 
-# Clear buffer without saving (loses pending events!)
-bin/rails solid_observer:buffer:clear
+**SolidObserver works with any main application database** — PostgreSQL, MySQL, or SQLite.
 
-# Run cleanup based on retention policy (default: 30 days)
-bin/rails solid_observer:storage:cleanup
+For its own monitoring data, the install generator defaults to a **separate SQLite database** — file-based, no extra infrastructure needed.
 
-# Delete ALL SolidObserver data (events + snapshots, interactive confirmation)
-bin/rails solid_observer:storage:purge
-```
+<details>
+<summary>Show multi-adapter setup and configuration details</summary>
 
-> **Important:** `storage:purge` deletes SolidObserver's monitoring data, NOT your Solid Queue jobs. Your queued jobs remain safe.
+The example below is what `rails generate solid_observer:install` produces:
 
-## Database Setup (Persistence Mode)
+```yaml
+# config/database.yml (generator default)
+solid_observer_queue:
+  <<: *default
+  adapter: sqlite3
+  database: storage/<%= Rails.env %>_solid_observer_queue.sqlite3
+```
 
-> **Tip:** If you're using real-time mode (`storage_mode: :realtime`), you can skip this section entirely — no database setup is needed.
+> **Note:** SQLite is the generator default, not a requirement. The `solid_observer_queue` database can use any Rails-supported adapter for record persistence. Adapter-native **storage-size monitoring** is currently implemented for SQLite, PostgreSQL/PostGIS, MySQL, and Trilogy. On other adapters, the size query returns `nil` and the engine logs a single `[SolidObserver] Unknown adapter for DatabaseSize: …` warning — record persistence still works.
 
-**SolidObserver works with any main application database** — PostgreSQL, MySQL, or SQLite.
+### Multi-adapter setup
 
-For its own monitoring data, SolidObserver uses a **separate SQLite database**. This keeps monitoring isolated from your main app and provides simple file-based storage that requires no additional infrastructure.
+If your host application uses PostgreSQL and you want SolidObserver to use SQLite, keep the `solid_observer_queue` block **self-contained** — do not rely on `<<: *default`. The generator default uses `<<: *default` with an explicit `adapter: sqlite3` override; that is safe on SQLite-primary hosts. On a PostgreSQL host, merging `<<: *default` without an explicit adapter override pulls the PG adapter in and fails at `db:create`. For multi-adapter connections, omit the merge entirely:
 
 ```yaml
 # config/database.yml
-solid_observer_queue:
-  <<: *default
-  adapter: sqlite3  # Always SQLite for SolidObserver storage
-  database: storage/<%= Rails.env %>_solid_observer_queue.sqlite3
+default: &default
+  adapter: postgresql
+  encoding: unicode
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+
+development:
+  primary:
+    <<: *default
+    database: my_app_development
+
+  solid_observer_queue:
+    adapter: sqlite3            # explicit override — do NOT merge *default
+    pool: 5
+    timeout: 5000
+    database: storage/development_solid_observer_queue.sqlite3
+    migrations_paths: db/solid_observer_migrate
 ```
 
-> **Note:** Your main app's `primary` database can be PostgreSQL, MySQL, or any Rails-supported adapter. Only the `solid_observer_queue` database needs to be SQLite.
+Apply the same pattern to `test:` and `production:`. For production with SQLite, ensure the `storage/` path is on persistent disk.
 
-## Roadmap
+**Bundler note (PG-only hosts):** if your `Gemfile` does not already include `sqlite3`, add it:
 
-SolidObserver is actively developed. Here's what's coming:
+```ruby
+gem "sqlite3", "~> 2.0"
+```
+
+**`migrations_paths` is recommended** to isolate SolidObserver's migrations from the host's primary `db/migrate/` folder. When `migrations_paths` is set on `solid_observer_queue`, `bin/rails solid_observer:install:migrations` copies migrations to that path automatically.
+
+</details>
+
+## Roadmap
 
 | Version | Focus | Status |
 |---------|-------|--------|
 | v0.1.0 | Solid Queue monitoring, CLI tools | ✅ Released |
-| v0.1.1 | Real-time mode (no migrations needed) | ✅ Current |
-| v0.2.0 | Web UI dashboard (vanilla HTML/CSS) | 🔜 Planned |
-| v0.3.0 | Solid Cache monitoring | 🔜 Planned |
-| v0.4.0 | Solid Cable monitoring | 🔜 Planned |
-| v0.5.0 | Cross-component correlation, health scores | 🔜 Planned |
-| v0.6.0 | Alerting & notifications | 🔜 Planned |
+| v0.1.1 | Real-time mode (no migrations needed) | ✅ Released |
+| v0.3.0 | Web UI dashboard + stability hardening | ✅ Released |
+| v0.4.0 | Solid Cache monitoring | ✅ Current |
+| v0.5.0 | Solid Cable monitoring | 🔜 Planned |
+| v0.6.0 | Cross-component correlation, health scores | 🔜 Planned |
+| v0.7.0 | Alerting & notifications | 🔜 Planned |
 | v1.0.0 | Production stable release | 🎯 Goal |
 
 See [GitHub Milestones](https://github.com/bart-oz/solid_observer/milestones) for detailed plans.
@@ -331,6 +503,19 @@ bundle exec reek
 
 ## Troubleshooting
 
+### Docker, CI, and Offline Boot
+
+SolidObserver is designed to boot without a live database connection. During
+`rails assets:precompile`, CI runs without a database service, or Kubernetes init
+containers, the engine logs a single info message and skips subscriber activation:
+
+```text
+[SolidObserver] Database not reachable at boot. Skipping subscriber activation.
+```
+
+No monkey-patching or environment-variable workarounds are needed. Once the application
+boots with a live database, the engine activates normally on the next restart.
+
 ### "no such table: solid_queue_ready_executions"
 
 This error means Solid Queue isn't configured to use the correct database in your environment.
@@ -347,22 +532,19 @@ config.solid_queue.connects_to = { database: { writing: :queue } }
 
 ### Multi-database setup
 
-SolidObserver works with Rails multi-database configurations. Here's an example with PostgreSQL as your primary database:
+> **See also:** [Multi-adapter setup](#multi-adapter-setup) in the Database Setup section for the full pattern.
+
+SolidObserver works with Rails multi-database configurations. Quick-reference example with PostgreSQL as your primary database and SQLite for SolidObserver's storage:
 
 ```yaml
 development:
   primary:
     adapter: postgresql
     database: myapp_development
-    # ... PostgreSQL settings
-  queue:
-    <<: *default
-    adapter: sqlite3
-    database: storage/development_queue.sqlite3
-    migrations_paths: db/queue_migrate
   solid_observer_queue:
     adapter: sqlite3
     database: storage/development_solid_observer_queue.sqlite3
+    migrations_paths: db/solid_observer_migrate
 ```
 
 ## Contributing