honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/reference/cluster/tasks.asciidoc

143 lines
4.6 KiB
Plaintext
Raw Normal View History

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.
2016-03-29 09:29:21 -04:00
[[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]
--------------------------------------------------
Generate and run tests from the docs Adds infrastructure so `gradle :docs:check` will extract tests from snippets in the documentation and execute the tests. This is included in `gradle check` so it should happen on CI and during a normal build. By default each `// AUTOSENSE` snippet creates a unique REST test. These tests are executed in a random order and the cluster is wiped between each one. If multiple snippets chain together into a test you can annotate all snippets after the first with `// TEST[continued]` to have the generated tests for both snippets joined. Snippets marked as `// TESTRESPONSE` are checked against the response of the last action. See docs/README.asciidoc for lots more. Closes #12583. That issue is about catching bugs in the docs during build. This catches *some* bugs in the docs during build which is a good start.
2016-04-29 10:42:03 -04:00
GET _tasks <1>
GET _tasks?nodes=nodeId1,nodeId2 <2>
GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
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.
2016-03-29 09:29:21 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE
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.
2016-03-29 09:29:21 -04:00
<1> Retrieves all tasks currently running on all nodes in the cluster.
<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <<cluster-nodes>> 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" : {
[DOC] Remove obsolete node names from documentation Funny node names have been removed in #19456 and replaced by UUID. This commit removes these obsolete node names and replace them by real UUIDs in the documentation. closes #20065
2016-09-16 08:32:03 -04:00
"name" : "H5dfFeA",
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.
2016-03-29 09:29:21 -04:00
"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,
Expose whether a task is cancellable in the _tasks list API Closes #17369
2016-03-31 18:41:45 -04:00
"cancellable" : false,
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.
2016-03-29 09:29:21 -04:00
"parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
},
"oTUltX4IQMOUUVeiohTt8A:123" : {
"node" : "oTUltX4IQMOUUVeiohTt8A",
"id" : 123,
"type" : "transport",
"action" : "cluster:monitor/tasks/lists",
"start_time_in_millis" : 1458585884904,
Expose whether a task is cancellable in the _tasks list API Closes #17369
2016-03-31 18:41:45 -04:00
"running_time_in_nanos" : 236042,
"cancellable" : false
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.
2016-03-29 09:29:21 -04:00
}
}
}
}
}
--------------------------------------------------
Create get task API that falls back to the .tasks index This adds a get task API that supports GET /_tasks/${taskId} and removes that responsibility from the list tasks API. The get task API supports wait_for_complation just as the list tasks API does but doesn't support any of the list task API's filters. In exchange, it supports falling back to the .results index when the task isn't running any more. Like any good GET API it 404s when it doesn't find the task. Then we change reindex, update-by-query, and delete-by-query to persist the task result when wait_for_completion=false. The leads to the neat behavior that, once you start a reindex with wait_for_completion=false, you can fetch the result of the task by using the get task API and see the result when it has finished. Also rename the .results index to .tasks.
2016-05-31 19:44:01 -04:00
It is also possible to retrieve information for a particular task:
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.
2016-03-29 09:29:21 -04:00
[source,js]
--------------------------------------------------
Remove lenient URL parameter parsing Today when parsing a request, Elasticsearch silently ignores incorrect (including parameters with typos) or unused parameters. This is bad as it leads to requests having unintended behavior (e.g., if a user hits the _analyze API and misspell the "tokenizer" then Elasticsearch will just use the standard analyzer, completely against intentions). This commit removes lenient URL parameter parsing. The strategy is simple: when a request is handled and a parameter is touched, we mark it as such. Before the request is actually executed, we check to ensure that all parameters have been consumed. If there are remaining parameters yet to be consumed, we fail the request with a list of the unconsumed parameters. An exception has to be made for parameters that format the response (as opposed to controlling the request); for this case, handlers are able to provide a list of parameters that should be excluded from tripping the unconsumed parameters check because those parameters will be used in formatting the response. Additionally, some inconsistencies between the parameters in the code and in the docs are corrected. Relates #20722
2016-10-04 12:45:29 -04:00
GET _tasks/task_id:1 <1>
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.
2016-03-29 09:29:21 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE
Create get task API that falls back to the .tasks index This adds a get task API that supports GET /_tasks/${taskId} and removes that responsibility from the list tasks API. The get task API supports wait_for_complation just as the list tasks API does but doesn't support any of the list task API's filters. In exchange, it supports falling back to the .results index when the task isn't running any more. Like any good GET API it 404s when it doesn't find the task. Then we change reindex, update-by-query, and delete-by-query to persist the task result when wait_for_completion=false. The leads to the neat behavior that, once you start a reindex with wait_for_completion=false, you can fetch the result of the task by using the get task API and see the result when it has finished. Also rename the .results index to .tasks.
2016-05-31 19:44:01 -04:00
// TEST[catch:missing]
<1> This will return a 404 if the task isn't found.
Or to retrieve all children of a particular task:
[source,js]
--------------------------------------------------
GET _tasks?parent_task_id=parentTaskId:1 <1>
--------------------------------------------------
// CONSOLE
<1> This won't return a 404 if the parent isn't found.
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.
2016-03-29 09:29:21 -04:00
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]
--------------------------------------------------
Generate and run tests from the docs Adds infrastructure so `gradle :docs:check` will extract tests from snippets in the documentation and execute the tests. This is included in `gradle check` so it should happen on CI and during a normal build. By default each `// AUTOSENSE` snippet creates a unique REST test. These tests are executed in a random order and the cluster is wiped between each one. If multiple snippets chain together into a test you can annotate all snippets after the first with `// TEST[continued]` to have the generated tests for both snippets joined. Snippets marked as `// TESTRESPONSE` are checked against the response of the last action. See docs/README.asciidoc for lots more. Closes #12583. That issue is about catching bugs in the docs during build. This catches *some* bugs in the docs during build which is a good start.
2016-04-29 10:42:03 -04:00
GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
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.
2016-03-29 09:29:21 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE
Create get task API that falls back to the .tasks index This adds a get task API that supports GET /_tasks/${taskId} and removes that responsibility from the list tasks API. The get task API supports wait_for_complation just as the list tasks API does but doesn't support any of the list task API's filters. In exchange, it supports falling back to the .results index when the task isn't running any more. Like any good GET API it 404s when it doesn't find the task. Then we change reindex, update-by-query, and delete-by-query to persist the task result when wait_for_completion=false. The leads to the neat behavior that, once you start a reindex with wait_for_completion=false, you can fetch the result of the task by using the get task API and see the result when it has finished. Also rename the .results index to .tasks.
2016-05-31 19:44:01 -04:00
// TEST[catch:missing]
You can also wait for all tasks for certain action types to finish. This
command will wait for all `reindex` tasks to finish:
[source,js]
--------------------------------------------------
GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
--------------------------------------------------
// CONSOLE
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.
2016-03-29 09:29:21 -04:00
Add _cat/tasks Adds new _cat endpoint that lists all tasks
2016-04-01 17:23:12 -04:00
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,js]
--------------------------------------------------
Generate and run tests from the docs Adds infrastructure so `gradle :docs:check` will extract tests from snippets in the documentation and execute the tests. This is included in `gradle check` so it should happen on CI and during a normal build. By default each `// AUTOSENSE` snippet creates a unique REST test. These tests are executed in a random order and the cluster is wiped between each one. If multiple snippets chain together into a test you can annotate all snippets after the first with `// TEST[continued]` to have the generated tests for both snippets joined. Snippets marked as `// TESTRESPONSE` are checked against the response of the last action. See docs/README.asciidoc for lots more. Closes #12583. That issue is about catching bugs in the docs during build. This catches *some* bugs in the docs during build which is a good start.
2016-04-29 10:42:03 -04:00
GET _cat/tasks
Add _cat/tasks Adds new _cat endpoint that lists all tasks
2016-04-01 17:23:12 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE
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.
2016-03-29 09:29:21 -04:00
[float]
=== Task Cancellation
If a long-running task supports cancellation, it can be cancelled by the following command:
[source,js]
--------------------------------------------------
Remove lenient URL parameter parsing Today when parsing a request, Elasticsearch silently ignores incorrect (including parameters with typos) or unused parameters. This is bad as it leads to requests having unintended behavior (e.g., if a user hits the _analyze API and misspell the "tokenizer" then Elasticsearch will just use the standard analyzer, completely against intentions). This commit removes lenient URL parameter parsing. The strategy is simple: when a request is handled and a parameter is touched, we mark it as such. Before the request is actually executed, we check to ensure that all parameters have been consumed. If there are remaining parameters yet to be consumed, we fail the request with a list of the unconsumed parameters. An exception has to be made for parameters that format the response (as opposed to controlling the request); for this case, handlers are able to provide a list of parameters that should be excluded from tripping the unconsumed parameters check because those parameters will be used in formatting the response. Additionally, some inconsistencies between the parameters in the code and in the docs are corrected. Relates #20722
2016-10-04 12:45:29 -04:00
POST _tasks/task_id:1/_cancel
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.
2016-03-29 09:29:21 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE
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.
2016-03-29 09:29:21 -04:00
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]
--------------------------------------------------
Remove lenient URL parameter parsing Today when parsing a request, Elasticsearch silently ignores incorrect (including parameters with typos) or unused parameters. This is bad as it leads to requests having unintended behavior (e.g., if a user hits the _analyze API and misspell the "tokenizer" then Elasticsearch will just use the standard analyzer, completely against intentions). This commit removes lenient URL parameter parsing. The strategy is simple: when a request is handled and a parameter is touched, we mark it as such. Before the request is actually executed, we check to ensure that all parameters have been consumed. If there are remaining parameters yet to be consumed, we fail the request with a list of the unconsumed parameters. An exception has to be made for parameters that format the response (as opposed to controlling the request); for this case, handlers are able to provide a list of parameters that should be excluded from tripping the unconsumed parameters check because those parameters will be used in formatting the response. Additionally, some inconsistencies between the parameters in the code and in the docs are corrected. Relates #20722
2016-10-04 12:45:29 -04:00
POST _tasks/_cancel?nodes=nodeId1,nodeId2&actions=*reindex
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.
2016-03-29 09:29:21 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE
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.
2016-03-29 09:29:21 -04:00
Add ability to group tasks by common parent By default, tasks are grouped by node. However, task execution in elasticsearch can be quite complex and an individual task that runs on a coordinating node can have many subtasks running on other nodes in the cluster. This commit makes it possible to list task grouped by common parents instead of by node. When this option is enabled all subtask are grouped under the coordinating node task that started all subtasks in the group. To group tasks by common parents, use the following syntax: GET /tasks?group_by=parents
2016-03-24 22:59:52 -04:00
[float]
=== Task Grouping
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.
2016-03-29 09:29:21 -04:00
Add ability to group tasks by common parent By default, tasks are grouped by node. However, task execution in elasticsearch can be quite complex and an individual task that runs on a coordinating node can have many subtasks running on other nodes in the cluster. This commit makes it possible to list task grouped by common parents instead of by node. When this option is enabled all subtask are grouped under the coordinating node task that started all subtasks in the group. To group tasks by common parents, use the following syntax: GET /tasks?group_by=parents
2016-03-24 22:59:52 -04:00
The task lists returned by task API commands can be grouped either by nodes (default) or by parent tasks using the `group_by` parameter.
The following command will change the grouping to parent tasks:
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.
2016-03-29 09:29:21 -04:00
Add ability to group tasks by common parent By default, tasks are grouped by node. However, task execution in elasticsearch can be quite complex and an individual task that runs on a coordinating node can have many subtasks running on other nodes in the cluster. This commit makes it possible to list task grouped by common parents instead of by node. When this option is enabled all subtask are grouped under the coordinating node task that started all subtasks in the group. To group tasks by common parents, use the following syntax: GET /tasks?group_by=parents
2016-03-24 22:59:52 -04:00
[source,js]
--------------------------------------------------
Generate and run tests from the docs Adds infrastructure so `gradle :docs:check` will extract tests from snippets in the documentation and execute the tests. This is included in `gradle check` so it should happen on CI and during a normal build. By default each `// AUTOSENSE` snippet creates a unique REST test. These tests are executed in a random order and the cluster is wiped between each one. If multiple snippets chain together into a test you can annotate all snippets after the first with `// TEST[continued]` to have the generated tests for both snippets joined. Snippets marked as `// TESTRESPONSE` are checked against the response of the last action. See docs/README.asciidoc for lots more. Closes #12583. That issue is about catching bugs in the docs during build. This catches *some* bugs in the docs during build which is a good start.
2016-04-29 10:42:03 -04:00
GET _tasks?group_by=parents
Add ability to group tasks by common parent By default, tasks are grouped by node. However, task execution in elasticsearch can be quite complex and an individual task that runs on a coordinating node can have many subtasks running on other nodes in the cluster. This commit makes it possible to list task grouped by common parents instead of by node. When this option is enabled all subtask are grouped under the coordinating node task that started all subtasks in the group. To group tasks by common parents, use the following syntax: GET /tasks?group_by=parents
2016-03-24 22:59:52 -04:00
--------------------------------------------------
Renamed all AUTOSENSE snippets to CONSOLE (#18210)
2016-05-09 09:42:23 -04:00
// CONSOLE