SolidObserver is a production-grade observability solution for Rails 8's Solid Stack. v0.5.0 covers Solid Queue, Solid Cache, and Solid Cable with a unified Web UI dashboard, CLI tools, metrics collection, and distributed tracing support.

Additional: 🔗 APM distributed tracing · ⚡ buffered writes · 🛡️ Docker/CI/K8s safe boot

• Ruby 3.2+
• Rails 8.0+
• Solid Queue (configured with connects_to in all environments)
• Solid Cache (optional — enable with config.observe_cache = true)
• Solid Cable (optional — enable with config.observe_cable = true)

Note: Ensure Solid Queue is configured with connects_to in all environments, not just production. See Troubleshooting if you encounter database connection issues.

Add to your Gemfile:

gem "solid_observer"

bundle install
rails generate solid_observer:install

SolidObserver supports two operating modes. Choose the one that fits your needs:

Get queue monitoring and job management instantly — no database setup required. SolidObserver queries Solid Queue directly.

# 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.

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 below.

⚠️ PostgreSQL / MySQL hosts: The generator writes a self-contained solid_observer_queue block with adapter: sqlite3. Review config/database.yml before running db:create — do not merge <<: *default into the observer entry, as that pulls the host adapter in and db:create will fail. See Multi-adapter setup for the correct pattern.

bin/rails solid_observer:install:migrations
bin/rails db:create
bin/rails db:migrate

For SQLite-default apps, no further configuration is needed — persistence is the default storage_mode.

bin/rails solid_observer:status

Output:

📊 SolidObserver Status
==================================================

🚀 Solid Queue

| Metric    | Value |
|-----------|-------|
| Ready     | 42    |
| Scheduled | 15    |
| Claimed   | 3     |
| Failed    | 2     |
| Workers   | 4     |

📋 Queue Depths

| Queue      | Jobs |
|------------|------|
| default    | 38   |
| mailers    | 12   |
| critical   | 10   |

# List jobs (defaults to ready jobs)
bin/rails solid_observer:jobs:list

# List failed jobs
bin/rails "solid_observer:jobs:list[failed]"

# Filter by status, queue, job class, and limit
bin/rails "solid_observer:jobs:list[failed,mailers]"
bin/rails "solid_observer:jobs:list[ready,default,UserNotificationJob,50]"

# Inspect a specific job
bin/rails "solid_observer:jobs:show[JOB_ID]"

# Retry a failed job
bin/rails "solid_observer:jobs:retry[JOB_ID]"

# Discard a failed job
bin/rails "solid_observer:jobs:discard[JOB_ID]"

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.

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.

bin/rails solid_observer:storage

Output:

💾 Storage Status

| Component | Size    | Events | Usage | Status |
|-----------|---------|--------|-------|--------|
| Queue     | 12.5 MB | 45,231 | 1.2%  | ✓      |

Configuration:
  Retention: 30 days
  Max size:  1024.0 MB per database
  Warning:   80% threshold

SolidObserver ships with a zero-dependency Web UI (no asset pipeline, no JS framework) at /solid_observer.

The install generator mounts it for you. To mount manually:

# config/routes.rb
mount SolidObserver::Engine, at: "/solid_observer"

Production dashboard exposure is the host application's responsibility. If you enable and mount the dashboard in production, wrap the mount in your existing admin authentication/authorization constraint (example shown for apps that already provide an authenticate route helper):

# config/routes.rb
authenticate :user, ->(user) { user.admin? } do
  mount SolidObserver::Engine, at: "/solid_observer"
end

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

For production hardening (fail-loud on missing env var vs. fail-open), see Configuration below.

• 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.
• HTTP Basic Auth requires both credentials. Setting only ui_username or only ui_password disables built-in auth; protect production mounts at the host-app route boundary.

See the full component breakdown in Components below.

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.

CLI commands (Solid Queue):

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

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.

Enabling Cache observability:

SolidCache must be configured in your host app (Rails 8 default). Then enable in the SolidObserver initializer:

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):

bin/rails solid_observer:cache:clear  # Clear all SolidCache entries (with confirmation)
bin/rails solid_observer:cache:prune  # Prune expired SolidCache entries

Cable observability is optional. Enable with config.observe_cable = true. Requires SolidCable in the host app. SolidObserver does not add any SolidCable dependency.

Cable dashboard (/solid_observer/cable_dashboard) shows broadcast/rejection trends, a stability indicator (hybrid: event + backlog signals), and recent safe events. Storages page includes Cable telemetry rows. Guarded trim controls: UI button for ≤1,000 trimmable messages; solid_observer:cable:trim Rake task for larger backlogs. Broadcasting names are stored as SHA256 digests — raw names are never persisted.

