This is an automated email from the ASF dual-hosted git repository.
kfaraz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/master by this push:
new e6b3840b7a7 Docs: Add Supervisor Stats API response structure (task
group ID → task ID mapping) (#19090)
e6b3840b7a7 is described below
commit e6b3840b7a71e6e61ac3461bf2852a41432fe330
Author: Aru Raghuwanshi <[email protected]>
AuthorDate: Thu Mar 5 17:18:46 2026 +0530
Docs: Add Supervisor Stats API response structure (task group ID → task ID
mapping) (#19090)
* Docs: Document Supervisor Stats API response structure (task group ID →
task ID mapping)
* Clean-up
* Add taskGroupId and RowStatsPayload to spell check dictionary
* Use JSON structure and add real-life example for supervisor stats
response schema
* Add movingAverages to spell check dictionary
---
docs/api-reference/supervisor-api.md | 60 ++++++++++++++++++++++++++++++++++++
docs/ingestion/tasks.md | 2 ++
website/.spelling | 2 ++
3 files changed, 64 insertions(+)
diff --git a/docs/api-reference/supervisor-api.md
b/docs/api-reference/supervisor-api.md
index 20fdb37a55f..2f0d72deda1 100644
--- a/docs/api-reference/supervisor-api.md
+++ b/docs/api-reference/supervisor-api.md
@@ -1363,6 +1363,62 @@ Host: http://ROUTER_IP:ROUTER_PORT
Returns a snapshot of the current ingestion row counters for each task being
managed by the supervisor, along with moving averages for the row counters. See
[Row stats](../ingestion/tasks.md#row-stats) for more information.
+#### Response schema
+
+The response is a nested map of task group IDs to task IDs to row stats:
+
+```json
+{
+ "<taskGroupId>": {
+ "<taskId>": {
+ "movingAverages": { ... },
+ "totals": { ... }
+ }
+ }
+}
+```
+
+- **taskGroupId** (string): Supervisor task group identifier
+- **taskId** (string): Druid indexing task identifier within that group
+- **movingAverages** / **totals**: Per-task row stats; see [Row
stats](../ingestion/tasks.md#row-stats) for field definitions
+
+For example, a supervisor with two task groups:
+
+```json
+{
+ "0": {
+ "index_kafka_my_datasource_abc123": {
+ "movingAverages": {
+ "buildSegments": {
+ "5m": { "processed": 10.0, "unparseable": 0.0, "thrownAway": 0.0,
"processedWithError": 0.0 },
+ "15m": { "processed": 5.0, "unparseable": 0.0, "thrownAway": 0.0,
"processedWithError": 0.0 },
+ "1m": { "processed": 12.0, "unparseable": 0.0, "thrownAway": 0.0,
"processedWithError": 0.0 }
+ }
+ },
+ "totals": {
+ "buildSegments": { "processed": 2000, "processedWithError": 0,
"thrownAway": 0, "unparseable": 0 }
+ }
+ }
+ },
+ "1": {
+ "index_kafka_my_datasource_def456": {
+ "movingAverages": {
+ "buildSegments": {
+ "5m": { "processed": 8.0, "unparseable": 0.0, "thrownAway": 0.0,
"processedWithError": 0.0 },
+ "15m": { "processed": 4.0, "unparseable": 0.0, "thrownAway": 0.0,
"processedWithError": 0.0 },
+ "1m": { "processed": 9.0, "unparseable": 0.0, "thrownAway": 0.0,
"processedWithError": 0.0 }
+ }
+ },
+ "totals": {
+ "buildSegments": { "processed": 1500, "processedWithError": 0,
"thrownAway": 0, "unparseable": 0 }
+ }
+ }
+ }
+}
+```
+
+In this example, `"0"` and `"1"` are task group IDs, and
`index_kafka_my_datasource_abc123` and `index_kafka_my_datasource_def456` are
task IDs.
+
#### URL
`GET` `/druid/indexer/v1/supervisor/{supervisorId}/stats`
@@ -1414,6 +1470,8 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
+In the example below, the outer key (`"0"`) is a **task group ID**; the inner
key (e.g., `index_kafka_custom_data_881d621078f6b7c_ccplchbi`) is a **task ID**.
+
<details>
<summary>View the response</summary>
@@ -1461,6 +1519,8 @@ Host: http://ROUTER_IP:ROUTER_PORT
```
</details>
+**For automation clients:** If you need to map task IDs to group IDs (for
handoff, draining, or observability), use the `/stats` response keys directly
instead of re-deriving group IDs from partition data. This avoids coupling to
internal supervisor assignment logic.
+
## Audit history
An audit history provides a comprehensive log of events, including supervisor
configuration, creation, suspension, and modification history.
diff --git a/docs/ingestion/tasks.md b/docs/ingestion/tasks.md
index d22e6e8f7c2..94381b48743 100644
--- a/docs/ingestion/tasks.md
+++ b/docs/ingestion/tasks.md
@@ -314,6 +314,8 @@ For the Kafka Indexing Service, a GET to the following
Overlord API will retriev
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/supervisor/{supervisorId}/stats
```
+The response is structured as a nested map: outer keys are **task group IDs**,
inner keys are **task IDs**, and each task maps to its row stats payload. See
the [Supervisor API](../api-reference/supervisor-api.md) for the full schema
and guidance for automation clients.
+
### Unparseable events
Lists of recently-encountered unparseable events can be retrieved from a
running task with a GET to the following Peon API:
diff --git a/website/.spelling b/website/.spelling
index 8bab890e6cf..309eddb1777 100644
--- a/website/.spelling
+++ b/website/.spelling
@@ -759,6 +759,8 @@ granularity_string
QueryKit
# MSQ report fields
taskId
+taskGroupId
+movingAverages
multiStageQuery.taskId
multiStageQuery.payload.status
multiStageQuery.payload.status.status
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
