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 JSON-native parameters necessary for the job to execute, it may be empty. jid is a unique Job ID for each job.

Arguments must be native JSON datatypes: String, Number, Boolean, Map, Array and null. You cannot pass complex objects/structures or other types, even if they are native to your specific language.

You can think of 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, best practice is to integrate your workers with an existing error service, but you can enable this to get a better view of why a job is retrying in the Web UI.

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

Metadata

Faktory provides a few, possibly useful pieces of job metadata in the payload:

• "created_at": "2017-12-20T15:30:17.111222333Z" - the client may set this or Faktory will fill it in when it receives a job.
• "enqueued_at": "2017-12-20T15:30:17.111222333Z" - Faktory will set this when it enqueues a job.
• "failure": { ...data... } - a hash with data about this job's most recent failure

Failure

If your job fails, Faktory will store a failure hash inside the job payload with elements which might be useful for debugging. These elements, including error message and backtrace, are displayed in the Web UI when looking at job details, i.e. go to the Retries tab and click any job in the list.

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.

For the nitty-gritty, the fundamental definition of a Job in Faktory can be found in client/job.go.