KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #claude-code #ai-agent #codex #ai-agents #deepseek-harness #agent-skills #macos #cli

solid_queue_monitor

★ 95 Open GitHub ↗

A lightweight, zero-dependency web interface for monitoring Solid Queue jobs in Rails applications.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SolidQueueMonitor

[![Gem Version](https://badge.fury.io/rb/solid_queue_monitor.svg)](https://badge.fury.io/rb/solid_queue_monitor)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/vishaltps/solid_queue_monitor/main/LICENSE)

A lightweight, zero-dependency web interface for monitoring Solid Queue background jobs in Ruby on Rails applications. Perfect for Rails API-only applications and traditional Rails apps.

## Key Advantages

- **Works in API-only Rails Applications**: Unlike other monitoring gems that require a full Rails application with asset pipeline or webpacker, SolidQueueMonitor works seamlessly in API-only Rails applications.
- **No External Dependencies**: No JavaScript frameworks, no CSS libraries, no additional gems required - just pure Rails.
- **Self-contained UI**: All HTML, CSS, and JavaScript are generated server-side, making deployment simple and reliable.
- **Minimal Footprint**: Adds minimal overhead to your application while providing powerful monitoring capabilities.
- **Rails 7 Compatible**: Fully compatible with Rails 7.1+ and the latest Solid Queue versions.

## Features

- **Dashboard Overview**: Get a quick snapshot of your queue's health with statistics on all job types
- **Job Activity Chart**: Visual line chart showing jobs created, completed, and failed over time with 9 time range options (15m to 1 week)
- **Dark Theme**: Toggle between light and dark themes with system preference detection and localStorage persistence
- **Worker Monitoring**: Real-time view of all Solid Queue processes (workers, dispatchers, schedulers)
  - Health status indicators (healthy, stale, dead) based on heartbeat
  - Shows queues each worker is processing and jobs currently being executed
  - Prune dead processes with one click
- **Job Details Page**: Dedicated page for viewing complete job information
  - Full job timeline showing created, scheduled, started, and finished states
  - Timing breakdown with queue wait time and execution duration
  - Complete error details with backtrace for failed jobs
  - Job arguments displayed in formatted JSON
- **Queue Details Page**: Detailed view for individual queues with job counts and filtering
- **Ready Jobs**: View jobs that are ready to be executed
- **In Progress Jobs**: Monitor jobs currently being processed by workers
- **Scheduled Jobs**: See upcoming jobs scheduled for future execution with ability to execute immediately or reject permanently
- **Recurring Jobs**: Manage periodic jobs that run on a schedule
- **Failed Jobs**: Track and debug failed jobs, with the ability to retry or discard them
- **Queue Management**: View and filter jobs by queue with pause/resume controls
- **Pause/Resume Queues**: Temporarily stop processing jobs on specific queues for incident response
- **Global Search**: Search across all job types by class name, queue, arguments, job ID, and error messages
- **Sortable Columns**: Click column headers to sort job tables by any column with ascending/descending toggle
- **Advanced Job Filtering**: Filter jobs by class name, queue, status, and job arguments
- **Quick Actions**: Retry or discard failed jobs, execute or reject scheduled jobs directly from any view
- **Performance Optimized**: Designed for high-volume applications with smart pagination
- **Auto-refresh**: Real-time monitoring with configurable auto-refresh interval and toggle
- **Optional Authentication**: Secure your dashboard with HTTP Basic Authentication
- **Responsive Design**: Works on desktop and mobile devices
- **Zero Dependencies**: No additional JavaScript libraries or frameworks required

## Screenshots

### Dashboard Overview (Light Theme)

![Dashboard Overview - Light Theme](https://raw.githubusercontent.com/vishaltps/solid_queue_monitor/main/screenshots/dashboard-light.png)

### Dashboard Overview (Dark Theme)

![Dashboard Overview - Dark Theme](https://raw.githubusercontent.com/vishaltps/solid_queue_monitor/main/screenshots/dashboard-dark.png)

### Worker Monitoring

![Worker Monitoring](https://raw.githubusercontent.com/vishaltps/solid_queue_monitor/main/screenshots/workers.png)

### Queue Management

![Queue Management](https://raw.githubusercontent.com/vishaltps/solid_queue_monitor/main/screenshots/queues.png)

### Failed Jobs

![Failed Jobs](https://raw.githubusercontent.com/vishaltps/solid_queue_monitor/main/screenshots/failed-jobs.png)

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'solid_queue_monitor', '~> 2.0'
```

Then execute:

```bash
$ bundle install
```

After bundling, run the generator:

```bash
rails generate solid_queue_monitor:install
```

This will:

1. Create an initializer at `config/initializers/solid_queue_monitor.rb`
2. Add required routes to your `config/routes.rb`

## Configuration

You can configure Solid Queue Monitor by editing the initializer:

```ruby
# config/initializers/solid_queue_monitor.rb
SolidQueueMonitor.setup do |config|
  # Enable or disable authentication
  # By default, authentication is disabled for ease of setup
  config.authentication_enabled = false

# Set the username for HTTP Basic Authentication (only used if authentication is enabled)
  # Supports static values, ENV variables, or callables (Proc/Lambda)
  config.username = 'admin'

# Set the password for HTTP Basic Authentication (only used if authentication is enabled)
  # Supports static values, ENV variables, or callables (Proc/Lambda)
  config.password = 'password'

# Number of jobs to display per page
  config.jobs_per_page = 25

# Auto-refresh settings
  # Enable or disable auto-refresh globally (users can still toggle it in the UI)
  config.auto_refresh_enabled = true

# Auto-refresh interval in seconds (default: 30)
  config.auto_refresh_interval = 30

# Disable the chart on the overview page to skip chart queries entirely
  # config.show_chart = true

# Enable CSRF protection for the dashboard's destructive actions (opt-in)
  # config.csrf_protection_enabled = false
end

# Optional: inherit from a host-app controller to plug into your existing auth.
# See "Custom Authentication" below. Defaults to "ActionController::Base".
# SolidQueueMonitor.base_controller_class = 'AdminController'
```

### Performance at Scale

SolidQueueMonitor is optimized for large datasets (millions of rows in `solid_queue_jobs`). All dashboard queries are designed to stay fast regardless of table size.

If you don't need the job activity chart, disable it to skip chart queries entirely:

```ruby
config.show_chart = false
```

### CSRF Protection

The dashboard's destructive actions (retry, discard, pause, resume, execute, reject, remove/prune workers) are all `POST` requests. By default CSRF protection is **disabled**, because the gem does not assume the host application has a session store (it works in API-only apps without one).

If your host app has a session store and the dashboard is mounted on the same origin, you should enable CSRF protection:

```ruby
config.csrf_protection_enabled = true
```

When enabled:

- All dashboard forms embed an `authenticity_token`, and `csrf_meta_tags` are added to the layout for JS/`fetch`-driven requests.
- Unverified `POST` requests are rejected by Rails' standard `verify_authenticity_token` (returns `422 Unprocessable Entity`). Safe methods (`GET`/`HEAD`) pass through.

Requirements:

- The host app has a session store configured (e.g. `config.session_store :cookie_store`).
- `config.api_only` is not enabled (or session middleware is otherwise present).
- The dashboard is mounted on the same origin as the host app, so `form_authenticity_token` works.

### Authentication

By default, Solid Queue Monitor does not require authentication to access the dashboard. This makes it easy to get started in development environments.

For production environments, it's strongly recommended to enable authentication:

1. **Enable authentication**: Set `config.authentication_enabled = true` in the initializer
2. **Configure secure credentials** using any of these approaches:

```ruby
# Static values
config.username = 'admin'
config.password = 'secure_password'

# Environment variables
config.username = ENV['SOLID_QUEUE_MONITOR_USERNAME']
config.password = ENV['SOLID_QUEUE_MONITOR_PASSWORD']

# Rails credentials (use a lambda for deferred evaluation)
config.username = -> { Rails.application.credentials.dig(:solid_queue_monitor, :username) }
config.password = -> { Rails.application.credentials.dig(:solid_queue_monitor, :password) }
```

### Custom Authentication

By default, Solid Queue Monitor uses HTTP Basic auth with the username/password from `SolidQueueMonitor.setup`. To integrate with your app's existing auth (Devise, Pundit, OmniAuth, custom sessions, etc.), point the engine at a base controller from your host app:

```ruby
# config/initializers/solid_queue_monitor.rb
SolidQueueMonitor.setup do |config|
  config.authentication_enabled = false # disable HTTP Basic
end

# Inherit from your own controller so its before_actions, rescue_froms,
# layout, and current_user helper cascade into the engine.
SolidQueueMonitor.base_controller_class = 'AdminController'
```

**Minimal example — just authenticate:**

```ruby
class AdminController < ApplicationController
  before_action :authenticate_user!   # Devise (or your equivalent)
end
```

**Richer example — require an admin role:**

```ruby
class AdminController < ApplicationController
  before_action :authenticate_user!
  before_action :require_admin

private

def require_admin
    redirect_to root_path, alert: 'Not authorized' unless current_user&.admin?
  end
end
```

Leave `authentication_enabled = true` if you want HTTP Basic to run *on top of* your host auth (host runs first, HTTP Basic second). Most adopters disable it.

Restart your server after changing this config — the class hierarchy is set at load time, so config changes won't take effect on a live process.

## Usage

After installation, visit `/solid_queue` in your browser to access the dashboard.

The dashboard provides several views:

- **Overview**: Shows statistics, recent jobs, and job activity chart
- **Ready Jobs**: Jobs that are ready to be executed
- **Scheduled Jobs**: Jobs scheduled for future execution with execute and reject actions
- **Recurring Jobs**: Jobs that run on a recurring schedule
- **Failed Jobs**: Jobs that have failed with error details and retry/discard actions
- **Queues**: Distribution of jobs across different queues with pause/resume controls
- **Workers**: Real-time monitoring of all Solid Queue processes with health status

Click on any job class name to view detailed information including timeline, timing breakdown, arguments, and error details (for failed jobs).

### API-only Applications

For API-only Rails applications, SolidQueueMonitor works out of the box without requiring you to enable the asset pipeline or webpacker. This makes it an ideal choice for monitoring background jobs in modern API-based architectures.

### Job Filtering

You can filter jobs by:

- **Class Name**: Filter by job class name
- **Queue Name**: Filter by queue name
- **Job Arguments**: Search within job arguments using case-insensitive partial matching
- **Status**: Filter by job status (completed, failed, scheduled, pending)

This makes it easy to find specific jobs when debugging issues in your application.

## Use Cases

- **Production Monitoring**: Keep an eye on your background job processing in production environments
- **Worker Health Monitoring**: Track the health of your Solid Queue processes and identify dead workers
- **Debugging**: Quickly identify and troubleshoot failed jobs with detailed error information and backtraces
- **Job Management**: Execute scheduled jobs on demand or reject unwanted jobs permanently
- **Incident Response**: Pause queues during incidents to prevent job processing while investigating issues
- **Performance Analysis**: Track job distribution, timing metrics, and identify bottlenecks
- **DevOps Integration**: Easily integrate with your monitoring stack

## Compatibility

- **Ruby**: 3.1.6 or higher
- **Rails**: 7.1 or higher
- **Solid Queue**: 0.1.0 or higher

## Content Security Policy

Solid Queue Monitor is fully CSP-compatible as of v2.0.0. The dashboard works out of the box under strict policies — no nonce configuration is required.

### Strict CSP (v2.0.0+)

As of v2.0 the dashboard's CSS and JavaScript are served as external, content-hashed assets (e.g. `/solid_queue/assets/application-a1b2c3d4.css`) with `Cache-Control: immutable`. The dashboard emits zero inline `<style>` or `<script>` blocks. A strict policy that only allows `'self'` for both directives is sufficient:

```ruby
# config/initializers/content_security_policy.rb
Rails.application.config.content_security_policy do |policy|
  policy.script_src :self
  policy.style_src  :self
end
```

### Nonce-based CSP

Nonce-based CSP is also supported. When `content_security_policy_nonce_generator` is configured, Solid Queue Monitor stamps the per-request nonce onto the `<link rel="stylesheet">` and `<script src="...">` tags it emits — so policies that exclude `'self'` and only allow nonces still work:

```ruby
# config/initializers/content_security_policy.rb
Rails.application.config.content_security_policy do |policy|
  policy.script_src :self
  policy.style_src  :self
end

Rails.application.config.content_security_policy_nonce_generator = ->(req) { SecureRandom.base64(16) }
Rails.application.config.content_security_policy_nonce_directives = %w[script-src style-src]
```

### Upgrading from v1.x

v1.x emitted inline `<style nonce>` and `<script nonce>` blocks, so a nonce generator was effectively required for strict policies. v2.0 removes all inline blocks. If you added a nonce generator only to make the monitor work, you can keep it (no harm) or remove it.

## Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

### Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Code of Conduct

Everyone interacting in the SolidQueueMonitor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yourusername/solid_queue_monitor/blob/main/CODE_OF_CONDUCT.md).

## Related Projects

- [Solid Queue](https://github.com/rails/solid_queue) - The official Rails background job framework
- [Rails](https://github.com/rails/rails) - The web application framework
- [ActiveJob](https://github.com/rails/rails/tree/main/activejob) - Rails job framework

solid_queue_monitor

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README