mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-01 16:39:11 +00:00
4b1c116461
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.
122 lines
4.0 KiB
Plaintext
122 lines
4.0 KiB
Plaintext
[[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]
|
|
--------------------------------------------------
|
|
GET _tasks <1>
|
|
GET _tasks?nodes=nodeId1,nodeId2 <2>
|
|
GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
<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" : {
|
|
"name" : "Tamara Rahn",
|
|
"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,
|
|
"cancellable" : false,
|
|
"parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
|
|
},
|
|
"oTUltX4IQMOUUVeiohTt8A:123" : {
|
|
"node" : "oTUltX4IQMOUUVeiohTt8A",
|
|
"id" : 123,
|
|
"type" : "transport",
|
|
"action" : "cluster:monitor/tasks/lists",
|
|
"start_time_in_millis" : 1458585884904,
|
|
"running_time_in_nanos" : 236042,
|
|
"cancellable" : false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
It is also possible to retrieve information for a particular task, or all children of a particular
|
|
tasks using the following two commands:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks/taskId:1
|
|
GET _tasks?parent_task_id=parentTaskId:1
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
GET _cat/tasks
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
[float]
|
|
=== Task Cancellation
|
|
|
|
If a long-running task supports cancellation, it can be cancelled by the following command:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _tasks/taskId:1/_cancel
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
POST _tasks/_cancel?node_id=nodeId1,nodeId2&actions=*reindex
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
|
|
[float]
|
|
=== Task Grouping
|
|
|
|
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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET _tasks?group_by=parents
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|