Ent Tracking

Job Tracking

The job tracking subsystem allows you to track and query the current state of a job within Faktory Enterprise.

Configure Tracking

Tracked jobs must have a custom attribute of "track":1. By default, jobs are not tracked.

Setting Status

The SETSTATUS command takes a JSON hash which contains a set of optional attributes for a JID while it is working:

{
  "jid":         "1234567abcdef",    // required
  "percent":     12,                 // optional
  "desc":        "Calculating...",   // optional
  "reserve_for": 300,                // optional
}

• Since job status is specific to each job, jid is required
• percent allows the job to provide a "percentage complete" value
• desc allows the job to report its latest checkpoint in a readable form, i.e. a description
• reserve_for allows the job to extend its current reservation by that number of seconds.

Note: setting reserve_for requires a heavyweight operation in Redis. It's recommended you minimize your usage of this attribute if possible; if the job typically executes very quickly, don't update reserve_for.

Getting Status

The GETSTATUS command takes a JID and returns a JSON hash of the attributes above.

> GETSTATUS 1234567abcdef
{
  "jid":        "1234567abcdef",
  "state":      "enqueued",
  "updated_at": "2020-01-27T21:10:45Z",
}

Once a job starts working, the worker can call SETSTATUS to give status updates as job execution proceeds.

> GETSTATUS 1234567abcdef
{
  "jid":        "1234567abcdef",
  "percent":    12,
  "desc":       "Calculating...",
  "state":      "working",
  "updated_at": "2020-01-27T21:10:45Z",
}

Once the job is finished, callers can still request status for 30 minutes. Note desc and percent will retain the last value from SETSTATUS, Faktory does not touch them.

> GETSTATUS 1234567abcdef
{
  "jid": "1234567abcdef",
  "percent": 98,
  "desc": "Clearing caches...",
  "state": "success",
  "updated_at": "2020-01-27T21:10:45Z",
}

The Dreaded "unknown" Job State

There are several reasons why a job's state might be unknown:

• The JID is invalid or was never actually enqueued.
• The job was not tagged with the track variable in the job's custom attributes: custom:{"track":1}.
• The job's status structure has expired in Redis. It lives for 30 minutes and a bad queue backlog can lead to expiration.

Notes

• Job status expires 30 minutes after job reservation expiration so clients can still poll for values even after job success/failure.
• Valid job states are "unknown", "enqueued", "working", "success", "failed", and "dead".
• If a job is enqueued but does not start working within 30 minutes, it's possible for the status to expire and further status polls to return unknown.