The Job Payload

A Faktory job is a JSON hash with a few mandatory elements. The bare minimum:

{
  "jid": "123861239abnadsa",
  "jobtype": "SomeName",
  "args": [1, 2, "hello"],
}

The worker uses jobtype to determine how to execute this job. The args is an array of parameters necessary for the job to execute, it may be empty. jid is a unique Job ID for each job.

You may consider a job as a function invocation. jobtype is the name of the function, args is the parameters.

Options

You can customize Faktory's behavior by setting additional elements in the JSON hash:

• "queue": "default" - push this job to a particular queue. The default queue is, unsurprisingly, "default".
• "reserve_for": 600 - set the reservation timeout for a job, in seconds. When a worker fetches a job, it has up to N seconds to ACK or FAIL the job. After N seconds, the job will be requeued for execution by another worker. Default is 1800 seconds or 30 minutes, minimum is 60 seconds.
• "at": "2017-12-20T15:30:17.111222333Z" - schedule a job to run at a point in time. The job will be enqueued within a few seconds of that point in time. Note the string must be in Go's RFC3339Nano time format.
• "retry": 3 - set the number of retries to perform if this job fails. Default is 25 (which, with exponential backoff, means Faktory will retry the job over a 21 day period). A value of 0 means the job will not be retried and will be discarded if it fails. A value of -1 means don't retry but move the job immediately to the Dead set if it fails.
• "backtrace": 10 - retain up to N lines of backtrace given to the FAIL command. Default is 0. Faktory is not designed to be a full-blown error service, your workers should integrate with existing error services, but you can enable this to get a better view of why a job is retrying in the Web UI.

Custom Data

Faktory workers can have plugins and middleware which need to store additional context with the job payload. Faktory supports a custom hash to store arbitrary key/values in the JSON. This can be extremely helpful for cross-cutting concerns which should propagate between systems, e.g. locale for user-specific text translations, request_id for tracing execution across a complex distributed system, etc.

{
  "jid": "123861239abnadsa",
  "jobtype": "SomeName",
  "args": [1, 2, "hello"],
  "custom": {
    "locale": "fr",
    "user_id": 1234567,
    "request_id": "5359948e-6475-47cd-b3bb-3903002a28ca"
  }
}

Note that Faktory will discard any custom data elements outside of the custom hash.