Task Management API
editTask Management API
editThe Task Management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible
Current Tasks Information
editThe task management API allows to retrieve information about the tasks currently executing on one or more nodes in the cluster.
Retrieves all tasks currently running on all nodes in the cluster. |
|
Retrieves all tasks running on nodes |
|
Retrieves all cluster-related tasks running on nodes |
The result will look similar to the following:
{ "nodes" : { "oTUltX4IQMOUUVeiohTt8A" : { "name" : "H5dfFeA", "transport_address" : "127.0.0.1:9300", "host" : "127.0.0.1", "ip" : "127.0.0.1:9300", "tasks" : { "oTUltX4IQMOUUVeiohTt8A:124" : { "node" : "oTUltX4IQMOUUVeiohTt8A", "id" : 124, "type" : "direct", "action" : "cluster:monitor/tasks/lists[n]", "start_time_in_millis" : 1458585884904, "running_time_in_nanos" : 47402, "cancellable" : false, "parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123" }, "oTUltX4IQMOUUVeiohTt8A:123" : { "node" : "oTUltX4IQMOUUVeiohTt8A", "id" : 123, "type" : "transport", "action" : "cluster:monitor/tasks/lists", "start_time_in_millis" : 1458585884904, "running_time_in_nanos" : 236042, "cancellable" : false } } } } }
It is also possible to retrieve information for a particular task. The following
example retrieves information about task oTUltX4IQMOUUVeiohTt8A:124
:
GET _tasks/oTUltX4IQMOUUVeiohTt8A:124
If the task isn’t found, the API returns a 404.
To retrieve all children of a particular task:
GET _tasks?parent_task_id=oTUltX4IQMOUUVeiohTt8A:123
If the parent isn’t found, the API does not return a 404.
You can also use the detailed
request parameter to get more information about
the running tasks. This is useful for telling one task from another but is more
costly to execute. For example, fetching all searches using the detailed
request parameter:
GET _tasks?actions=*search&detailed
The results might look like:
{ "nodes" : { "oTUltX4IQMOUUVeiohTt8A" : { "name" : "H5dfFeA", "transport_address" : "127.0.0.1:9300", "host" : "127.0.0.1", "ip" : "127.0.0.1:9300", "tasks" : { "oTUltX4IQMOUUVeiohTt8A:464" : { "node" : "oTUltX4IQMOUUVeiohTt8A", "id" : 464, "type" : "transport", "action" : "indices:data/read/search", "description" : "indices[test], types[test], search_type[QUERY_THEN_FETCH], source[{\"query\":...}]", "start_time_in_millis" : 1483478610008, "running_time_in_nanos" : 13991383, "cancellable" : true } } } } }
The new description
field contains human readable text that identifies the
particular request that the task is performing such as identifying the search
request being performed by a search task like the example above. Other kinds of
task have different descriptions, like _reindex
which
has the search and the destination, or _bulk
which just has the
number of requests and the destination indices. Many requests will only have an
empty description because more detailed information about the request is not
easily available or particularly helpful in identifying the request.
_tasks
requests with detailed
may also return a status
. This is a report
of the internal status of the task. As such its format varies from task to task.
While we try to keep the status
for a particular task consistent from version
to version this isn’t always possible because we sometimes change the
implementation. In that case we might remove fields from the status
for a
particular request so any parsing you do of the status might break in minor
releases.
The task API can also be used to wait for completion of a particular task. The
following call will block for 10 seconds or until the task with id
oTUltX4IQMOUUVeiohTt8A:12345
is completed.
GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
You can also wait for all tasks for certain action types to finish. This
command will wait for all reindex
tasks to finish:
GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
Tasks can be also listed using _cat version of the list tasks command, which accepts the same arguments as the standard list tasks command.
GET _cat/tasks GET _cat/tasks?detailed
Task Cancellation
editIf a long-running task supports cancellation, it can be cancelled with the cancel
tasks API. The following example cancels task oTUltX4IQMOUUVeiohTt8A:12345
:
POST _tasks/oTUltX4IQMOUUVeiohTt8A:12345/_cancel
The task cancellation command supports the same task selection parameters as the list tasks command, so multiple tasks
can be cancelled at the same time. For example, the following command will cancel all reindex tasks running on the
nodes nodeId1
and nodeId2
.
POST _tasks/_cancel?nodes=nodeId1,nodeId2&actions=*reindex
Task Grouping
editThe task lists returned by task API commands can be grouped either by nodes (default) or by parent tasks using the group_by
parameter.
The following command will change the grouping to parent tasks:
GET _tasks?group_by=parents
The grouping can be disabled by specifying none
as a group_by
parameter:
GET _tasks?group_by=none
Identifying running tasks
editThe X-Opaque-Id
header, when provided on the HTTP request header, is going to be returned as a header in the response as well as
in the headers
field for in the task information. This allows to track certain calls, or associate certain tasks with
a the client that started them:
curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents"
The result will look similar to the following:
HTTP/1.1 200 OK X-Opaque-Id: 123456 content-type: application/json; charset=UTF-8 content-length: 831 { "tasks" : { "u5lcZHqcQhu-rUoFaqDphA:45" : { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 45, "type" : "transport", "action" : "cluster:monitor/tasks/lists", "start_time_in_millis" : 1513823752749, "running_time_in_nanos" : 293139, "cancellable" : false, "headers" : { "X-Opaque-Id" : "123456" }, "children" : [ { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 46, "type" : "direct", "action" : "cluster:monitor/tasks/lists[n]", "start_time_in_millis" : 1513823752750, "running_time_in_nanos" : 92133, "cancellable" : false, "parent_task_id" : "u5lcZHqcQhu-rUoFaqDphA:45", "headers" : { "X-Opaque-Id" : "123456" } } ] } } }