Skip to content

Commit 05e89eb

Browse files
opensearch-trigger-bot[bot]github-actions[bot]kolchfa-awsnatebower
authored
Adding rethrottle api docs (#9607) (#10257)
* Adding retrottle api docs * Apply suggestions from code review * addressing PR comments * Apply suggestions from code review --------- (cherry picked from commit f7b3288) Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> Signed-off-by: AntonEliatra <anton.rubin@eliatra.com> Signed-off-by: Nathan Bower <nbower@amazon.com> Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
1 parent 3a242a6 commit 05e89eb

File tree

1 file changed

+168
-0
lines changed

1 file changed

+168
-0
lines changed

‎_api-reference/tasks/rethrottle.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
layout: default
3+
title: Rethrottle
4+
parent: Tasks API
5+
nav_order: 40
6+
---
7+
8+
# Rethrottle
9+
10+
You can use the following APIs to dynamically change the `requests_per_second` for [`_reindex`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/), [`_update_by_query`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/update-by-query/), or [`_delete_by_query`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/delete-by-query/) operations that are already running.
11+
12+
## Endpoints
13+
14+
```json
15+
POST /_delete_by_query/{task_id}/_rethrottle
16+
POST /_reindex/{task_id}/_rethrottle
17+
POST /_update_by_query/{task_id}/_rethrottle
18+
```
19+
20+
## Path parameters
21+
22+
Parameter | Data type | Description
23+
:--- | :--- | :---
24+
`task_id` | String | The unique identifier for the running task that you want to rethrottle.
25+
26+
## Query parameters
27+
28+
Parameter | Data type | Description
29+
:--- | :--- | :---
30+
`requests_per_second` | Float | The new throttle value to apply to the task. Use `-1` to disable throttling. Optional.
31+
32+
### Example request: Rethrottle a running delete by query task
33+
34+
```json
35+
POST /_delete_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=10
36+
```
37+
{% include copy-curl.html %}
38+
39+
40+
### Example request: Rethrottle a running reindex task
41+
42+
```json
43+
POST /_reindex/<YOUR_TASK_ID>/_rethrottle?requests_per_second=20
44+
```
45+
{% include copy-curl.html %}
46+
47+
### Example request: Rethrottle a running update by query task
48+
49+
```json
50+
POST /_update_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=5
51+
```
52+
{% include copy-curl.html %}
53+
54+
## Example response
55+
56+
The following response provides details regarding the active `update_by_query` task:
57+
58+
```
59+
{
60+
"nodes": {
61+
"bvv8SKpiRhOhF9_Bu8gZ7w": {
62+
"name": "opensearch-node1",
63+
"transport_address": "172.18.0.4:9300",
64+
"host": "172.18.0.4",
65+
"ip": "172.18.0.4:9300",
66+
"roles": [
67+
"cluster_manager",
68+
"data",
69+
"ingest",
70+
"remote_cluster_client"
71+
],
72+
"attributes": {
73+
"shard_indexing_pressure_enabled": "true"
74+
},
75+
"tasks": {
76+
"bvv8SKpiRhOhF9_Bu8gZ7w:640": {
77+
"node": "bvv8SKpiRhOhF9_Bu8gZ7w",
78+
"id": 640,
79+
"type": "transport",
80+
"action": "indices:data/write/update/byquery",
81+
"status": {
82+
"total": 4785,
83+
"updated": 1000,
84+
"created": 0,
85+
"deleted": 0,
86+
"batches": 1,
87+
"version_conflicts": 0,
88+
"noops": 0,
89+
"retries": {
90+
"bulk": 0,
91+
"search": 0
92+
},
93+
"throttled_millis": 0,
94+
"requests_per_second": 50,
95+
"throttled_until_millis": 2146
96+
},
97+
"description": "update-by-query [test-rethrottle] updated with Script{type=inline, lang='painless', idOrCode='ctx._source.new_field = 'updated'', options={}, params={}}",
98+
"start_time_in_millis": 1751310547697,
99+
"running_time_in_nanos": 9567425129,
100+
"cancellable": true,
101+
"cancelled": false,
102+
"headers": {
103+
"X-Opaque-Id": "1b911516-44cd-4920-8c1e-79368ea7cdfd"
104+
},
105+
"resource_stats": {
106+
"average": {
107+
"cpu_time_in_nanos": 0,
108+
"memory_in_bytes": 0
109+
},
110+
"total": {
111+
"cpu_time_in_nanos": 0,
112+
"memory_in_bytes": 0
113+
},
114+
"min": {
115+
"cpu_time_in_nanos": 0,
116+
"memory_in_bytes": 0
117+
},
118+
"max": {
119+
"cpu_time_in_nanos": 0,
120+
"memory_in_bytes": 0
121+
},
122+
"thread_info": {
123+
"thread_executions": 0,
124+
"active_threads": 0
125+
}
126+
}
127+
}
128+
}
129+
}
130+
}
131+
}
132+
```
133+
134+
## Response body fields
135+
136+
The response provides detailed task- and node-level information about the rethrottled operation.
137+
138+
| Field | Data type | Description |
139+
| :--- | :--- | :--- |
140+
| `nodes` | Object | A map of node IDs to details about the task on each node. |
141+
| `nodes.<node_id>.name` | String | The name of the node on which the task is running. |
142+
| `nodes.<node_id>.transport_address` | String | The transport address of the node. |
143+
| `nodes.<node_id>.host` | String | The host IP address. |
144+
| `nodes.<node_id>.ip` | String | The IP address and port. |
145+
| `nodes.<node_id>.roles` | Array | The roles assigned to the node. |
146+
| `nodes.<node_id>.attributes` | Object | Node-level attributes. |
147+
| `nodes.<node_id>.tasks` | Object | A map of task IDs to detailed information about each task. |
148+
| `nodes.<node_id>.tasks.<task_id>.type` | String | The task type, such as `transport`. |
149+
| `nodes.<node_id>.tasks.<task_id>.action` | String | The specific action being performed (for example, `reindex`). |
150+
| `nodes.<node_id>.tasks.<task_id>.status` | Object | The current status of the task. |
151+
| `nodes.<node_id>.tasks.<task_id>.status.total` | Integer | The total number of documents to process. |
152+
| `nodes.<node_id>.tasks.<task_id>.status.created` | Integer | The number of documents created. |
153+
| `nodes.<node_id>.tasks.<task_id>.status.updated` | Integer | The number of documents updated. |
154+
| `nodes.<node_id>.tasks.<task_id>.status.deleted` | Integer | The number of documents deleted. |
155+
| `nodes.<node_id>.tasks.<task_id>.status.batches` | Integer | The number of batches processed. |
156+
| `nodes.<node_id>.tasks.<task_id>.status.version_conflicts` | Integer | The number of version conflicts. |
157+
| `nodes.<node_id>.tasks.<task_id>.status.noops` | Integer | The number of no-op updates. |
158+
| `nodes.<node_id>.tasks.<task_id>.status.retries` | Object | Retry stats for bulk and search operations. |
159+
| `nodes.<node_id>.tasks.<task_id>.status.requests_per_second` | Float | Current throttle rate in requests per second. |
160+
| `nodes.<node_id>.tasks.<task_id>.status.throttled_millis` | Integer | The time, in milliseconds, that the task was throttled. |
161+
| `nodes.<node_id>.tasks.<task_id>.status.throttled_until_millis` | Integer | The time, in milliseconds, that the task is expected to remain throttled. |
162+
| `nodes.<node_id>.tasks.<task_id>.description` | String | A human-readable description of the task. |
163+
| `nodes.<node_id>.tasks.<task_id>.start_time_in_millis` | Integer | The task start time in epoch milliseconds. |
164+
| `nodes.<node_id>.tasks.<task_id>.running_time_in_nanos` | Integer | The task runtime in nanoseconds. |
165+
| `nodes.<node_id>.tasks.<task_id>.cancellable` | Boolean | Whether the task can be canceled. |
166+
| `nodes.<node_id>.tasks.<task_id>.cancelled` | Boolean | Whether the task has been canceled. |
167+
| `nodes.<node_id>.tasks.<task_id>.headers` | Object | Optional HTTP headers associated with the task. |
168+
| `nodes.<node_id>.tasks.<task_id>.resource_stats` | Object | Statistics about resource usage. |

0 commit comments

Comments
 (0)