diff --git a/docs/reference/cat.asciidoc b/docs/reference/cat.asciidoc index 25cf92a346728..50d3028101dd0 100644 --- a/docs/reference/cat.asciidoc +++ b/docs/reference/cat.asciidoc @@ -230,6 +230,8 @@ include::cat/recovery.asciidoc[] include::cat/repositories.asciidoc[] +include::cat/tasks.asciidoc[] + include::cat/thread_pool.asciidoc[] include::cat/shards.asciidoc[] diff --git a/docs/reference/cat/tasks.asciidoc b/docs/reference/cat/tasks.asciidoc new file mode 100644 index 0000000000000..95da2691bd4d0 --- /dev/null +++ b/docs/reference/cat/tasks.asciidoc @@ -0,0 +1,113 @@ +[[cat-tasks]] +=== cat task management API +++++ +cat task management +++++ + +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.] + +Returns information about tasks currently executing in the cluster, +similar to the <> API. + + +[[cat-tasks-api-request]] +==== {api-request-title} + +`GET /_cat/_tasks/` + +`GET /_cat/_tasks` + + +[[cat-tasks-api-desc]] +==== {api-description-title} + +The cat task management API returns information +about tasks currently executing +on one or more nodes in the cluster. +It is a more compact view +of the JSON <> API. + + +[[cat-tasks-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id] + + +[[cat-tasks-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=actions] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=group-by] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=help] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id-query-parm] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v] + + +[[cat-tasks-api-response-codes]] +==== {api-response-codes-title} + +include::{docdir}/cluster/tasks.asciidoc[tag=tasks-api-404] + + +[[cat-tasks-api-examples]] +==== {api-examples-title} + + +[[cat-tasks-api-specific-ex]] +===== Get information for a specific task + +[source,console] +---------------------------------------------------------------------------- +GET _cat/tasks/oTUltX4IQMOUUVeiohTt8A:124?v +---------------------------------------------------------------------------- +// TEST[skip:No tasks to retrieve] + +The API returns the following response: + +[source,txt] +---- +action task_id parent_task_id type start_time timestamp running_time ip node +cluster:monitor/tasks/lists[n] oTUltX4IQMOUUVeiohTt8A:124 oTUltX4IQMOUUVeiohTt8A:123 direct 1458585884904 01:48:24 44.1micros 127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A +---- +// TESTRESPONSE[skip:No tasks to retrieve] +// TESTRESPONSE[non_json] + + +[[cat-tasks-api-all-ex]] +===== Get information for all tasks in a cluster + +[source,console] +---- +GET _cat/tasks?v +---- +// TEST[skip:No tasks to retrieve] + +The API returns the following response: + +[source,console-result] +---- +action task_id parent_task_id type start_time timestamp running_time ip node +cluster:monitor/tasks/lists[n] oTUltX4IQMOUUVeiohTt8A:124 oTUltX4IQMOUUVeiohTt8A:123 direct 1458585884904 01:48:24 44.1micros 127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A +cluster:monitor/tasks/lists oTUltX4IQMOUUVeiohTt8A:123 - transport 1458585884904 01:48:24 186.2micros 127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A +---- +// TESTRESPONSE[skip:No tasks to retrieve] +// TESTRESPONSE[non_json] diff --git a/docs/reference/cluster/tasks.asciidoc b/docs/reference/cluster/tasks.asciidoc index 3c96639b3850c..9cbc421aa0133 100644 --- a/docs/reference/cluster/tasks.asciidoc +++ b/docs/reference/cluster/tasks.asciidoc @@ -1,50 +1,61 @@ [[tasks]] -=== Task Management API +=== Task management API +++++ +Task management +++++ -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] +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.] Returns information about the tasks currently executing in the cluster. [[tasks-api-request]] ==== {api-request-title} -`GET /_tasks` + - `GET /_tasks/` +`GET /_tasks` + [[tasks-api-desc]] ==== {api-description-title} -The task management API allows to retrieve information about the tasks currently -executing on one or more nodes in the cluster. +The task management API returns information +about tasks currently executing +on one or more nodes in the cluster. [[tasks-api-path-params]] ==== {api-path-parms-title} -``:: - (Optional, string) The ID of the task to return (`node_id:task_number`). +include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id] [[tasks-api-query-params]] ==== {api-query-parms-title} -include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] +include::{docdir}/rest-api/common-parms.asciidoc[tag=actions] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed] -`wait_for_completion`:: - (Optional, boolean) If `true`, it waits for the matching tasks to complete. - Defaults to `false`. +include::{docdir}/rest-api/common-parms.asciidoc[tag=group-by] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id-query-parm] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] +include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion] [[tasks-api-response-codes]] ==== {api-response-codes-title} +tag::tasks-api-404[] `404` (Missing resources):: - If `{task_id}` is specified but not found, this code indicates that there - are no resources that match the request. - +If `` is specified but not found, this code indicates that there +are no resources that match the request. +end::tasks-api-404[] [[tasks-api-examples]] ==== {api-examples-title} @@ -205,18 +216,6 @@ will wait for all `reindex` tasks to finish: GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s -------------------------------------------------- - -===== Listing tasks by using _cat - -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,console] --------------------------------------------------- -GET _cat/tasks -GET _cat/tasks?detailed --------------------------------------------------- - [[task-cancellation]] ===== Task Cancellation diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 106c9833c5898..849739f3e73e6 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -1,4 +1,16 @@ +tag::actions[] +`actions`:: ++ +-- +(Optional, string) +Comma-separated list or wildcard expression +used to limit the request. + +Omit this parameter to return all actions. +-- +end::actions[] + tag::active-only[] `active_only`:: (Optional, boolean) @@ -143,11 +155,6 @@ in the `completion_fields` or `fielddata_fields` parameters. -- end::fields[] -tag::generation[] -Generation number, such as `0`. {es} increments this generation number -for each segment written. {es} then uses this number to derive the segment name. -end::generation[] - tag::index-alias-filter[] <> used to limit the index alias. @@ -174,6 +181,32 @@ tag::from[] (Optional, integer) Starting document offset. Defaults to `0`. end::from[] +tag::generation[] +Generation number, such as `0`. {es} increments this generation number +for each segment written. {es} then uses this number to derive the segment name. +end::generation[] + +tag::group-by[] +`group_by`:: ++ +-- +(Optional, string) +Key used to group tasks in the response. + +Possible values are: + +`nodes`:: +(Default) +Node ID + +`parents`:: +Parent task ID + +`none`:: +Do not group tasks. +-- +end::group-by[] + tag::groups[] `groups`:: (Optional, string) @@ -403,6 +436,27 @@ tag::node-id[] returned information. end::node-id[] +tag::node-id-query-parm[] +`node_id`:: +(Optional, string) +Comma-separated list of node IDs or names +used to limit returned information. +end::node-id-query-parm[] + +tag::parent-task-id[] +`parent_task_id`:: ++ +-- +(Optional, string) +Parent task ID +used to limit returned information. + +To return all tasks, +omit this parameter +or use a value of `-1`. +-- +end::parent-task-id[] + tag::pipeline[] `pipeline`:: (Optional, string) ID of the pipeline to use to preprocess incoming documents. @@ -572,6 +626,12 @@ include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs] -- end::target-index[] +tag::task-id[] +``:: +(Optional, string) ID of the task to return +(`node_id:task_number`). +end::task-id[] + tag::terminate_after[] `terminate_after`:: (Optional, integer) The maximum number of documents to collect for each shard,