solid_observer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f33210e5da882874417d97b040e5c1ea8a30b4cf5f628645fa76405bd38379
-  data.tar.gz: ffa7843af6bdd14bc23762da2f42a245073bf4776ec6b2de1aece77852c41d9d
+  metadata.gz: c2e83e38f795537bcacb9a431fe39543476b615cb205904fd5af324a4a1886e8
+  data.tar.gz: cf501ff1b33535eb7a2b4f4858289bea3c93af7371af83bb867255b3f00de462
 SHA512:
-  metadata.gz: 3b8ca565611c5a343b55131fa63d84ff5ad8c47a954b9103914764d90a1d381b6dcd39923c71b9c467011c2f6f0bc17cb724a8b8a60e16eef32110142088b007
-  data.tar.gz: 73e295dd624824b396bcd0ccca2c4d740f3f27287ce226b7816a92569193b996527e6cd5c8e0967c67a18b1b9c19fe100163ee49d5a5d3ebcb6e5b18624fa9bd
+  metadata.gz: 58fb350eda47268f65f13b71ac4f317fe7a9cd6274a05c636a4d7a91477ad5a6269a652a7bb537255cbce8e690231c6bd33507530baf6fb626e672b738bf175b
+  data.tar.gz: 9042759cdeca68bf9fd50a0c62493c6e9d057915b714cb8d68ef81f36028e6437c8f85dfeab8bac971419bc8471b147840051aa881a01871f720640f4abdfdb9

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [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

@@ -11,17 +11,17 @@
 </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.1.1-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-93.06%25-brightgreen.svg" alt="Coverage"></a>
 </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.
 
-## Features (v0.1.0)
+## Features (v0.1.1)
 
 - 📊 **Real-time Queue Status** — Monitor jobs across all states (ready, scheduled, claimed, failed)
 - 🔍 **Job Management CLI** — List, inspect, retry, and discard failed jobs
@@ -29,6 +29,7 @@ SolidObserver is a production-grade observability solution for Rails 8's Solid S
 - 🔗 **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)
 
 ## Requirements
 
@@ -46,14 +47,29 @@ 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 SQLite database. This gives you everything in real-time mode plus long-term event tracking, buffered writes, and retention-based cleanup.
 
 ```bash
 bin/rails solid_observer:install:migrations
@@ -61,6 +77,8 @@ bin/rails db:create
 bin/rails db:migrate
 ```
 
+No additional configuration needed — persistence is the default `storage_mode`.
+
 ## Quick Start
 
 ### Check Queue Status
@@ -116,7 +134,7 @@ bin/rails "solid_observer:jobs:retry[JOB_ID]"
 bin/rails "solid_observer:jobs:discard[JOB_ID]"
 ```
 
-### Check Storage
+### Check Storage (Persistence Mode)
 
 ```bash
 bin/rails solid_observer:storage
@@ -142,18 +160,23 @@ After installation, configure SolidObserver in `config/initializers/solid_observ
 
 ```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 +215,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 +224,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 +256,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,7 +274,9 @@ 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.
 
@@ -266,12 +298,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) | ✅ 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 |
 | v1.0.0 | Production stable release | 🎯 Goal |
 
 See [GitHub Milestones](https://github.com/bart-oz/solid_observer/milestones) for detailed plans.

data/lib/solid_observer/cli/storage.rb

@@ -4,6 +4,14 @@ module SolidObserver
   module CLI
     class Storage < Base
       def call
+        if SolidObserver.config.realtime_mode?
+          print_section_header("💾 Storage Status")
+          info("Storage monitoring is not available in real-time mode.")
+          info("Switch to persistence mode for event history and storage tracking.")
+          output("")
+          return
+        end
+
         print_section_header("💾 Storage Status")
 
         current_stats = gather_storage_stats

data/lib/solid_observer/configuration.rb

@@ -38,6 +38,9 @@ module SolidObserver
     # Storage Settings
     attr_accessor :max_db_size
 
+    # Storage Mode
+    attr_reader :storage_mode
+
     # Performance Settings (with validation)
     attr_reader :sampling_rate,
       :warning_threshold,
@@ -55,6 +58,9 @@ module SolidObserver
       @http_basic_auth_user = nil
       @http_basic_auth_password = nil
 
+      # Storage mode
+      @storage_mode = :persistence
+
       # Observer defaults
       @observe_queue = true
       @observe_cache = false
@@ -78,6 +84,23 @@ module SolidObserver
       @correlation_id_generator = nil
     end
 
+    STORAGE_MODES = %i[persistence realtime].freeze
+
+    def storage_mode=(value)
+      value = value.to_sym
+      raise ArgumentError, "storage_mode must be :persistence or :realtime" unless STORAGE_MODES.include?(value)
+
+      @storage_mode = value
+    end
+
+    def persistence_mode?
+      @storage_mode == :persistence
+    end
+
+    def realtime_mode?
+      @storage_mode == :realtime
+    end
+
     def sampling_rate=(value)
       validate_rate!(:sampling_rate, value)
       @sampling_rate = value

data/lib/solid_observer/engine.rb

@@ -12,6 +12,8 @@ module SolidObserver
       end
 
       def configure_database_connection
+        return if SolidObserver.config.realtime_mode?
+
         db_config = ActiveRecord::Base.configurations.configs_for(
           env_name: Rails.env,
           name: "solid_observer_queue"
@@ -30,12 +32,15 @@ module SolidObserver
       def activate_subscribers
         logger = Rails.logger
 
-        unless table_exists?("solid_observer_queue_events")
+        if SolidObserver.config.realtime_mode?
+          logger.info "[SolidObserver] Starting in real-time mode (no persistence)"
+        elsif !table_exists?("solid_observer_queue_events")
           logger.info "[SolidObserver] Tables not found. Run: rails solid_observer:install:migrations && rails db:migrate"
           return
+        else
+          logger.info "[SolidObserver] Activating event subscribers"
         end
 
-        logger.info "[SolidObserver] Activating event subscribers"
         Subscriber.subscribe!
       rescue ActiveRecord::NoDatabaseError
         logger.info "[SolidObserver] Database not ready yet. Skipping subscriber activation."

data/lib/solid_observer/queue_event_buffer.rb

@@ -25,12 +25,15 @@ module SolidObserver
     # @param event_data [Hash] Event data to buffer
     # @return [void]
     def push(event_data)
+      config = SolidObserver.config
+      return unless config.persistence_mode?
+
       should_flush = false
 
       @mutex.synchronize do
         @buffer << event_data
         schedule_flush unless @flush_scheduled
-        should_flush = @buffer.size >= SolidObserver.config.buffer_size
+        should_flush = @buffer.size >= config.buffer_size
       end
 
       flush! if should_flush

data/lib/solid_observer/services/cleanup_storage.rb

@@ -8,6 +8,8 @@ module SolidObserver
       end
 
       def call
+        return 0 if SolidObserver.config.realtime_mode?
+
         deleted_count = 0
 
         QueueEvent.transaction do

data/lib/solid_observer/services/record_event.rb

@@ -81,6 +81,8 @@ module SolidObserver
       end
 
       def increment_metric
+        return unless SolidObserver.config.persistence_mode?
+
         period = Time.current.beginning_of_hour
         QueueMetric.increment(metric: @metric_name, period: period)
       rescue => e

data/lib/solid_observer/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SolidObserver
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
   RUBY_MINIMUM_VERSION = "3.2.0"
   RAILS_MINIMUM_VERSION = "8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_observer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - BartOz