solid_observer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f33210e5da882874417d97b040e5c1ea8a30b4cf5f628645fa76405bd38379
-  data.tar.gz: ffa7843af6bdd14bc23762da2f42a245073bf4776ec6b2de1aece77852c41d9d
+  metadata.gz: a745bb3571f70b207e14f2e88f6162db6b2322a889d42f5ebd2a50e80c5b8014
+  data.tar.gz: d05f835df0503f04f88223c0879145a2dab13279cd5bfc59346545c0e8263f1c
 SHA512:
-  metadata.gz: 3b8ca565611c5a343b55131fa63d84ff5ad8c47a954b9103914764d90a1d381b6dcd39923c71b9c467011c2f6f0bc17cb724a8b8a60e16eef32110142088b007
-  data.tar.gz: 73e295dd624824b396bcd0ccca2c4d740f3f27287ce226b7816a92569193b996527e6cd5c8e0967c67a18b1b9c19fe100163ee49d5a5d3ebcb6e5b18624fa9bd
+  metadata.gz: 8417c8013a7c9ff03a9d52481af63889adaba093abf0c9b041842664af7fb15edde929f7c7b94c6df12cbac00ca41d2aeee0f488fd7ffe831abf9d5f873bff09
+  data.tar.gz: 92147e32675291ec743e055c55382bf719a9ab6dd10e2e507789d0163b703e06490ad97dbb785e0a9c0b51b8eb72eb7a849d95504ac52c8680e53a137b50e4e4

data/CHANGELOG.md

@@ -1,3 +1,76 @@
+## [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
+- **Real-time mode** (`storage_mode: :realtime`) — run SolidObserver without database migrations
+  - Queue status and job management CLI commands work without any SolidObserver database
+  - `storage_mode` configuration option (`:persistence` default, `:realtime` for no-DB operation)
+  - `persistence_mode?` and `realtime_mode?` configuration predicates
+  - Graceful `CLI::Storage` message when in real-time mode
+  - Event buffering, metric incrementing, and cleanup automatically disabled in real-time mode
+
 ## [0.1.0] - 2026-02-02
 
 ### Added

data/README.md

@@ -2,33 +2,34 @@
   <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.0-blue.svg" alt="Version"></a>
+  <a href="https://github.com/bart-oz/solid_observer/releases"><img src="https://img.shields.io/badge/version-0.3.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.23%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.98%25-brightgreen.svg" alt="Coverage"></a>
 </p>
 
 ---
+<p align="center">
+  <img src=".github/assets/dash_1.png" alt="Dashboard overview" width="700">
+</p>
 
-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.
+SolidObserver is a production-grade observability solution for Rails 8's Solid Stack. Starting with **Solid Queue** monitoring in v0.3.0, it provides unified visibility into your background job processing with a Web UI dashboard, CLI tools, metrics collection, and distributed tracing support.
 
-## Features (v0.1.0)
+## Features (v0.3.0)
 
+- 🖥️ **Web UI Dashboard** — Live queue stats, job browser, event log, and storage info
 - 📊 **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
+- 🛡️ **Production Ready** — Docker/CI/K8s safe boot, automatic cleanup, size limits, retention policies
+- 🚀 **Two Operating Modes** — Real-time (no migrations) or persistence (full event history)
 
 ## Requirements
 
@@ -46,14 +47,31 @@ Add to your Gemfile:
 gem "solid_observer"
 ```
 
-Run the installer:
-
 ```bash
 bundle install
 rails generate solid_observer:install
 ```
 
-Install and run migrations:
+SolidObserver supports two operating modes. Choose the one that fits your needs:
+
+### Real-time Mode (no migrations needed)
+
+Get queue monitoring and job management instantly — no database setup required. SolidObserver queries Solid Queue directly.
+
+```ruby
+# config/initializers/solid_observer.rb
+SolidObserver.configure do |config|
+  config.storage_mode = :realtime
+end
+```
+
+That's it. You now have access to queue status, job listing, retry, and discard commands.
+
+### Persistence Mode (default)
+
+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
@@ -61,6 +79,8 @@ bin/rails db:create
 bin/rails db:migrate
 ```
 
+For SQLite-default apps, no further configuration is needed — persistence is the default `storage_mode`.
+
 ## Quick Start
 
 ### Check Queue Status
@@ -116,7 +136,16 @@ bin/rails "solid_observer:jobs:retry[JOB_ID]"
 bin/rails "solid_observer:jobs:discard[JOB_ID]"
 ```
 
-### Check Storage
+### 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
@@ -136,24 +165,99 @@ Configuration:
   Warning:   80% threshold
 ```
 
