Skip to content

Commit 3d1f68c

Browse files
committed
updated readme - added monitoring in table contents, recommended solid_queue_monitor gem for dashboard
1 parent 3a71660 commit 3d1f68c

File tree

1 file changed

+39
-3
lines changed

1 file changed

+39
-3
lines changed

README.md

+39-3
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@ Solid Queue can be used with SQL databases such as MySQL, PostgreSQL or SQLite,
2525
- [Concurrency controls](#concurrency-controls)
2626
- [Failed jobs and retries](#failed-jobs-and-retries)
2727
- [Error reporting on jobs](#error-reporting-on-jobs)
28+
- [Monitoring](#monitoring)
2829
- [Puma plugin](#puma-plugin)
2930
- [Jobs and transactional integrity](#jobs-and-transactional-integrity)
3031
- [Recurring tasks](#recurring-tasks)
3132
- [Inspiration](#inspiration)
3233
- [License](#license)
3334

34-
3535
## Installation
3636

3737
Solid Queue is configured by default in new Rails 8 applications. But if you're running an earlier version, you can add it manually following these steps:
@@ -114,6 +114,7 @@ plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"] || Rails.env.development?
114114
```
115115

116116
You can also just use `bin/jobs`, but in this case you might want to [set a different logger for Solid Queue](#other-configuration-settings) because the default logger will log to `log/development.log` and you won't see anything when you run `bin/jobs`. For example:
117+
117118
```ruby
118119
config.solid_queue.logger = ActiveSupport::Logger.new(STDOUT)
119120
```
@@ -204,7 +205,7 @@ production:
204205
- queues: "*"
205206
threads: 3
206207
polling_interval: 2
207-
- queues: [ real_time, background ]
208+
- queues: [real_time, background]
208209
threads: 5
209210
polling_interval: 0.1
210211
processes: 3
@@ -492,6 +493,8 @@ failed_execution.discard # This will delete the job from the system
492493

493494
However, we recommend taking a look at [mission_control-jobs](https://github.com/rails/mission_control-jobs), a dashboard where, among other things, you can examine and retry/discard failed jobs.
494495

496+
For applications that need a lightweight solution, especially Rails API-only applications, [solid_queue_monitor](https://github.com/vishaltps/solid_queue_monitor) is an excellent alternative. It provides a zero-dependency web interface for monitoring Solid Queue background jobs with all the essential features for managing jobs, including examining and retrying/discarding failed jobs. Its minimal footprint makes it perfect for API-only Rails applications where you want to avoid adding additional dependencies.
497+
495498
### Error reporting on jobs
496499

497500
Some error tracking services that integrate with Rails, such as Sentry or Rollbar, hook into [Active Job](https://guides.rubyonrails.org/active_job_basics.html#exceptions) and automatically report not handled errors that happen during job execution. However, if your error tracking system doesn't, or if you need some custom reporting, you can hook into Active Job yourself. A possible way of doing this would be:
@@ -519,22 +522,55 @@ class ApplicationMailer < ActionMailer::Base
519522
end
520523
```
521524

525+
## Monitoring
526+
527+
Solid Queue provides various ways to monitor your background jobs. You can use these tools to view job statistics, track job status, manage failed jobs, and more.
528+
529+
### Solid Queue Monitor
530+
531+
For applications that need a lightweight solution, especially Rails API-only applications, [solid_queue_monitor](https://github.com/vishaltps/solid_queue_monitor) is an excellent option. Key features include:
532+
533+
- Zero dependencies - works out of the box for Rails API applications
534+
- Dashboard overview of job queues
535+
- Job filtering by class, queue name, and status
536+
- Failed job inspection and management
537+
- Recurring job monitoring
538+
- Responsive design that works on mobile devices
539+
540+
Its minimal footprint makes it perfect for API-only Rails applications or projects where you want to avoid additional dependencies.
541+
542+
### Mission Control Jobs
543+
544+
[mission_control-jobs](https://github.com/rails/mission_control-jobs) is the officially supported dashboard for Solid Queue. It provides a comprehensive interface for monitoring and managing your background jobs with features like:
545+
546+
- Statistics and analytics for job processing
547+
- Job filtering and searching
548+
- Detailed error information for failed jobs
549+
- Ability to retry and discard failed jobs
550+
- Support for recurring jobs management
551+
552+
As a full-featured Rails engine, it comes with more dependencies but offers a rich user experience.
553+
522554
## Puma plugin
523555

524556
We provide a Puma plugin if you want to run the Solid Queue's supervisor together with Puma and have Puma monitor and manage it. You just need to add
557+
525558
```ruby
526559
plugin :solid_queue
527560
```
561+
528562
to your `puma.rb` configuration.
529563

530564
If you're using Puma in development but you don't want to use Solid Queue in development, make sure you avoid the plugin being used, for example using an environment variable like this:
565+
531566
```ruby
532567
plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]
533568
```
534-
that you set in production only. This is what Rails 8's default Puma config looks like. Otherwise, if you're using Puma in development but not Solid Queue, starting Puma would start also Solid Queue supervisor and it'll most likely fail because it won't be properly configured.
535569

570+
that you set in production only. This is what Rails 8's default Puma config looks like. Otherwise, if you're using Puma in development but not Solid Queue, starting Puma would start also Solid Queue supervisor and it'll most likely fail because it won't be properly configured.
536571

537572
## Jobs and transactional integrity
573+
538574
:warning: Having your jobs in the same ACID-compliant database as your application data enables a powerful yet sharp tool: taking advantage of transactional integrity to ensure some action in your app is not committed unless your job is also committed and vice versa, and ensuring that your job won't be enqueued until the transaction within which you're enqueuing it is committed. This can be very powerful and useful, but it can also backfire if you base some of your logic on this behaviour, and in the future, you move to another active job backend, or if you simply move Solid Queue to its own database, and suddenly the behaviour changes under you. Because this can be quite tricky and many people shouldn't need to worry about it, by default Solid Queue is configured in a different database as the main app.
539575

540576
Starting from Rails 8, an option which doesn't rely on this transactional integrity and which Active Job provides is to defer the enqueueing of a job inside an Active Record transaction until that transaction successfully commits. This option can be set via the [`enqueue_after_transaction_commit`](https://edgeapi.rubyonrails.org/classes/ActiveJob/Enqueuing.html#method-c-enqueue_after_transaction_commit) class method on the job level and is by default disabled. Either it can be enabled for individual jobs or for all jobs through `ApplicationJob`:

0 commit comments

Comments
 (0)