Task Queue Statistics (#414)

* Including `approximate_backlog_counter` in Request/Response protos (#395)

* Including approximate_backlog_counter in Request/Response protos

* addressed comments

* fixed ci error

* fixed the jq error locally, maybe causing CI to fail

* Updated TaskQueueTypeInfo to have BacklogInfo (#396)

* Update DescribeTaskQueueResponse to remove BacklogInfo (#397)

* Removed BacklogInfo from DescribeTaskQueueResponse

* ran make

* Rename BacklogInfo to TaskQueueStats (#411)

* corrected tag number

* Updated docstrings

* Fixed lint complains

---------

Co-authored-by: Shahab Tajik <[email protected]>

Author: Shivs11

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "proto/api"]
+	url = ../api
+	branch = shivam/backlog-count

openapi/openapiv2.json

@@ -1195,9 +1195,16 @@
             },
             "collectionFormat": "multi"
           },
+          {
+            "name": "reportStats",
+            "description": "Report stats for the requested task queue types and versions",
+            "in": "query",
+            "required": false,
+            "type": "boolean"
+          },
           {
             "name": "reportPollers",
-            "description": "Report backlog info for the requested task queue types and versions\nbool report_backlog_info = 8;\nReport list of pollers for requested task queue types and versions",
+            "description": "Report list of pollers for requested task queue types and versions",
             "in": "query",
             "required": false,
             "type": "boolean"
@@ -8314,6 +8321,31 @@
       },
       "description": "Reachability of tasks for a worker on a single task queue."
     },
+    "v1TaskQueueStats": {
+      "type": "object",
+      "properties": {
+        "approximateBacklogCount": {
+          "type": "string",
+          "format": "int64",
+          "description": "The approximate number of tasks backlogged in this task queue. May count expired tasks but eventually converges\nto the right value."
+        },
+        "approximateBacklogAge": {
+          "type": "string",
+          "description": "Approximate age of the oldest task in the backlog based on the create timestamp of the task at the head of the queue."
+        },
+        "tasksAddRate": {
+          "type": "number",
+          "format": "float",
+          "description": "Approximate tasks per second added to the task queue based on activity within a fixed window. This includes both backlogged and\nsync-matched tasks."
+        },
+        "tasksDispatchRate": {
+          "type": "number",
+          "format": "float",
+          "description": "Approximate tasks per second dispatched to workers based on activity within a fixed window. This includes both backlogged and\nsync-matched tasks."
+        }
+      },
+      "description": "For workflow task queues, we only report the normal queue stats, not sticky queues. This means the stats\nreported here do not count all workflow tasks. However, because the tasks queued in sticky queues only remain\nvalid for a few seconds, the inaccuracy becomes less significant as the backlog age grows."
+    },
     "v1TaskQueueStatus": {
       "type": "object",
       "properties": {
@@ -8360,6 +8392,9 @@
             "$ref": "#/definitions/v1PollerInfo"
           },
           "description": "Unversioned workers (with `useVersioning=false`) are reported in unversioned result even if they set a Build ID."
+        },
+        "stats": {
+          "$ref": "#/definitions/v1TaskQueueStats"
         }
       }
     },

openapi/openapiv3.yaml

@@ -1066,12 +1066,14 @@ paths:
                 - TASK_QUEUE_TYPE_NEXUS
               type: string
               format: enum
+        - name: reportStats
+          in: query
+          description: Report stats for the requested task queue types and versions
+          schema:
+            type: boolean
         - name: reportPollers
           in: query
-          description: |-
-            Report backlog info for the requested task queue types and versions
-             bool report_backlog_info = 8;
-             Report list of pollers for requested task queue types and versions
+          description: Report list of pollers for requested task queue types and versions
           schema:
             type: boolean
         - name: reportTaskReachability
@@ -6121,6 +6123,34 @@ components:
              See the TaskReachability docstring for information about each enum variant.
              If reachability is empty, this worker is considered unreachable in this task queue.
       description: Reachability of tasks for a worker on a single task queue.
+    TaskQueueStats:
+      type: object
+      properties:
+        approximateBacklogCount:
+          type: string
+          description: |-
+            The approximate number of tasks backlogged in this task queue. May count expired tasks but eventually converges
+             to the right value.
+        approximateBacklogAge:
+          pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
+          type: string
+          description: Approximate age of the oldest task in the backlog based on the create timestamp of the task at the head of the queue.
+        tasksAddRate:
+          type: number
+          description: |-
+            Approximate tasks per second added to the task queue based on activity within a fixed window. This includes both backlogged and
+             sync-matched tasks.
+          format: float
+        tasksDispatchRate:
+          type: number
+          description: |-
+            Approximate tasks per second dispatched to workers based on activity within a fixed window. This includes both backlogged and
+             sync-matched tasks.
+          format: float
+      description: |-
+        For workflow task queues, we only report the normal queue stats, not sticky queues. This means the stats
+         reported here do not count all workflow tasks. However, because the tasks queued in sticky queues only remain
+         valid for a few seconds, the inaccuracy becomes less significant as the backlog age grows.
     TaskQueueStatus:
       type: object
       properties:
@@ -6144,6 +6174,8 @@ components:
           items:
             $ref: '#/components/schemas/PollerInfo'
           description: Unversioned workers (with `useVersioning=false`) are reported in unversioned result even if they set a Build ID.
+        stats:
+          $ref: '#/components/schemas/TaskQueueStats'
     TaskQueueVersionInfo:
       type: object
       properties:

temporal/api/taskqueue/v1/message.proto

@@ -84,6 +84,24 @@ message TaskQueueVersionInfo {
 message TaskQueueTypeInfo {
     // Unversioned workers (with `useVersioning=false`) are reported in unversioned result even if they set a Build ID.
     repeated PollerInfo pollers = 1;
+    TaskQueueStats stats = 2;
+}
+
+// For workflow task queues, we only report the normal queue stats, not sticky queues. This means the stats
+// reported here do not count all workflow tasks. However, because the tasks queued in sticky queues only remain
+// valid for a few seconds, the inaccuracy becomes less significant as the backlog age grows.
+message TaskQueueStats {
+    // The approximate number of tasks backlogged in this task queue. May count expired tasks but eventually converges
+    // to the right value.
+    int64 approximate_backlog_count = 1;
+    // Approximate age of the oldest task in the backlog based on the create timestamp of the task at the head of the queue.
+    google.protobuf.Duration approximate_backlog_age = 2;
+    // Approximate tasks per second added to the task queue based on activity within a fixed window. This includes both backlogged and
+    // sync-matched tasks.
+    float tasks_add_rate = 3;
+    // Approximate tasks per second dispatched to workers based on activity within a fixed window. This includes both backlogged and
+    // sync-matched tasks.
+    float tasks_dispatch_rate = 4;
 }
 
 // Deprecated. Use `InternalTaskQueueStatus`. This is kept until `DescribeTaskQueue` supports legacy behavior.

temporal/api/workflowservice/v1/request_response.proto

@@ -919,8 +919,8 @@ message DescribeTaskQueueRequest {
 
     // Task queue types to report info about. If not specified, all types are considered.
     repeated temporal.api.enums.v1.TaskQueueType task_queue_types = 7;
-    // Report backlog info for the requested task queue types and versions
-    // bool report_backlog_info = 8;
+    // Report stats for the requested task queue types and versions
+    bool report_stats = 8;
     // Report list of pollers for requested task queue types and versions
     bool report_pollers = 9;
     // Report task reachability for the requested versions and all task types (task reachability is not reported