+## Web UI Dashboard
+
+SolidObserver ships with a zero-dependency Web UI (no asset pipeline, no JS framework) at `/solid_observer`.
+
+<table>
+  <tr>
+    <td align="center"><a href=".github/assets/dash_1.png"><img src=".github/assets/dash_1.png" alt="Dashboard overview" width="250"></a></td>
+    <td align="center"><a href=".github/assets/dash_2.png"><img src=".github/assets/dash_2.png" alt="Dashboard jobs and events" width="250"></a></td>
+    <td align="center"><a href=".github/assets/dash_3.png"><img src=".github/assets/dash_3.png" alt="Dashboard storage and details" width="250"></a></td>
+  </tr>
+</table>
+
+### Mount
+
+The install generator mounts it for you. To mount manually:
+
+```ruby
+# config/routes.rb
+mount SolidObserver::Engine, at: "/solid_observer"
+```
+
+### 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 credentials. Auth is enabled only when **both** are set; if either is missing or `nil`, the UI is unauthenticated |
+| `ui_base_controller` | `"ApplicationController"` | Name of your host app's base controller. SolidObserver does **not** inherit from it; the value is used to detect API-only apps so the engine can include the rendering modules its dashboard needs |
+
+Live polling cadence is hardcoded at 5s.
+
+### Production hardening (recommended)
+
+The snippet above silently disables auth if `ENV["SOLID_OBSERVER_PASSWORD"]` is unset (fail-open with a boot warning — see Caveats). For production, prefer one of these patterns so a missing env var fails loudly at boot rather than shipping an unauthenticated UI:
+
+```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
+```
+
+Option A is best when the UI must always be authenticated in production (a missing env var crashes boot — you find out immediately). Option B is best when the UI is optional in some environments.
+
+### Caveats
+
+- **Realtime mode** (`storage_mode: :realtime`) — Events and Storage navigation links are hidden. Direct visits to `/solid_observer/events` or `/solid_observer/storage` redirect to the dashboard with a flash alert (`This page is not available in real-time mode`).
+- **API-only apps** — the Web UI works in API-only Rails apps without manual configuration. SolidObserver's engine ships its own Cookies/Session/Flash middleware stack scoped to `/solid_observer/*` requests, so the dashboard renders, flash messages display, and retry/discard CSRF forms work even when the host app has `config.api_only = true`. The host app's middleware stack is not modified.
+- **Custom API base controller** — if your host app's API base controller is **not** named `ApplicationController`, set `config.ui_base_controller` to its name (e.g. `"Api::BaseController"`). The engine uses this only to detect `ActionController::API` ancestry; if detected, it includes `ActionView::Layouts`, `ActionView::Rendering`, and `ActionController::RequestForgeryProtection` so layouts and CSRF forms render.
+- **Host-app callbacks are not inherited.** SolidObserver does not run your host app's `before_action`s or authentication. Use `ui_username` / `ui_password` for the engine's built-in HTTP Basic Auth.
+- **Auth misconfiguration is fail-open, but loud.** If you set `ui_username` but `ui_password` resolves to `nil` (e.g. an unset ENV var), the UI ships unauthenticated rather than locking everyone out — and the engine logs a `WARNING` at boot naming the missing credential. Verify both are set in production.
+
 ## Configuration
 
 After installation, configure SolidObserver in `config/initializers/solid_observer.rb`:
 
 ```ruby
 SolidObserver.configure do |config|
+  # Storage Mode (:persistence or :realtime)
+  # :persistence — stores events, metrics, snapshots (requires migrations)
+  # :realtime    — live monitoring only, no database needed
+  config.storage_mode = :persistence  # default
+
   # Enable queue monitoring (default: true)
   config.observe_queue = true
 
-  # Data Retention
+  # 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
 
-  # Database Limits
+  # Database Limits (persistence mode only)
   config.max_db_size = 1.gigabyte     # Maximum database size
   config.warning_threshold = 0.8      # Warn at 80% capacity
 
-  # Performance Tuning
+  # Performance Tuning (persistence mode only)
   config.buffer_size = 1000           # Buffer before flushing to DB
   config.flush_interval = 10.seconds  # Flush interval
   config.sampling_rate = 1.0          # 1.0 = capture all events
@@ -192,6 +296,8 @@ When configured, all job events will include your correlation ID, allowing you t
 
 ## CLI Reference
 
+**Available in both modes (real-time and persistence):**
+
 | Command | Description |
 |---------|-------------|
 | `solid_observer:status` | Show queue status overview |
@@ -199,13 +305,18 @@ When configured, all job events will include your correlation ID, allowing you t
 | `solid_observer:jobs:show[ID]` | Show job details |
 | `solid_observer:jobs:retry[ID]` | Retry a failed job |
 | `solid_observer:jobs:discard[ID]` | Discard a failed job |
+
+**Persistence mode only:**
+
+| Command | Description |
+|---------|-------------|
 | `solid_observer:storage` | Show storage statistics |
 | `solid_observer:buffer:flush` | Force flush event buffer to database |
 | `solid_observer:buffer:clear` | Clear buffer without saving |
 | `solid_observer:storage:cleanup` | Run retention-based cleanup |
 | `solid_observer:storage:purge` | Delete ALL SolidObserver data |
 
-> **Note:** These 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. To manage jobs, use `jobs:discard` or `jobs:retry`.
 
 ### Jobs List Arguments
 
@@ -226,7 +337,7 @@ bin/rails "solid_observer:jobs:list[ready,mailers]"          # Ready jobs in mai
 bin/rails "solid_observer:jobs:list[failed,,,50]"            # 50 failed jobs (skip queue/class)
 ```
 
