Skip to content

Commit e702208

Browse files
jrodewigjrodewig
authored
[DOCS] Document cat tasks API (#47321) (#47375)
1 parent c93b39c commit e702208

File tree

4 files changed

+206
-27
lines changed

4 files changed

+206
-27
lines changed

‎docs/reference/cat.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,8 @@ include::cat/recovery.asciidoc[]
230230

231231
include::cat/repositories.asciidoc[]
232232

233+
include::cat/tasks.asciidoc[]
234+
233235
include::cat/thread_pool.asciidoc[]
234236

235237
include::cat/shards.asciidoc[]

‎docs/reference/cat/tasks.asciidoc

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
[[cat-tasks]]
2+
=== cat task management API
3+
++++
4+
<titleabbrev>cat task management</titleabbrev>
5+
++++
6+
7+
beta::[The cat task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.]
8+
9+
Returns information about tasks currently executing in the cluster,
10+
similar to the <<tasks,task management>> API.
11+
12+
13+
[[cat-tasks-api-request]]
14+
==== {api-request-title}
15+
16+
`GET /_cat/_tasks/<task_id>`
17+
18+
`GET /_cat/_tasks`
19+
20+
21+
[[cat-tasks-api-desc]]
22+
==== {api-description-title}
23+
24+
The cat task management API returns information
25+
about tasks currently executing
26+
on one or more nodes in the cluster.
27+
It is a more compact view
28+
of the JSON <<tasks,task management>> API.
29+
30+
31+
[[cat-tasks-api-path-params]]
32+
==== {api-path-parms-title}
33+
34+
include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id]
35+
36+
37+
[[cat-tasks-api-query-params]]
38+
==== {api-query-parms-title}
39+
40+
include::{docdir}/rest-api/common-parms.asciidoc[tag=actions]
41+
42+
include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed]
43+
44+
include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
45+
46+
include::{docdir}/rest-api/common-parms.asciidoc[tag=group-by]
47+
48+
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
49+
50+
include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
51+
52+
include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id-query-parm]
53+
54+
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
55+
56+
include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id]
57+
58+
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
59+
60+
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
61+
62+
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
63+
64+
65+
[[cat-tasks-api-response-codes]]
66+
==== {api-response-codes-title}
67+
68+
include::{docdir}/cluster/tasks.asciidoc[tag=tasks-api-404]
69+
70+
71+
[[cat-tasks-api-examples]]
72+
==== {api-examples-title}
73+
74+
75+
[[cat-tasks-api-specific-ex]]
76+
===== Get information for a specific task
77+
78+
[source,console]
79+
----
80+
GET _cat/tasks/oTUltX4IQMOUUVeiohTt8A:124?v
81+
----
82+
// TEST[skip:No tasks to retrieve]
83+
84+
The API returns the following response:
85+
86+
[source,txt]
87+
----
88+
action task_id parent_task_id type start_time timestamp running_time ip node
89+
cluster:monitor/tasks/lists[n] oTUltX4IQMOUUVeiohTt8A:124 oTUltX4IQMOUUVeiohTt8A:123 direct 1458585884904 01:48:24 44.1micros 127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A
90+
----
91+
// TESTRESPONSE[skip:No tasks to retrieve]
92+
// TESTRESPONSE[non_json]
93+
94+
95+
[[cat-tasks-api-all-ex]]
96+
===== Get information for all tasks in a cluster
97+
98+
[source,console]
99+
----
100+
GET _cat/tasks?v
101+
----
102+
// TEST[skip:No tasks to retrieve]
103+
104+
The API returns the following response:
105+
106+
[source,console-result]
107+
----
108+
action task_id parent_task_id type start_time timestamp running_time ip node
109+
cluster:monitor/tasks/lists[n] oTUltX4IQMOUUVeiohTt8A:124 oTUltX4IQMOUUVeiohTt8A:123 direct 1458585884904 01:48:24 44.1micros 127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A
110+
cluster:monitor/tasks/lists oTUltX4IQMOUUVeiohTt8A:123 - transport 1458585884904 01:48:24 186.2micros 127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A
111+
----
112+
// TESTRESPONSE[skip:No tasks to retrieve]
113+
// TESTRESPONSE[non_json]

‎docs/reference/cluster/tasks.asciidoc

Lines changed: 26 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,61 @@
11
[[tasks]]
2-
=== Task Management API
2+
=== Task management API
3+
++++
4+
<titleabbrev>Task management</titleabbrev>
5+
++++
36

4-
beta[The Task Management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible]
7+
beta[The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.]
58

69
Returns information about the tasks currently executing in the cluster.
710

811
[[tasks-api-request]]
912
==== {api-request-title}
1013

11-
`GET /_tasks` +
12-
1314
`GET /_tasks/<task_id>`
1415

