[DOCS] Document _cat/tasks API
#47321
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| [[cat-tasks]] | ||
| === cat task management API | ||
| ++++ | ||
| <titleabbrev>cat task management</titleabbrev> | ||
| ++++ | ||
|
|
||
| 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 <<tasks,task management>> API. | ||
|
|
||
|
|
||
| [[cat-tasks-api-request]] | ||
| ==== {api-request-title} | ||
|
|
||
| `GET /_cat/_tasks/<task_id>` | ||
|
|
||
| `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 <<tasks,task management>> API. | ||
|
|
||
|
|
||
| [[cat-tasks-api-path-params]] | ||
| ==== {api-path-parms-title} | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id] | ||
|
There was a problem hiding this comment. Looking at the code, it should also support There was a problem hiding this comment. Thanks! These are included under the query parameters section. |
||
|
|
||
|
|
||
| [[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] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am not totally sure why task management is still beta. Perhaps, it is time to start a discussion about removal of this label. But since the non-cat API is marked beta, it is appropriate to use this label here as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've opened #47378 to discuss this more.