-### Buffer & Storage Management
+### Buffer & Storage Management (Persistence Mode)
 
 ```bash
 # Flush in-memory buffer to database
@@ -244,21 +355,60 @@ bin/rails solid_observer:storage:purge
 
 > **Important:** `storage:purge` deletes SolidObserver's monitoring data, NOT your Solid Queue jobs. Your queued jobs remain safe.
 
-## Database Setup
+## Database Setup (Persistence Mode)
+
+> **Tip:** If you're using real-time mode (`storage_mode: :realtime`), you can skip this section entirely — no database setup is needed.
 
 **SolidObserver works with any main application database** — PostgreSQL, MySQL, or SQLite.
 
-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.
+For its own monitoring data, the install generator defaults to a **separate SQLite database** — file-based, no extra infrastructure needed. The example below is what `rails generate solid_observer:install` produces:
 
 ```yaml
-# config/database.yml
+# config/database.yml (generator default)
 solid_observer_queue:
   <<: *default
-  adapter: sqlite3  # Always SQLite for SolidObserver storage
+  adapter: sqlite3
   database: storage/<%= Rails.env %>_solid_observer_queue.sqlite3
 ```
 
-> **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.
+> **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, but the size column on the dashboard will be empty until adapter support is added.
+
+### Multi-adapter setup
+
+If your host application uses one database adapter (e.g. PostgreSQL) and you want SolidObserver to use a different adapter (e.g. SQLite — for isolation, simpler ops, or to avoid loading observability traffic onto your primary DB), keep the `solid_observer_queue` block **self-contained** — do not rely on `<<: *default`. The generator default (shown above) uses `<<: *default` with an explicit `adapter: sqlite3` override; that is safe on SQLite-primary hosts where the anchor is also SQLite. On a PostgreSQL host, merging `<<: *default` without an explicit adapter override pulls the PG adapter into the observer connection and fails at `db:create` with `PG::SyntaxError` (PG treating a SQLite file path as a database name). For multi-adapter connections, omit the merge entirely, as shown below.
+
+```yaml
+# config/database.yml
+default: &default
+  adapter: postgresql           # host's adapter
+  encoding: unicode
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+
+development:
+  primary:
+    <<: *default
+    database: my_app_development
+  # ... cache / queue / cable on PG ...
+
+  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
+```
+
+Apply the same pattern to `test:` and `production:`. For production with SQLite, ensure the `storage/` path is on persistent disk (not ephemeral container storage) — otherwise prefer PostgreSQL for the observer DB too.
+
+**Bundler note (PG-only hosts):** if your `Gemfile` does not already include `sqlite3`, add it:
+
+```ruby
+gem "sqlite3", "~> 2.0"
+```
+
+then `bundle install`. SolidObserver does not declare `sqlite3` as a runtime dependency — adapter choice is yours.
+
+**`migrations_paths` is recommended** to isolate SolidObserver's migrations from the host's primary `db/migrate/` folder. This prevents Rails from running SolidObserver's migrations against your primary database (which would create an unused `solid_observer_queue_events` table there). When `migrations_paths` is set on `solid_observer_queue`, `bin/rails solid_observer:install:migrations` copies migrations to that path automatically — no manual `mv` required.
 
 ## Roadmap
 
@@ -266,12 +416,13 @@ SolidObserver is actively developed. Here's what's coming:
 
 | Version | Focus | Status |
 |---------|-------|--------|
-| v0.1.0 | Solid Queue monitoring, CLI tools | ✅ Current |
-| v0.2.0 | Solid Cache monitoring | 🔜 Planned |
-| v0.3.0 | Solid Cable monitoring | 🔜 Planned |
-| v0.4.0 | Cross-component correlation, health scores | 🔜 Planned |
-| v0.5.0 | Alerting & notifications | 🔜 Planned |
-| v0.6.0 | Web UI dashboard | 🔜 Planned |
+| v0.1.0 | Solid Queue monitoring, CLI tools | ✅ Released |
+| v0.1.1 | Real-time mode (no migrations needed) | ✅ Released |
+| v0.3.0 | Web UI dashboard + stability hardening | ✅ Current |
+| v0.4.0 | Solid Cache monitoring | 🔜 Planned |
+| 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.
@@ -298,6 +449,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.
@@ -314,7 +478,9 @@ 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 (explicit `adapter:` override, `gem "sqlite3"` Bundler note, `migrations_paths` rationale).
+
+SolidObserver works with Rails multi-database configurations. Quick-reference example with PostgreSQL as your primary database and SQLite for SolidObserver's storage:
 
 ```yaml
 development:
@@ -322,14 +488,10 @@ development:
     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