143 lines
4.6 KiB
Plaintext
143 lines
4.6 KiB
Plaintext
[[tasks]]
|
|
== Task Management API
|
|
|
|
experimental[The Task Management API is new and should still be considered experimental. The API may change in ways that are not backwards compatible]
|
|
|
|
[float]
|
|
=== Current Tasks Information
|
|
|
|
The task management API allows to retrieve information about the tasks currently
|
|
executing on one or more nodes in the cluster.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks <1>
|
|
GET _tasks?nodes=nodeId1,nodeId2 <2>
|
|
GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
<1> Retrieves all tasks currently running on all nodes in the cluster.
|
|
<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <<cluster-nodes>> for more info about how to select individual nodes.
|
|
<3> Retrieves all cluster-related tasks running on nodes `nodeId1` and `nodeId2`.
|
|
|
|
The result will look similar to the following:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"nodes" : {
|
|
"oTUltX4IQMOUUVeiohTt8A" : {
|
|
"name" : "Tamara Rahn",
|
|
"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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks/taskId:1 <1>
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[catch:missing]
|
|
|
|
<1> This will return a 404 if the task isn't found.
|
|
|
|
Or to retrieve all children of a particular task:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks?parent_task_id=parentTaskId:1 <1>
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
<1> This won't return a 404 if the parent isn't found.
|
|
|
|
The task API can be also 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.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[catch:missing]
|
|
|
|
You can also wait for all tasks for certain action types to finish. This
|
|
command will wait for all `reindex` tasks to finish:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Tasks can be also listed using _cat version of the list tasks command, which accepts the same arguments
|
|
as the standard list tasks command.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _cat/tasks
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[float]
|
|
=== Task Cancellation
|
|
|
|
If a long-running task supports cancellation, it can be cancelled by the following command:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _tasks/taskId:1/_cancel
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
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`.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _tasks/_cancel?node_id=nodeId1,nodeId2&actions=*reindex
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
|
|
[float]
|
|
=== Task Grouping
|
|
|
|
The 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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks?group_by=parents
|
|
--------------------------------------------------
|
|
// CONSOLE
|