Enabling Cable observability:

SolidObserver.configure do |config|
  config.observe_cable = true  # default: false
  # config.cable_sampling_rate = 0.1  # Sample 10% of broadcast events (default: 0.1)
  # config.cable_rejection_threshold = 0.05  # Rejection rate threshold for Degraded (default: 0.05)
  # config.cable_backlog_threshold = 0.10    # Backlog ratio threshold (default: 0.10)
  # config.cable_error_threshold = 0.0       # Error rate threshold (default: 0.0)
end

solid_cable_enabled? is true when both observe_cable = true and SolidCable is available in the host app.

CLI commands (Solid Cable):

bin/rails solid_observer:cable:trim  # Trim expired Cable messages (with confirmation)

Cable dashboard screenshots are not yet available — capture from a host app with SolidCable configured.

The Storage page aggregates per-component health rows: Queue Observer database, Cache Observer, SolidCache table sizes, and Cable telemetry. Each row reports size, record counts, and a status indicator.

For adapter notes and multi-adapter setup, see Database Setup below.

The dashboard is admin/developer-facing. When SolidObserver storage is not reachable, the current default 503 error page includes the raw exception class and message so maintainers can diagnose adapter, credential, migration, or database availability problems. Do not expose the dashboard to untrusted users.

After installation, configure SolidObserver in config/initializers/solid_observer.rb:

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

  # Enable cache monitoring (default: false; requires SolidCache in host app)
  config.observe_cache = true

  # Enable cable monitoring (default: false; requires SolidCable in host app)
  config.observe_cable = true
  config.cable_sampling_rate = 0.1          # Sample 10% of broadcast events
  config.cable_rejection_threshold = 0.05   # Rejection rate → Degraded stability
  config.cable_backlog_threshold = 0.10     # Backlog ratio threshold
  config.cable_error_threshold = 0.0        # Error rate threshold

  # 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 (persistence mode only)
  config.max_db_size = 1.gigabyte     # Maximum database size
  config.warning_threshold = 0.8      # Warn at 80% capacity

  # 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
end

SolidObserver.configure do |config|
  # Datadog APM
  config.correlation_id_generator = -> {
    Datadog::Tracing.active_trace&.id
  }

  # Sentry
  config.correlation_id_generator = -> {
    Sentry.get_current_scope&.transaction&.trace_id
  }

  # OpenTelemetry
  config.correlation_id_generator = -> {
    OpenTelemetry::Trace.current_span&.context&.trace_id
  }

  # Custom implementation
  config.correlation_id_generator = -> {
    Thread.current[:request_id] || SecureRandom.uuid
  }
end

When configured, all job events will include your correlation ID, allowing you to trace jobs back to the originating request.

# 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

Available in both modes (real-time and persistence):

Persistence mode only:

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.

Arguments are positional: [status, queue, job_class, limit]

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)

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, 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:

# config/database.yml (generator default)
solid_observer_queue:
  adapter: sqlite3
  pool: 5
  timeout: 5000
  database: storage/<%= Rails.env %>_solid_observer_queue.sqlite3
  migrations_paths: db/solid_observer_migrate

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.

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 produces a self-contained block with explicit adapter: sqlite3 and migrations_paths, which is safe on any host adapter. 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:

# config/database.yml
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

Apply the same pattern to test: and production:. For production with SQLite, ensure the storage/ path is on persistent disk.

Bundler note (PG-only hosts): if your Gemfile does not already include sqlite3, add it:

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.

See GitHub Milestones for detailed plans.

# Clone the repository
git clone https://github.com/bart-oz/solid_observer.git
cd solid_observer

# Install dependencies
bin/setup

# Run tests
bundle exec rspec

# Run linter
bundle exec standardrb

# Run code smell detector
bundle exec reek

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:

[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.

This error means Solid Queue isn't configured to use the correct database in your environment.

Solution: Ensure connects_to is configured for all environments, not just production:

# config/environments/development.rb
config.solid_queue.connects_to = { database: { writing: :queue } }

# config/environments/test.rb
config.solid_queue.connects_to = { database: { writing: :queue } }

See also: 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:

development:
  primary:
    adapter: postgresql
    database: myapp_development
  solid_observer_queue:
    adapter: sqlite3
    database: storage/development_solid_observer_queue.sqlite3
    migrations_paths: db/solid_observer_migrate

Bug reports and pull requests are welcome on GitHub.

Check out issues labeled:

• good first issue — Great for newcomers
• help wanted — We'd love your help

Please follow the code of conduct.

The gem is available as open source under the terms of the MIT License.