Making tq stats visible from cli

temporalcli/commands.gen.go

@@ -1539,11 +1539,11 @@ func NewTemporalTaskQueueDescribeCommand(cctx *CommandContext, parent *TemporalT
 	s.Parent = parent
 	s.Command.DisableFlagsInUseLine = true
 	s.Command.Use = "describe [flags]"
-	s.Command.Short = "Provides task reachability and pollers information for Workers on this Task Queue."
+	s.Command.Short = "Provides pollers information, backlog statistics, and task reachability (experimental) for Workers on this Task Queue."
 	if hasHighlighting {
-		s.Command.Long = "The \x1b[1mtemporal task-queue describe\x1b[0m command provides task reachability information for the requested versions and all task types,\nwhich can be used to safely retire Workers with old code versions, provided that they were assigned a Build ID.\n\nThe reachability states of a Build ID are:\n    - \x1b[1mReachable\x1b[0m: the Build ID may be used by new workflows or activities\n(based on versioning rules), or there are open workflows or backlogged activities assigned to it.\n    - \x1b[1mClosedWorkflowsOnly\x1b[0m: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period.\n    - \x1b[1mUnreachable\x1b[0m: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period.\n\nTask reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example, \x1b[1mReachable\x1b[0m is more conservative than \x1b[1mClosedWorkflowsOnly\x1b[0m.\n\nThere is a non-trivial cost of computing task reachability, use the flag \x1b[1m--report-reachability\x1b[0m to enable it.\n\nThis command also provides poller\ninformation for a given Task Queue.\n\nThe Server records the last time of each poll request. A \x1b[1mLastAccessTime\x1b[0m value\nin excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the\nWorker has shut down. Workers are removed if 5 minutes have passed since the last poll\nrequest.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\nUse the options listed below to modify what this command returns.\n\nNote that without a \x1b[1m--select-*\x1b[0m option the result for the default Build ID will be returned.\nThe default Build ID is the one mentioned in the first unconditional Assignment Rule.\nIf there is no default Build ID, the result for the unversioned queue will be returned."
+		s.Command.Long = "The \x1b[1mtemporal task-queue describe\x1b[0m command provides poller information, backlog statistics and task reachability (experimental) \ninformation for the requested versions and all task types, which can be used to safely retire Workers with old code versions, \nprovided that they were assigned a Build ID.\n\nThis command provides poller information for a given Task Queue\nin the following manner:\n\nThe Server records the last time of each poll request. A \x1b[1mLastAccessTime\x1b[0m value\nin excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the\nWorker has shut down. Workers are removed if 5 minutes have passed since the last poll\nrequest.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\nThis command provides the following task queue statistics for better worker fleet management:\n    - \x1b[1mApproximateBacklogCount\x1b[0m: The approximate number of tasks backlogged in this task queue. \nMay count expired tasks but eventually converges to the right value.\n    - \x1b[1mApproximateBacklogAge\x1b[0m: Approximate age of the oldest task in the backlog based on the creation time of \nthe task at the head of the queue, measured in seconds.\n    - \x1b[1mTasksAddRate\x1b[0m: Approximate tasks per second added to the task queue, averaging over the last 30 seconds.\nIncludes tasks whether or not they were added from the backlog or those that were dispatched immediately without\ngoing to the backlog (sync-matched).\n    - \x1b[1mTasksDispatchRate\x1b[0m: Approximate tasks per second dispatched to the task queue, averaging over the last 30 seconds.\nIncludes tasks whether or not they were dispatched from the backlog or those that were dispatched immediately without\ngoing to the backlog (sync-matched).\n    -  \x1b[1mBacklog Increase Rate\x1b[0m: Approximate net tasks per second added to the backlog, averaging the last 30 seconds.\nThis is calculated as \x1b[1mTasksAddRate\x1b[0m - \x1b[1mTasksDispatchRate\x1b[0m.\n\nThe reachability states of a Build ID are:\n    - \x1b[1mReachable\x1b[0m: the Build ID may be used by new workflows or activities\n(based on versioning rules), or there are open workflows or backlogged activities assigned to it.\n    - \x1b[1mClosedWorkflowsOnly\x1b[0m: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period.\n    - \x1b[1mUnreachable\x1b[0m: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period.\n\nTask reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example, \x1b[1mReachable\x1b[0m is more conservative than \x1b[1mClosedWorkflowsOnly\x1b[0m.\n\nThere is a non-trivial cost of computing task reachability, use the flag \x1b[1m--report-reachability\x1b[0m to enable it.\n\n\nUse the options listed below to modify what this command returns.\n\nNote that without a \x1b[1m--select-*\x1b[0m option the result for the default Build ID will be returned.\nThe default Build ID is the one mentioned in the first unconditional Assignment Rule.\nIf there is no default Build ID, the result for the unversioned queue will be returned."
 	} else {
-		s.Command.Long = "The `temporal task-queue describe` command provides task reachability information for the requested versions and all task types,\nwhich can be used to safely retire Workers with old code versions, provided that they were assigned a Build ID.\n\nThe reachability states of a Build ID are:\n    - `Reachable`: the Build ID may be used by new workflows or activities\n(based on versioning rules), or there are open workflows or backlogged activities assigned to it.\n    - `ClosedWorkflowsOnly`: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period.\n    - `Unreachable`: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period.\n\nTask reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example, `Reachable` is more conservative than `ClosedWorkflowsOnly`.\n\nThere is a non-trivial cost of computing task reachability, use the flag `--report-reachability` to enable it.\n\nThis command also provides poller\ninformation for a given Task Queue.\n\nThe Server records the last time of each poll request. A `LastAccessTime` value\nin excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the\nWorker has shut down. Workers are removed if 5 minutes have passed since the last poll\nrequest.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\nUse the options listed below to modify what this command returns.\n\nNote that without a `--select-*` option the result for the default Build ID will be returned.\nThe default Build ID is the one mentioned in the first unconditional Assignment Rule.\nIf there is no default Build ID, the result for the unversioned queue will be returned."
+		s.Command.Long = "The `temporal task-queue describe` command provides poller information, backlog statistics and task reachability (experimental) \ninformation for the requested versions and all task types, which can be used to safely retire Workers with old code versions, \nprovided that they were assigned a Build ID.\n\nThis command provides poller information for a given Task Queue\nin the following manner:\n\nThe Server records the last time of each poll request. A `LastAccessTime` value\nin excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the\nWorker has shut down. Workers are removed if 5 minutes have passed since the last poll\nrequest.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\nThis command provides the following task queue statistics for better worker fleet management:\n    - `ApproximateBacklogCount`: The approximate number of tasks backlogged in this task queue. \nMay count expired tasks but eventually converges to the right value.\n    - `ApproximateBacklogAge`: Approximate age of the oldest task in the backlog based on the creation time of \nthe task at the head of the queue, measured in seconds.\n    - `TasksAddRate`: Approximate tasks per second added to the task queue, averaging over the last 30 seconds.\nIncludes tasks whether or not they were added from the backlog or those that were dispatched immediately without\ngoing to the backlog (sync-matched).\n    - `TasksDispatchRate`: Approximate tasks per second dispatched to the task queue, averaging over the last 30 seconds.\nIncludes tasks whether or not they were dispatched from the backlog or those that were dispatched immediately without\ngoing to the backlog (sync-matched).\n    -  `Backlog Increase Rate`: Approximate net tasks per second added to the backlog, averaging the last 30 seconds.\nThis is calculated as `TasksAddRate` - `TasksDispatchRate`.\n\nThe reachability states of a Build ID are:\n    - `Reachable`: the Build ID may be used by new workflows or activities\n(based on versioning rules), or there are open workflows or backlogged activities assigned to it.\n    - `ClosedWorkflowsOnly`: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period.\n    - `Unreachable`: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period.\n\nTask reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example, `Reachable` is more conservative than `ClosedWorkflowsOnly`.\n\nThere is a non-trivial cost of computing task reachability, use the flag `--report-reachability` to enable it.\n\n\nUse the options listed below to modify what this command returns.\n\nNote that without a `--select-*` option the result for the default Build ID will be returned.\nThe default Build ID is the one mentioned in the first unconditional Assignment Rule.\nIf there is no default Build ID, the result for the unversioned queue will be returned."
 	}
 	s.Command.Args = cobra.NoArgs
 	s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name. Required.")

temporalcli/commandsmd/commands.md

@@ -721,10 +721,35 @@ Queue command, run `temporal task-queue [command] [command options]`.
 
 Includes options set for [client](#options-set-for-client).
 
-### temporal task-queue describe: Provides task reachability and pollers information for Workers on this Task Queue.
+### temporal task-queue describe: Provides pollers information, backlog statistics, and task reachability (experimental) for Workers on this Task Queue.
 
-The `temporal task-queue describe` command provides task reachability information for the requested versions and all task types,
-which can be used to safely retire Workers with old code versions, provided that they were assigned a Build ID.
+The `temporal task-queue describe` command provides poller information, backlog statistics and task reachability (experimental) 
+information for the requested versions and all task types, which can be used to safely retire Workers with old code versions, 
+provided that they were assigned a Build ID.
+
+This command provides [poller](/application-development/worker-performance#poller-count) information for a given [Task Queue](/concepts/what-is-a-task-queue)
+in the following manner:
+
+The [Server](/concepts/what-is-the-temporal-server) records the last time of each poll request. A `LastAccessTime` value
+in excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the
+Worker has shut down. [Workers](/concepts/what-is-a-worker) are removed if 5 minutes have passed since the last poll
+request.
+
+Information about the Task Queue can be returned to troubleshoot server issues.
+
+This command provides the following task queue statistics for better worker fleet management:
+    - `ApproximateBacklogCount`: The approximate number of tasks backlogged in this task queue. 
+May count expired tasks but eventually converges to the right value.
+    - `ApproximateBacklogAge`: Approximate age of the oldest task in the backlog based on the creation time of 
+the task at the head of the queue, measured in seconds.
+    - `TasksAddRate`: Approximate tasks per second added to the task queue, averaging over the last 30 seconds.
+Includes tasks whether or not they were added from the backlog or those that were dispatched immediately without
+going to the backlog (sync-matched).
+    - `TasksDispatchRate`: Approximate tasks per second dispatched to the task queue, averaging over the last 30 seconds.
+Includes tasks whether or not they were dispatched from the backlog or those that were dispatched immediately without
+going to the backlog (sync-matched).
+    -  `Backlog Increase Rate`: Approximate net tasks per second added to the backlog, averaging the last 30 seconds.
+This is calculated as `TasksAddRate` - `TasksDispatchRate`.
 
 The reachability states of a Build ID are:
     - `Reachable`: the Build ID may be used by new workflows or activities
@@ -738,15 +763,6 @@ For example, `Reachable` is more conservative than `ClosedWorkflowsOnly`.
 
 There is a non-trivial cost of computing task reachability, use the flag `--report-reachability` to enable it.
 
-This command also provides [poller](/application-development/worker-performance#poller-count)
-information for a given [Task Queue](/concepts/what-is-a-task-queue).
-
-The [Server](/concepts/what-is-the-temporal-server) records the last time of each poll request. A `LastAccessTime` value
-in excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the
-Worker has shut down. [Workers](/concepts/what-is-a-worker) are removed if 5 minutes have passed since the last poll
-request.
-
-Information about the Task Queue can be returned to troubleshoot server issues.
 
 Use the options listed below to modify what this command returns.