diff --git a/docs/reference/cluster.asciidoc b/docs/reference/cluster.asciidoc index a42371b1054..7955239fc5d 100644 --- a/docs/reference/cluster.asciidoc +++ b/docs/reference/cluster.asciidoc @@ -45,7 +45,7 @@ include::cluster/nodes-stats.asciidoc[] include::cluster/nodes-info.asciidoc[] -include::cluster/nodes-task.asciidoc[] +include::cluster/tasks.asciidoc[] include::cluster/nodes-hot-threads.asciidoc[] diff --git a/docs/reference/cluster/nodes-task.asciidoc b/docs/reference/cluster/nodes-task.asciidoc deleted file mode 100644 index 85a8e758699..00000000000 --- a/docs/reference/cluster/nodes-task.asciidoc +++ /dev/null @@ -1,49 +0,0 @@ -[[nodes-task]] -== Nodes Task API - -The nodes task management API retrieves information about the tasks currently -executing on one or more nodes in the cluster. - -[source,js] --------------------------------------------------- -GET /_tasks <1> -GET /_tasks/nodeId1,nodeId2 <2> -GET /_tasks/nodeId1,nodeId2/cluster:* <3> --------------------------------------------------- -// AUTOSENSE - -<1> Retrieves all tasks currently running on all nodes in the cluster. -<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <> 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": { - "fDlEl7PrQi6F-awHZ3aaDw": { - "name": "Gazer", - "transport_address": "127.0.0.1:9300", - "host": "127.0.0.1", - "ip": "127.0.0.1:9300", - "tasks": [ - { - "node": "fDlEl7PrQi6F-awHZ3aaDw", - "id": 105, - "type": "transport", - "action": "cluster:monitor/nodes/tasks" - }, - { - "node": "fDlEl7PrQi6F-awHZ3aaDw", - "id": 106, - "type": "direct", - "action": "cluster:monitor/nodes/tasks[n]", - "parent_node": "fDlEl7PrQi6F-awHZ3aaDw", - "parent_id": 105 - } - ] - } - } -} --------------------------------------------------- diff --git a/docs/reference/cluster/pending.asciidoc b/docs/reference/cluster/pending.asciidoc index 4997a035ba2..84315073129 100644 --- a/docs/reference/cluster/pending.asciidoc +++ b/docs/reference/cluster/pending.asciidoc @@ -5,6 +5,11 @@ The pending cluster tasks API returns a list of any cluster-level changes (e.g. create index, update mapping, allocate or fail shard) which have not yet been executed. +NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the +<> which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create +index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task +might be reported by both task api and pending cluster tasks API. + [source,js] -------------------------------------------------- $ curl -XGET 'http://localhost:9200/_cluster/pending_tasks' diff --git a/docs/reference/cluster/tasks.asciidoc b/docs/reference/cluster/tasks.asciidoc new file mode 100644 index 00000000000..bb03231fc83 --- /dev/null +++ b/docs/reference/cluster/tasks.asciidoc @@ -0,0 +1,103 @@ +[[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> +-------------------------------------------------- +// AUTOSENSE + +<1> Retrieves all tasks currently running on all nodes in the cluster. +<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <> 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, + "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 + } + } + } + } +} + +-------------------------------------------------- + +It is also possible to retrieve information for a particular task, or all children of a particular +tasks using the following two commands: + +[source,js] +-------------------------------------------------- +GET /_tasks/taskId1 +GET /_tasks?parent_task_id=parentTaskId1 +-------------------------------------------------- +// AUTOSENSE + +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 +-------------------------------------------------- +// AUTOSENSE + + +[float] +=== Task Cancellation + +If a long-running task supports cancellation, it can be cancelled by the following command: + +[source,js] +-------------------------------------------------- +POST /_tasks/taskId1/_cancel +-------------------------------------------------- +// AUTOSENSE + +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 +-------------------------------------------------- +// AUTOSENSE + + + + diff --git a/docs/reference/docs/reindex.asciidoc b/docs/reference/docs/reindex.asciidoc index a825a8eca44..5d57d4a9073 100644 --- a/docs/reference/docs/reindex.asciidoc +++ b/docs/reference/docs/reindex.asciidoc @@ -390,7 +390,7 @@ from aborting the operation. === Works with the Task API While Reindex is running you can fetch their status using the -<>: +<>: [source,js] -------------------------------------------------- @@ -413,24 +413,26 @@ The responses looks like: "testattr" : "test", "portsfile" : "true" }, - "tasks" : [ { - "node" : "r1A2WoRbTwKZ516z6NEs5A", - "id" : 36619, - "type" : "transport", - "action" : "indices:data/write/reindex", - "status" : { <1> - "total" : 6154, - "updated" : 3500, - "created" : 0, - "deleted" : 0, - "batches" : 36, - "version_conflicts" : 0, - "noops" : 0, - "retries": 0, - "throttled_millis": 0 - }, - "description" : "" - } ] + "tasks" : { + "r1A2WoRbTwKZ516z6NEs5A:36619" : { + "node" : "r1A2WoRbTwKZ516z6NEs5A", + "id" : 36619, + "type" : "transport", + "action" : "indices:data/write/reindex", + "status" : { <1> + "total" : 6154, + "updated" : 3500, + "created" : 0, + "deleted" : 0, + "batches" : 36, + "version_conflicts" : 0, + "noops" : 0, + "retries": 0, + "throttled_millis": 0 + }, + "description" : "" + } + } } } } diff --git a/docs/reference/docs/update-by-query.asciidoc b/docs/reference/docs/update-by-query.asciidoc index f7ddf1d087c..84bd61f3e9b 100644 --- a/docs/reference/docs/update-by-query.asciidoc +++ b/docs/reference/docs/update-by-query.asciidoc @@ -235,11 +235,11 @@ from aborting the operation. === Works with the Task API While Update By Query is running you can fetch their status using the -<>: +<>: [source,js] -------------------------------------------------- -POST /_tasks/?pretty&detailed=true&action=byquery +POST /_tasks/?pretty&detailed=true&action=*byquery -------------------------------------------------- // AUTOSENSE @@ -258,24 +258,26 @@ The responses looks like: "testattr" : "test", "portsfile" : "true" }, - "tasks" : [ { - "node" : "r1A2WoRbTwKZ516z6NEs5A", - "id" : 36619, - "type" : "transport", - "action" : "indices:data/write/update/byquery", - "status" : { <1> - "total" : 6154, - "updated" : 3500, - "created" : 0, - "deleted" : 0, - "batches" : 36, - "version_conflicts" : 0, - "noops" : 0, - "retries": 0, - "throttled_millis": 0 - }, - "description" : "" - } ] + "tasks" : { + "r1A2WoRbTwKZ516z6NEs5A:36619" : { + "node" : "r1A2WoRbTwKZ516z6NEs5A", + "id" : 36619, + "type" : "transport", + "action" : "indices:data/write/update/byquery", + "status" : { <1> + "total" : 6154, + "updated" : 3500, + "created" : 0, + "deleted" : 0, + "batches" : 36, + "version_conflicts" : 0, + "noops" : 0, + "retries": 0, + "throttled_millis": 0 + }, + "description" : "" + } + } } } }