diff --git a/_api-reference/tasks.md b/_api-reference/tasks.md index fd8099bc..72f88f0f 100644 --- a/_api-reference/tasks.md +++ b/_api-reference/tasks.md @@ -28,7 +28,7 @@ GET _tasks/ Note that if a task finishes running, it won't be returned as part of your request. For an example of a task that takes a little longer to finish, you can run the [`_reindex`]({{site.url}}{{site.baseurl}}/opensearch/reindex-data) API operation on a larger document, and then run `tasks`. -**Sample Response** +#### Example response ```json { "nodes": { @@ -93,18 +93,18 @@ Parameter | Data type | Description | `wait_for_completion` | Boolean | Waits for the matching tasks to complete. (Default: false) `group_by` | Enum | Groups tasks by parent/child relationships or nodes. (Default: nodes) `timeout` | Time | An explicit operation timeout. (Default: 30 seconds) -`master_timeout` | Time | The time to wait for a connection to the primary node. (Default: 30 seconds) +`cluster_manager_timeout` | Time | The time to wait for a connection to the primary node. (Default: 30 seconds) For example, this request returns tasks currently running on a node named `opensearch-node1`: -**Sample Request** +#### Example request -``` +```json GET /_tasks?nodes=opensearch-node1 ``` {% include copy-curl.html %} -**Sample Response** +#### Example response ```json { @@ -150,14 +150,14 @@ GET /_tasks?nodes=opensearch-node1 The following request returns detailed information about active search tasks: -**Sample Request** +#### Example request ```bash curl -XGET "localhost:9200/_tasks?actions=*search&detailed ``` {% include copy.html %} -**Sample Response** +#### Example response ```json { @@ -190,9 +190,25 @@ curl -XGET "localhost:9200/_tasks?actions=*search&detailed "cancelled" : false, "headers" : { }, "resource_stats" : { + "average" : { + "cpu_time_in_nanos" : 0, + "memory_in_bytes" : 0 + }, "total" : { "cpu_time_in_nanos" : 0, "memory_in_bytes" : 0 + }, + "min" : { + "cpu_time_in_nanos" : 0, + "memory_in_bytes" : 0 + }, + "max" : { + "cpu_time_in_nanos" : 0, + "memory_in_bytes" : 0 + }, + "thread_info" : { + "thread_executions" : 0, + "active_threads" : 0 } } } @@ -203,6 +219,22 @@ curl -XGET "localhost:9200/_tasks?actions=*search&detailed ``` +### The `resource_stats` object + +The `resource_stats` object is only updated for tasks that support resource tracking. These stats are computed based on scheduled thread executions, including both threads that have finished working on the task and threads currently working on the task. Because the same thread may be scheduled to work on the same task multiple times, each instance of a given thread being scheduled to work on a given task is considered to be a single thread execution. + +The following table lists all response fields in the `resource_stats` object. + +Response field | Description | +:--- | :--- | +`average` | The average resource usage across all scheduled thread executions. | +`total` | The sum of resource usages across all scheduled thread executions. | +`min` | The minimum resource usage across all scheduled thread executions. | +`max` | The maximum resource usage across all scheduled thread executions. | +`thread_info` | Thread-count-related stats.| +`thread_info.active_threads` | The number of threads currently working on the task. | +`thread_info.thread_executions` | The number of threads that have been scheduled to work on the task. | + ## Task canceling After getting a list of tasks, you can cancel all cancelable tasks with the following request: @@ -296,4 +328,4 @@ This operation supports the same parameters as the `tasks` operation. The follow ```bash curl -i -H "X-Opaque-Id: 123456" "https://localhost:9200/_tasks?nodes=opensearch-node1" -u 'admin:admin' --insecure ``` -{% include copy.html %} \ No newline at end of file +{% include copy.html %}