README.md in backburner-0.1.1 vs README.md in backburner-0.1.2
- old
+ new
@@ -84,18 +84,24 @@
```ruby
Backburner.configure do |config|
config.beanstalk_url = ["beanstalk://127.0.0.1", "beanstalk://127.0.0.1:11301"]
config.tube_namespace = "some.app.production"
config.on_error = lambda { |e| puts e }
+ config.max_job_retries = 3 # default 0 retries
+ config.retry_delay = 2 # default 5 seconds
config.default_priority = 65536
- config.respond_timeout = 120
+ config.respond_timeout = 120
+ config.logger = Logger.new(STDOUT)
end
```
-The `beanstalk_url` supports a string such as 'beanstalk://127.0.0.1' or an array of addresses.
-The `tube_namespace` is the prefix used for all tubes related to this backburner queue.
-The `on_error` is a callback that gets invoked with the error whenever a job fails
+ * The `beanstalk_url` supports a string such as 'beanstalk://127.0.0.1' or an array of addresses.
+ * The `tube_namespace` is the prefix used for all tubes related to this backburner queue.
+ * The `on_error` is a callback that gets invoked with the error whenever a job fails.
+ * The `max_job_retries` determines how many times to retry a job before burying
+ * The `retry_delay` determines the base time to wait (in secs) between retries
+ * The `logger` is the logger object written to when backburner wants to report info or errors.
## Usage
Backburner allows you to create jobs and place them on a beanstalk queue, and later pull those jobs off the queue and
process them asynchronously.
@@ -225,23 +231,47 @@
The `default_queues` stores the specific list of queues that should be processed by default by a worker.
### Failures
-You can setup the error handler for jobs using configure:
+When a job fails in backburner (usually because an exception was raised), the job will be released
+and retried again (with progressive delays in between) until the `max_job_retries` configuration is reached.
```ruby
Backburner.configure do |config|
+ config.max_job_retries = 3 # retry jobs 3 times
+ config.retry_delay = 2 # wait 2 seconds in between retries
+end
+```
+
+Note the default `max_job_retries` is 0, meaning that by default **jobs are not retried**.
+If continued retry attempts fail, the job will be buried and can be 'kicked' later for inspection.
+
+You can also setup a custom error handler for jobs using configure:
+
+```ruby
+Backburner.configure do |config|
config.on_error = lambda { |ex| Airbrake.notify(ex) }
end
```
-Now all beanstalk queue errors will show up on airbrake.
-If a job fails in beanstalk, the job is automatically buried and must be 'kicked' later.
+Now all backburner queue errors will appear on airbrake for deeper inspection.
### Logging
-Right now, all logging happens to standard out and can be piped to a file or any other output manually. More on logging coming later.
+Logging in backburner is rather simple. When a job is run, the log records that. When a job
+fails, the log records that. When any exceptions occur during processing, the log records that.
+
+By default, the log will print to standard out. You can customize the log to output to any
+standard logger by controlling the configuration option:
+
+```ruby
+Backburner.configure do |config|
+ config.logger = Logger.new(STDOUT)
+end
+```
+
+Be sure to check logs whenever things do not seem to be processing.
### Web Front-end
Be sure to check out the Sinatra-powered project [beanstalkd_view](https://github.com/denniskuczynski/beanstalkd_view)
by [denniskuczynski](http://github.com/denniskuczynski) which provides an excellent overview of the tubes and
\ No newline at end of file