Add thread level details to _tasks API (#4542)

* Add thread level details to _tasks API Signed-off-by: Jay Deng <[email protected]> * Rewording according to style guide and formatting changes Signed-off-by: Fanit Kolchina <[email protected]> * Update _api-reference/tasks.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> * Update tasks.md Signed-off-by: kolchfa-aws <[email protected]> --------- Signed-off-by: Jay Deng <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Jul 14, 2023 · a7da897 · a7da897
1 parent 5722fea
commit a7da897
Showing 1 changed file with 40 additions and 8 deletions.
diff --git a/_api-reference/tasks.md b/_api-reference/tasks.md
@@ -28,7 +28,7 @@ GET _tasks/<task_id>
 
 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 %}
+{% include copy.html %}