Task Management¶
Pulp can execute almost any call asynchronously and some calls are always executed asynchronously. Pulp provides REST APIs to inspect and manage the tasks executing these calls.
Task Report¶
The task information object is used to report information about any asynchronously executed task.
_href (string) - uri path to retrieve this task report object.
state (string) - the current state of the task. The possible values include: ‘waiting’, ‘skipped’, ‘running’, ‘suspended’, ‘finished’, ‘error’ and ‘canceled’.
task_id (string) - the unique id of the task that is executing the asynchronous call
task_type (string) - deprecated the fully qualified (package/method) type of the task that is executing the asynchronous call. The field is empty for tasks performed by consumer agent.
progress_report (object) - arbitrary progress information, usually in the form of an object
result (any) - the return value of the call, if any
exception (null or string) - deprecated the error exception value, if any
traceback (null or array) - deprecated the resulting traceback if an exception was raised
start_time (null or string) - the time the call started executing
finish_time (null or string) - the time the call stopped executing
tags (array) - arbitrary tags useful for looking up the call report
spawned_tasks (array) - List of objects containing the uri and task id for any tasks that were spawned by this task.
worker_name (string) - The worker associated with the task. This field is empty if a worker is not yet assigned.
queue (string) - The queue associated with the task. This field is empty if a queue is not yet assigned.
error (null or object) - Any, errors that occurred that did not cause the overall call to fail. See Error Details.
Note
The exception and traceback fields have been deprecated as of Pulp 2.4. The information about errors that have occurred will be contained in the error block. See Error Details for more information.
Example Task Report:
{
"_href": "/pulp/api/v2/tasks/0fe4fcab-a040-11e1-a71c-00508d977dff/",
"state": "running",
"worker_name": "reserved_resource_worker-0@your.domain.com",
"task_id": "0fe4fcab-a040-11e1-a71c-00508d977dff",
"task_type": "pulp.server.tasks.repository.sync_with_auto_publish",
"progress_report": {}, # contents depend on the operation
"result": null,
"start_time": "2012-05-17T16:48:00Z",
"finish_time": null,
"exception": null,
"traceback": null,
"tags": [
"pulp:repository:f16",
"pulp:action:sync"
],
"spawned_tasks": [{"href": "/pulp/api/v2/tasks/7744e2df-39b9-46f0-bb10-feffa2f7014b/",
"task_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b" }],
"error": null
}
Polling Task Progress¶
Poll a task for progress and result information for the asynchronous call it is executing. Polling returns a Task Report
/pulp/api/v2/tasks/<task_id>/200 - if the task is found
404 - if the task is not found
Cancelling a Task¶
Some asynchronous tasks may be canceled by the user before they complete. A task must be in the waiting or running states in order to be canceled.
Note
It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be ‘canceled’ as a result of this call. In these instances this method call will still return a response code of 200.
/pulp/api/v2/tasks/<task_id>/200 - if the task cancellation request was successfully received
404 - if the task is not found
Listing Tasks¶
All currently running and waiting tasks may be listed. This returns an array of Task Report instances. the array can be filtered by tags.
/pulp/api/v2/tasks/tag (string) - (optional) only return tasks tagged with all tag parameters
200 - containing an array of tasks
Deleting Completed Tasks¶
All completed tasks with states finished, error, skipped may be deleted. This call returns response code 204 if successful or code 403 if the request is forbidden.
/pulp/api/v2/tasks/state (string) - (optional) only delete tasks currently in this state
For example:
/pulp/api/v2/tasks/?state=finished&state=skipped
204 - if the tasks were successfully deleted
403 - if there was a forbidden request
Searching for Tasks¶
API callers may also search for tasks. This uses a search criteria document.
/pulp/api/v2/tasks/search/200 - containing the list of tasks
/pulp/api/v2/tasks/search/For example:
/pulp/api/v2/tasks/search/?field=id&field=task_type&limit=20
200 - containing the array of tasks.
Task Group Management¶
Cancelling Tasks in a Task Group¶
All asynchronous tasks in a particular task group may be canceled by the user before they complete. A task must be in the waiting or running state in order to be canceled.
Note
It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be ‘canceled’ as a result of this call. In these instances this method call will still return a response code of 200.
/pulp/api/v2/task_groups/<group_id>/200 - if the task group cancellation request was successfully received
404 - if the task group is not found
Task Group Summary¶
Task Group Summary object summarizes the state of all the tasks belonging to a task group.
accepted (int) - number of tasks in ‘accepted’ state
finished (int) - number of tasks in ‘finished’ state
running (int) - number of tasks in ‘running’ state
canceled (int) - number of tasks in ‘canceled’ state
waiting (int) - number of tasks in ‘waiting’ state
skipped (int) - number of tasks in ‘skipped’ state
suspended (int) - number of tasks in ‘suspended’ state
error (int) - number of tasks in ‘error’ state
total (int) - total number of tasks in the task group
Example task group summary:
{
"accepted": 0,
"finished": 100,
"running": 4,
"canceled": 0,
"waiting": 2,
"skipped": 0,
"suspended": 0,
"error": 0,
"total": 106
}
Polling Task Group Progress¶
Poll a group of tasks for progress summary. Polling returns a Cancelling Tasks in a Task Group
/pulp/api/v2/task_groups/<task_group_id>/state_summary/200 - if the task group is found
404 - if the task group id is not found