16+
`GET /_tasks`
17+
1518

1619
[[tasks-api-desc]]
1720
==== {api-description-title}
1821

19-
The task management API allows to retrieve information about the tasks currently
20-
executing on one or more nodes in the cluster.
22+
The task management API returns information
23+
about tasks currently executing
24+
on one or more nodes in the cluster.
2125

2226

2327
[[tasks-api-path-params]]
2428
==== {api-path-parms-title}
2529

26-
`<task_id>`::
27-
(Optional, string) The ID of the task to return (`node_id:task_number`).
30+
include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id]
2831

2932

3033
[[tasks-api-query-params]]
3134
==== {api-query-parms-title}
3235

33-
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
36+
include::{docdir}/rest-api/common-parms.asciidoc[tag=actions]
37+
38+
include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed]
3439

35-
`wait_for_completion`::
36-
(Optional, boolean) If `true`, it waits for the matching tasks to complete.
37-
Defaults to `false`.
40+
include::{docdir}/rest-api/common-parms.asciidoc[tag=group-by]
41+
42+
include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id-query-parm]
43+
44+
include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id]
45+
46+
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
3847

48+
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
3949

4050

4151
[[tasks-api-response-codes]]
4252
==== {api-response-codes-title}
4353

54+
tag::tasks-api-404[]
4455
`404` (Missing resources)::
45-
If `{task_id}` is specified but not found, this code indicates that there
46-
are no resources that match the request.
47-
56+
If `<task_id>` is specified but not found, this code indicates that there
57+
are no resources that match the request.
58+
end::tasks-api-404[]
4859

4960
[[tasks-api-examples]]
5061
==== {api-examples-title}
@@ -205,18 +216,6 @@ will wait for all `reindex` tasks to finish:
205216
GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
206217
--------------------------------------------------
207218

208-
209-
===== Listing tasks by using _cat
210-
211-
Tasks can be also listed using _cat version of the list tasks command, which
212-
accepts the same arguments as the standard list tasks command.
213-
214-
[source,console]
215-
--------------------------------------------------
216-
GET _cat/tasks
217-
GET _cat/tasks?detailed
218-
--------------------------------------------------
219-
220219
[[task-cancellation]]
221220
===== Task Cancellation
222221

‎docs/reference/rest-api/common-parms.asciidoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,16 @@
11

2+
tag::actions[]
3+
`actions`::
4+
+
5+
--
6+
(Optional, string)
7+
Comma-separated list or wildcard expression
8+
of actions used to limit the request.
9+
10+
Omit this parameter to return all actions.
11+
--
12+
end::actions[]
13+
214
tag::active-only[]
315
`active_only`::
416
(Optional, boolean)
@@ -190,6 +202,32 @@ tag::from[]
190202
(Optional, integer) Starting document offset. Defaults to `0`.
191203
end::from[]
192204

205+
tag::generation[]
206+
Generation number, such as `0`. {es} increments this generation number
207+
for each segment written. {es} then uses this number to derive the segment name.
208+
end::generation[]
209+
210+
tag::group-by[]
211+
`group_by`::
212+
+
213+
--
214+
(Optional, string)
215+
Key used to group tasks in the response.
216+
217+
Possible values are:
218+
219+
`nodes`::
220+
(Default)
221+
Node ID
222+
223+
`parents`::
224+
Parent task ID
225+
226+
`none`::
227+
Do not group tasks.
228+
--
229+
end::group-by[]
230+
193231
tag::groups[]
194232
`groups`::
195233
(Optional, string)
@@ -419,6 +457,27 @@ tag::node-id[]
419457
returned information.
420458
end::node-id[]
421459

460+
tag::node-id-query-parm[]
461+
`node_id`::
462+
(Optional, string)
463+
Comma-separated list of node IDs or names
464+
used to limit returned information.
465+
end::node-id-query-parm[]
466+
467+
tag::parent-task-id[]
468+
`parent_task_id`::
469+
+
470+
--
471+
(Optional, string)
472+
Parent task ID
473+
used to limit returned information.
474+
475+
To return all tasks,
476+
omit this parameter
477+
or use a value of `-1`.
478+
--
479+
end::parent-task-id[]
480+
422481
tag::pipeline[]
423482
`pipeline`::
424483
(Optional, string) ID of the pipeline to use to preprocess incoming documents.
@@ -588,6 +647,12 @@ include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs]
588647
--
589648
end::target-index[]
590649

650+
tag::task-id[]
651+
`<task_id>`::
652+
(Optional, string) ID of the task to return
653+
(`node_id:task_number`).
654+
end::task-id[]
655+
591656
tag::terminate_after[]
592657
`terminate_after`::
593658
(Optional, integer) The maximum number of documents to collect for each shard,

0 commit comments

Comments
 (0)