Job.addLog

Method Signature

Job.addLog(log)

Parameter: log Object

• A log object created by calling Job.createLog.

Returns: Promise => true

Job.addLog(message)

Parameter: message String

• A message string to log against the job.

Returns: Promise => true

Job.addLog(data)

Parameter: data Object

• A data object to log against the job.

Returns: Promise => true

Description

During the life cycle of a job the Queue objects will populate job history as log entries. At anytime you can call Queue.getJob or Queue.findJob and examine the Job.log property.

For any reason at all you may want to add your own log entry to a job in the queue. This is easy to do thanks to both the Job.createLog and the Job.addLog methods on a Job object. Once a log has been added to the job it will exist in the database on the Job.log property within an Array of log entries.

So you can appreciate what a job log looks like, here is the result of calling Job.getCleanCopy(true) on a job with some history. This job was taken from the rethinkdb-job-queue process tests.

{ dateCreated: 2016-08-17T03:44:30.634Z,
  dateFinished: 2016-08-17T03:44:42.123Z,
  dateEnable: 2016-08-17T03:44:48.086Z,
  dateStarted: 2016-08-17T03:44:41.086Z,
  id: '0e4a717c-84b1-43f3-98dd-2e670ebc28f9',
  log:
  [ { date: 2016-08-17T03:44:30.634Z,
      message: 'Job added to the queue',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 0,
      status: 'waiting',
      type: 'information' },
    { date: 2016-08-17T03:44:30.672Z,
      message: 'Job retrieved and active',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 0,
      status: 'active',
      type: 'information' },
    { date: 2016-08-17T03:44:31.728Z,
      duration: 1056,
      message: 'Job timed out (run time > 1 sec)',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 1,
      status: 'failed',
      type: 'warning' },
    { date: 2016-08-17T03:44:31.746Z,
      message: 'Job retrieved and active',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 1,
      status: 'active',
      type: 'information' },
    { date: 2016-08-17T03:44:32.765Z,
      duration: 1018,
      message: 'Job timed out (run time > 1 sec)',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 2,
      status: 'failed',
      type: 'warning' },
    { date: 2016-08-17T03:44:35.883Z,
      message: 'Job retrieved and active',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 2,
      status: 'active',
      type: 'information' },
    { date: 2016-08-17T03:44:36.904Z,
      duration: 1021,
      message: 'Job timed out (run time > 1 sec)',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 3,
      status: 'failed',
      type: 'warning' },
    { date: 2016-08-17T03:44:41.086Z,
      message: 'Job retrieved and active',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 3,
      status: 'active',
      type: 'information' },
    { date: 2016-08-17T03:44:42.123Z,
      duration: 1037,
      message: 'Job timed out (run time > 1 sec)',
      queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
      retryCount: 3,
      status: 'terminated',
      type: 'error' } ],
  data: 'The quick brown fox jumped over the lazy dog',
  priority: 'normal',
  progress: 0,
  queueId: 'WebDev:rjqJobQueueTests:rjqJobQueueTestJobs:7615:baad3b28-80c9-48ba-a800-73a2ae3a89a2',
  retryCount: 3,
  retryDelay: 2,
  retryMax: 3,
  status: 'terminated',
  timeout: 1 }

Should I add a Log, string, or data?

Log Object

The preferred method for adding a complex log entry to a job would be to first call Job.createLog to obtain a Log object, populate the object with extra information, then commit the log to the database by calling Job.addLog.

let log = job.createLog() // createLog has some parameters not shown here
log.message = 'This is your log message'
// Add any other properties you want to the log
log.jobState = { // Some complex object }

job.addLog(log).catch(err => console.log(err))

String Message

If you only need to log a quick message against the job, simply call Job.addLog passing in a message string. The message will be attached to the log.message property of the log entry.

job.addLog('This is your log message').catch(err => console.log(err))

Data Object

Finally, you can add a complex object by passing it to the addLog method. The object will be attached to the log.data property of the log entry.

job.addLog({ // Some complex object }).catch(err => console.log(err))

Example

The following is a complete example of creating a job, adding it to the queue, creating a log, adding the log to the job, and getting the job from the database. This example does not include processing jobs with Queue.process.

const Queue = require('rethinkdb-job-queue')
const q = new Queue()
let job = q.createJob({ content: 'some job data' })

q.addJob(job).then((savedJobs) => {
  sJob = savedJobs[0]

  const newLog = sJob.createLog('log history message')
  newLog.extraInformation = 'Something you want to add'

  return sJob.addLog(newLog)
}).then(() => {
  // The in memory job will have the new log
  // No need to call getJob
  return q.getJob(job)
}).then((ourJobs) => {
  oJob = ourJobs[0]

  // oJob.log.length === 2
  // One log for being added to the queue and
  // one custom log entry.

  // oJob.log[1].extraInformation === 'Something you want to add'

}).catch(err => console.error(err))