Periodic Tasks

RelengAPI supports executing tasks periodically: a kind of distributed cron. Applications within the API use this functionality to perform regular maintenance tasks, prepare reports, and so on. The component implementing this functionality is named "badpenny".

Configuration

Badpenny configuration is performed in code, and its configuration cannot be modified from the API. However, extensive read-only access is provided for administrative purposes, to those with the base.badpenny.view permission.

Tasks and Jobs

A badpenny task is a named action that occurs on a schedule. That schedule is determined by the code implementing the action.

Tasks are defined in code, so they cannot be modified via the API. Tasks that were once defined in the code, but are no longer, are considered "inactive".

REST type BadpennyTask

A task describes an operation that occurs periodically.

Keys:
  • name (unicode) -- unique task name (based on the qualified Python function name)

  • last_success (int) -- last success of the task: -1 (never run), 0 (failed), or 1 (succeeded)

  • jobs ([BadpennyJob]) -- all recent jobs for this task; this is only returned when a single task

  • active (bool) -- true if the task is active (that is, if it is defined in the code).

  • schedule (unicode) -- a pretty description of the task's schedule, if active

A job is a single execution of a task's action. A job's life-cycle begins when it is created from the task. The job starts when it is actually executed on a machine in the celery cluster. The job completes when that execution is finished -- successfully or not.

Each job has a success flag, as well as a JSON-formatted result with arbitrary contents and some log output (BadpennyJobLog) to help with debugging.

REST type BadpennyJob

A job is a single occurrence of a task.

Keys:
  • id (int) -- unique job id

  • task_name (unicode) -- name of the task that created this job

  • created_at (datetime) -- time at which this job was created

  • started_at (datetime) -- time at which this job started executing

  • completed_at (datetime) -- time at which this job finished executing

  • successful (bool) -- true if the job was successful

This type represents a job log.

REST type BadpennyJobLog
Keys:
  • content (unicode) -- text log from the job

Endpoints

endpoint GET /badpenny/jobs
Response Body:

[BadpennyJob]

List all badpenny jobs.

endpoint GET /badpenny/jobs/<job_id>
Parameters:
  • job_id -- int

Response Body:

BadpennyJob

Get information on a badpenny job by its ID. Use this to poll for job completion.

endpoint GET /badpenny/jobs/<job_id>/logs
Parameters:
  • job_id -- int

Response Body:

BadpennyJobLog

Get logs for a badpenny job by its ID.

endpoint GET /badpenny/tasks
Parameters:
  • all -- bool - optional

Response Body:

[BadpennyTask]

List all badpenny tasks. With "?all=1", include inactive tasks.

endpoint GET /badpenny/tasks/<task_name>
Parameters:
  • task_name -- unicode

Response Body:

BadpennyTask

Get information on a badpenny task by name.

endpoint POST /badpenny/tasks/<task_name>/run-now
Parameters:
  • task_name -- unicode

Response Body:

BadpennyJob

Force the given badpenny task to run now. This method requires the base.badpenny.run permission.