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