¶ ↑
resque-statusresque-status is an extension to the resque queue system that provides simple trackable jobs.
¶ ↑
Aboutresque-status provides a set of simple classes that extend resque’s default functionality (with 0% monkey patching) to give apps a way to track specific job instances and their status. It achieves this by giving job instances UUID’s and allowing the job instances to report their status from within their iterations.
¶ ↑
Installationresque-status *requires Redis >= 1.1* (though I recommend getting the latest stable version). You can download Redis here: code.google.com/p/redis/ or install it using homebrew (brew install redis).
Install the resque-status gem (which will pull in the dependencies).
gem install resque-status
To use with Rails, you can install as a plugin or add the gem to you’re config:
# environment.rb config.gem 'resque-status', :lib => 'resque/status'
Then in an initializer:
# config/initializers/resque.rb require 'resque/job_with_status' Resque.redis = "your/redis/socket" # default localhost:6379 Resque::Status.expire_in = (24 * 60 * 60) # 24hrs in seconds
¶ ↑
UsageThe most direct way to use resque-status is to create your jobs using the Resque::JobWithStatus class. An example job would look something like:
class SleepJob < Resque::JobWithStatus def perform total = options['length'].to_i || 1000 num = 0 while num < total at(num, total, "At #{num} of #{total}") sleep(1) num += 1 end completed end end
Instead of normal Resque job classes, we inherit from the JobWithStatus class. Another major difference is that intead of implementing perform
as a class method, we do our job implementation within instances of the job class.
In order to queue a SleepJob up, we also won’t use Resque.enqueue
, instead we’ll use the create
class method which will wrap enqueue
and creating a unique id (UUID) for us to track the job with.
job_id = SleepJob.create(:length => 100)
This will create a UUID enqueue the job and pass the :length option on the SleepJob instance as options (as you can see above).
Now that we have a UUID its really easy to get the status:
status = Resque::Status.get(job_id)
This returns a Resque::Status object, which is a Hash (with benefits).
status.pct_complete #=> 0 status.status #=> 'queued' status.queued? #=> true status.working? #=> false status.time #=> Time object status.message #=> "Created at ..."
Once the worker reserves the job, the instance of SleepJob updates the status at each iteration using at()
status = Resque::Status.get(job_id) status.working? #=> true status.num #=> 5 status.total => 100 status.pct_complete => 5
If an error occurs within the job instance, the status is set to ‘failed’ and then the error is re-raised so that Resque can capture it.
Its also possible to get a list of current/recent job statuses:
Resque::Status.statuses #=> [#<Resque::Status>, ...]
¶ ↑
Passing back data from the jobYou may want to save data from inside the job to access it from outside the job.
A common use-case is web-triggered jobs that create files, later available for download by the user.
A Status is actually just a hash, so inside a job you can do:
status['filename'] = '/myfilename'
Also, all the status setting methods take any number of hash arguments. So you could do:
complete('filename' => '/myfilename')
¶ ↑
Kill! Kill! Kill!Because we’re tracking UUIDs per instance, and we’re checking in/updating the status on each iteration (using at
or tick
) we can kill specific jobs by UUID.
Resque::Status.kill(job_id)
The next time the job at job_id calls at
or tick, it will raise a Killed error and set the status to killed.
¶ ↑
ExpirationSince Redis is RAM based, we probably don’t want to keep these statuses around forever (at least until @antirez releases the VM feature). By setting expire_in, all statuses and thier related keys will expire in expire_in seconds from the last time theyre updated:
Resque::Status.expire_in = (60 * 60) # 1 hour
¶ ↑
resque-webThough the main purpose of these trackable jobs is to allow you to surface the status of user created jobs through you’re apps’ own UI, I’ve added a simple example UI as a plugin to resque-web.
To use, you need to setup a resque-web config file:
# ~/resque_conf.rb require 'resque/status_server'
Then start resque-web with your config:
resque-web ~/resque_conf.rb
This should launch resque-web in your browser and you should see a ‘Statuses’ tab.
¶ ↑
MoreSource: github.com/quirkey/resque-status API Docs: rdoc.info/projects/quirkey/resque-status Examples: github.com/quirkey/resque-status/tree/master/examples Resque: github.com/defunkt/resque
¶ ↑
ThanksResque is awesome, @defunkt needs a shout-out.
¶ ↑
Note on Patches/Pull Requests-
Fork the project.
-
Make your feature addition or bug fix.
-
Add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-
Send me a pull request. Bonus points for topic branches.
¶ ↑
CopyrightCopyright © 2010 Aaron Quint. See LICENSE for details.