Skip to content

Commit c356b30

Browse files
imotovimotov
committed
Update task management docs to reflect the latest changes in the interface
Brings docs in line with new list task syntax and adds task cancellation API docs.
1 parent 48b4f08 commit c356b30

File tree

6 files changed

+152
-89
lines changed

6 files changed

+152
-89
lines changed

‎docs/reference/cluster.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ include::cluster/nodes-stats.asciidoc[]
4545

4646
include::cluster/nodes-info.asciidoc[]
4747

48-
include::cluster/nodes-task.asciidoc[]
48+
include::cluster/tasks.asciidoc[]
4949

5050
include::cluster/nodes-hot-threads.asciidoc[]
5151

‎docs/reference/cluster/nodes-task.asciidoc‎

Lines changed: 0 additions & 49 deletions
This file was deleted.

‎docs/reference/cluster/pending.asciidoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@ The pending cluster tasks API returns a list of any cluster-level changes
55
(e.g. create index, update mapping, allocate or fail shard) which have not yet
66
been executed.
77

8+
NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the
9+
<<tasks,Task Management API>> which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create
10+
index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task
11+
might be reported by both task api and pending cluster tasks API.
12+
813
[source,js]
914
--------------------------------------------------
1015
$ curl -XGET 'http://localhost:9200/_cluster/pending_tasks'

‎docs/reference/cluster/tasks.asciidoc‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
[[tasks]]
2+
== Task Management API
3+
4+
experimental[The Task Management API is new and should still be considered experimental. The API may change in ways that are not backwards compatible]
5+
6+
[float]
7+
=== Current Tasks Information
8+
9+
The task management API allows to retrieve information about the tasks currently
10+
executing on one or more nodes in the cluster.
11+
12+
[source,js]
13+
--------------------------------------------------
14+
GET /_tasks <1>
15+
GET /_tasks?nodes=nodeId1,nodeId2 <2>
16+
GET /_tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
17+
--------------------------------------------------
18+
// AUTOSENSE
19+
20+
<1> Retrieves all tasks currently running on all nodes in the cluster.
21+
<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <<cluster-nodes>> for more info about how to select individual nodes.
22+
<3> Retrieves all cluster-related tasks running on nodes `nodeId1` and `nodeId2`.
23+
24+
The result will look similar to the following:
25+
26+
[source,js]
27+
--------------------------------------------------
28+
{
29+
"nodes" : {
30+
"oTUltX4IQMOUUVeiohTt8A" : {
31+
"name" : "Tamara Rahn",
32+
"transport_address" : "127.0.0.1:9300",
33+
"host" : "127.0.0.1",
34+
"ip" : "127.0.0.1:9300",
35+
"tasks" : {
36+
"oTUltX4IQMOUUVeiohTt8A:124" : {
37+
"node" : "oTUltX4IQMOUUVeiohTt8A",
38+
"id" : 124,
39+
"type" : "direct",
40+
"action" : "cluster:monitor/tasks/lists[n]",
41+
"start_time_in_millis" : 1458585884904,
42+
"running_time_in_nanos" : 47402,
43+
"parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
44+
},
45+
"oTUltX4IQMOUUVeiohTt8A:123" : {
46+
"node" : "oTUltX4IQMOUUVeiohTt8A",
47+
"id" : 123,
48+
"type" : "transport",
49+
"action" : "cluster:monitor/tasks/lists",
50+
"start_time_in_millis" : 1458585884904,
51+
"running_time_in_nanos" : 236042
52+
}
53+
}
54+
}
55+
}
56+
}
57+
58+
--------------------------------------------------
59+
60+
It is also possible to retrieve information for a particular task, or all children of a particular
61+
tasks using the following two commands:
62+
63+
[source,js]
64+
--------------------------------------------------
65+
GET /_tasks/taskId1
66+
GET /_tasks?parent_task_id=parentTaskId1
67+
--------------------------------------------------
68+
// AUTOSENSE
69+
70+
The task API can be also used to wait for completion of a particular task. The following call will
71+
block for 10 seconds or until the task with id `oTUltX4IQMOUUVeiohTt8A:12345` is completed.
72+
73+
[source,js]
74+
--------------------------------------------------
75+
GET /_tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
76+
--------------------------------------------------
77+
// AUTOSENSE
78+
79+
80+
[float]
81+
=== Task Cancellation
82+
83+
If a long-running task supports cancellation, it can be cancelled by the following command:
84+
85+
[source,js]
86+
--------------------------------------------------
87+
POST /_tasks/taskId1/_cancel
88+
--------------------------------------------------
89+
// AUTOSENSE
90+
91+
The task cancellation command supports the same task selection parameters as the list tasks command, so multiple tasks
92+
can be cancelled at the same time. For example, the following command will cancel all reindex tasks running on the
93+
nodes `nodeId1` and `nodeId2`.
94+
95+
[source,js]
96+
--------------------------------------------------
97+
POST /_tasks/_cancel?node_id=nodeId1,nodeId2&actions=*reindex
98+
--------------------------------------------------
99+
// AUTOSENSE
100+
101+
102+
103+

‎docs/reference/docs/reindex.asciidoc‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -390,7 +390,7 @@ from aborting the operation.
390390
=== Works with the Task API
391391

392392
While Reindex is running you can fetch their status using the
393-
<<nodes-task,Nodes Task API>>:
393+
<<tasks,Task API>>:
394394

395395
[source,js]
396396
--------------------------------------------------
@@ -413,24 +413,26 @@ The responses looks like:
413413
"testattr" : "test",
414414
"portsfile" : "true"
415415
},
416-
"tasks" : [ {
417-
"node" : "r1A2WoRbTwKZ516z6NEs5A",
418-
"id" : 36619,
419-
"type" : "transport",
420-
"action" : "indices:data/write/reindex",
421-
"status" : { <1>
422-
"total" : 6154,
423-
"updated" : 3500,
424-
"created" : 0,
425-
"deleted" : 0,
426-
"batches" : 36,
427-
"version_conflicts" : 0,
428-
"noops" : 0,
429-
"retries": 0,
430-
"throttled_millis": 0
431-
},
432-
"description" : ""
433-
} ]
416+
"tasks" : {
417+
"r1A2WoRbTwKZ516z6NEs5A:36619" : {
418+
"node" : "r1A2WoRbTwKZ516z6NEs5A",
419+
"id" : 36619,
420+
"type" : "transport",
421+
"action" : "indices:data/write/reindex",
422+
"status" : { <1>
423+
"total" : 6154,
424+
"updated" : 3500,
425+
"created" : 0,
426+
"deleted" : 0,
427+
"batches" : 36,
428+
"version_conflicts" : 0,
429+
"noops" : 0,
430+
"retries": 0,
431+
"throttled_millis": 0
432+
},
433+
"description" : ""
434+
}
435+
}
434436
}
435437
}
436438
}

‎docs/reference/docs/update-by-query.asciidoc‎

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -235,11 +235,11 @@ from aborting the operation.
235235
=== Works with the Task API
236236

237237
While Update By Query is running you can fetch their status using the
238-
<<nodes-task,Nodes Task API>>:
238+
<<tasks,Task API>>:
239239

240240
[source,js]
241241
--------------------------------------------------
242-
POST /_tasks/?pretty&detailed=true&action=byquery
242+
POST /_tasks/?pretty&detailed=true&action=*byquery
243243
--------------------------------------------------
244244
// AUTOSENSE
245245

@@ -258,24 +258,26 @@ The responses looks like:
258258
"testattr" : "test",
259259
"portsfile" : "true"
260260
},
261-
"tasks" : [ {
262-
"node" : "r1A2WoRbTwKZ516z6NEs5A",
263-
"id" : 36619,
264-
"type" : "transport",
265-
"action" : "indices:data/write/update/byquery",
266-
"status" : { <1>
267-
"total" : 6154,
268-
"updated" : 3500,
269-
"created" : 0,
270-
"deleted" : 0,
271-
"batches" : 36,
272-
"version_conflicts" : 0,
273-
"noops" : 0,
274-
"retries": 0,
275-
"throttled_millis": 0
276-
},
277-
"description" : ""
278-
} ]
261+
"tasks" : {
262+
"r1A2WoRbTwKZ516z6NEs5A:36619" : {
263+
"node" : "r1A2WoRbTwKZ516z6NEs5A",
264+
"id" : 36619,
265+
"type" : "transport",
266+
"action" : "indices:data/write/update/byquery",
267+
"status" : { <1>
268+
"total" : 6154,
269+
"updated" : 3500,
270+
"created" : 0,
271+
"deleted" : 0,
272+
"batches" : 36,
273+
"version_conflicts" : 0,
274+
"noops" : 0,
275+
"retries": 0,
276+
"throttled_millis": 0
277+
},
278+
"description" : ""
279+
}
280+
}
279281
}
280282
}
281283
}

0 commit comments

Comments
 (0)