Cleanup temporal task-queue describe help (#668)

Fixup some inaccuracies and typos in the help output.

Co-authored-by: Josh Berry <josh.berry@temporal.io>

Author: Shivs11

temporalcli/commands.gen.go

@@ -1585,9 +1585,9 @@ func NewTemporalTaskQueueDescribeCommand(cctx *CommandContext, parent *TemporalT
 	s.Command.Use = "describe [flags]"
 	s.Command.Short = "Show active Workers"
 	if hasHighlighting {
-		s.Command.Long = "Display a list of active Workers that have recently polled a Task Queue. The\nTemporal Server records each poll request time. A \x1b[1mLastAccessTime\x1b[0m over one\nminute may indicate the Worker is at capacity or has shut down. Temporal\nWorkers are removed if 5 minutes have passed since the last poll request.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\n\x1b[1mtemporal task-queue describe \\\n   --task-queue YourTaskQueue\x1b[0m\n\nThis command provides poller information for a given Task Queue.\nWorkflow and Activity polling use separate Task Queues:\n\n\x1b[1mtemporal task-queue describe \\\n    --task-queue YourTaskQueue \\\n    --task-queue-type \"activity\"\x1b[1m\x1b[0m\n\nThis command provides the following task queue statistics:\n- \x1b[0mApproximateBacklogCount\x1b[1m: The approximate number of tasks backlogged in this\n  task queue.  May count expired tasks but eventually converges to the right\n  value.\n- \x1b[0mApproximateBacklogAge\x1b[1m: How far \"behind\" the task queue is running. This is\n  the difference in age between the oldest and newest tasks in the backlog,\n  measured in seconds.\n- \x1b[0mTasksAddRate\x1b[1m: Approximate rate at which tasks are being added to the task\n  queue, measured in tasks per second, averaged over the last 30 seconds.\n  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog.\n- \x1b[0mTasksDispatchRate\x1b[1m: Approximate rate at which tasks are being dispatched from\n  the task queue, measured in tasks per second, averaged over the last 30\n  seconds.  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog.\n- \x1b[0mBacklog Increase Rate\x1b[1m: Approximate rate at which the backlog size is\n  increasing (if positive) or decreasing (if negative), measured in tasks per\n  second, averaged over the last 30 seconds.  This is equivalent to:\n  \x1b[0mTasksAddRate\x1b[1m - \x1b[0mTasksDispatchRate\x1b[1m.\n\nSafely retire Workers assigned a Build ID by checking reachability across\nall task types. Use the flag \x1b[0m--report-reachability\x1b[1m:\n\n\x1b[1mtemporal task-queue describe \\\n   --task-queue YourTaskQueue \\\n   --build-id \"YourBuildId\" \\\n   --report-reachability\x1b[0m\n\nTask reachability information is returned for the requested versions and all\ntask types, which can be used to safely retire Workers with old code versions,\nprovided that they were assigned a Build ID.\n\nNote that task reachability status is experimental and may significantly change\nor be removed in a future release. Also, determining task reachability incurs a\nnon-trivial computing cost.\n\nTask reachability states are reported per build ID. The state may be one of the\nfollowing:\n\n- \x1b[0mReachable\x1b[1m: using the current versioning rules, the Build ID may be used\n   by new Workflow Executions or Activities OR there are currently open\n   Workflow or backlogged Activity tasks assigned to the queue.\n- \x1b[0mClosedWorkflowsOnly\x1b[1m: the Build ID does not have open Workflow Executions\n   and can't be reached by new Workflow Executions. It MAY have closed\n   Workflow Executions within the Namespace retention period.\n- \x1b[0mUnreachable\x1b[1m: this Build ID is not used for new Workflow Executions and\n  isn't used by any existing Workflow Execution within the retention period.\n\nTask reachability is eventually consistent. You may experience a delay until\nreachability converges to the most accurate value. This is designed to act\nin the most conservative way until convergence. For example, \x1b[0mReachable\x1b[1m is\nmore conservative than \x1b[0mClosedWorkflowsOnly`."
+		s.Command.Long = "Display a list of active Workers that have recently polled a Task Queue. The\nTemporal Server records each poll request time. A \x1b[1mLastAccessTime\x1b[0m over one\nminute may indicate the Worker is at capacity or has shut down. Temporal\nWorkers are removed if 5 minutes have passed since the last poll request.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\n\x1b[1mtemporal task-queue describe \\\n   --task-queue YourTaskQueue\x1b[0m\n\nThis command provides poller information for a given Task Queue.\nWorkflow and Activity polling use separate Task Queues:\n\n\x1b[1mtemporal task-queue describe \\\n    --task-queue YourTaskQueue \\\n    --task-queue-type \"activity\"\x1b[0m\n\nThis command provides the following task queue statistics:\n- \x1b[1mApproximateBacklogCount\x1b[0m: The approximate number of tasks backlogged in this\n  task queue. May count expired tasks but eventually converges to the right\n  value.\n- \x1b[1mApproximateBacklogAge\x1b[0m: Approximate age of the oldest task in the backlog,\n  based on its creation time, measured in seconds.\n- \x1b[1mTasksAddRate\x1b[0m: Approximate rate at which tasks are being added to the task\n  queue, measured in tasks per second, averaged over the last 30 seconds.\n  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog. (See note below.)\n- \x1b[1mTasksDispatchRate\x1b[0m: Approximate rate at which tasks are being dispatched from\n  the task queue, measured in tasks per second, averaged over the last 30\n  seconds.  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog. (See note below.)\n- \x1b[1mBacklog Increase Rate\x1b[0m: Approximate rate at which the backlog size is\n  increasing (if positive) or decreasing (if negative), measured in tasks per\n  second, averaged over the last 30 seconds.  This is equivalent to:\n  \x1b[1mTasksAddRate\x1b[0m - \x1b[1mTasksDispatchRate\x1b[0m.\n\nNOTE: The \x1b[1mTasksAddRate\x1b[0m and \x1b[1mTasksDispatchRate\x1b[0m metrics may differ from the\nactual rate of add/dispatch, because tasks may be dispatched eagerly to an\navailable worker, or may apply only to specific workers (they are \"sticky\").\nSuch tasks are not counted by these metrics.\n\nSafely retire Workers assigned a Build ID by checking reachability across\nall task types. Use the flag \x1b[1m--report-reachability\x1b[0m:\n\n\x1b[1mtemporal task-queue describe \\\n   --task-queue YourTaskQueue \\\n   --build-id \"YourBuildId\" \\\n   --report-reachability\x1b[0m\n\nTask reachability information is returned for the requested versions and all\ntask types, which can be used to safely retire Workers with old code versions,\nprovided that they were assigned a Build ID.\n\nNote that task reachability status is experimental and may significantly change\nor be removed in a future release. Also, determining task reachability incurs a\nnon-trivial computing cost.\n\nTask reachability states are reported per build ID. The state may be one of the\nfollowing:\n\n- \x1b[1mReachable\x1b[0m: using the current versioning rules, the Build ID may be used\n  by new Workflow Executions or Activities OR there are currently open\n  Workflow or backlogged Activity tasks assigned to the queue.\n- \x1b[1mClosedWorkflowsOnly\x1b[0m: the Build ID does not have open Workflow Executions\n  and can't be reached by new Workflow Executions. It MAY have closed\n  Workflow Executions within the Namespace retention period.\n- \x1b[1mUnreachable\x1b[0m: this Build ID is not used for new Workflow Executions and\n  isn't used by any existing Workflow Execution within the retention period.\n\nTask reachability is eventually consistent. You may experience a delay until\nreachability converges to the most accurate value. This is designed to act\nin the most conservative way until convergence. For example, \x1b[1mReachable\x1b[0m is\nmore conservative than \x1b[1mClosedWorkflowsOnly\x1b[0m."
 	} else {
-		s.Command.Long = "Display a list of active Workers that have recently polled a Task Queue. The\nTemporal Server records each poll request time. A `LastAccessTime` over one\nminute may indicate the Worker is at capacity or has shut down. Temporal\nWorkers are removed if 5 minutes have passed since the last poll request.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\n```\ntemporal task-queue describe \\\n   --task-queue YourTaskQueue\n```\n\nThis command provides poller information for a given Task Queue.\nWorkflow and Activity polling use separate Task Queues:\n\n```\ntemporal task-queue describe \\\n    --task-queue YourTaskQueue \\\n    --task-queue-type \"activity\"`\n```\n\nThis command provides the following task queue statistics:\n- `ApproximateBacklogCount`: The approximate number of tasks backlogged in this\n  task queue.  May count expired tasks but eventually converges to the right\n  value.\n- `ApproximateBacklogAge`: How far \"behind\" the task queue is running. This is\n  the difference in age between the oldest and newest tasks in the backlog,\n  measured in seconds.\n- `TasksAddRate`: Approximate rate at which tasks are being added to the task\n  queue, measured in tasks per second, averaged over the last 30 seconds.\n  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog.\n- `TasksDispatchRate`: Approximate rate at which tasks are being dispatched from\n  the task queue, measured in tasks per second, averaged over the last 30\n  seconds.  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog.\n- `Backlog Increase Rate`: Approximate rate at which the backlog size is\n  increasing (if positive) or decreasing (if negative), measured in tasks per\n  second, averaged over the last 30 seconds.  This is equivalent to:\n  `TasksAddRate` - `TasksDispatchRate`.\n\nSafely retire Workers assigned a Build ID by checking reachability across\nall task types. Use the flag `--report-reachability`:\n\n```\ntemporal task-queue describe \\\n   --task-queue YourTaskQueue \\\n   --build-id \"YourBuildId\" \\\n   --report-reachability\n```\n\nTask reachability information is returned for the requested versions and all\ntask types, which can be used to safely retire Workers with old code versions,\nprovided that they were assigned a Build ID.\n\nNote that task reachability status is experimental and may significantly change\nor be removed in a future release. Also, determining task reachability incurs a\nnon-trivial computing cost.\n\nTask reachability states are reported per build ID. The state may be one of the\nfollowing:\n\n- `Reachable`: using the current versioning rules, the Build ID may be used\n   by new Workflow Executions or Activities OR there are currently open\n   Workflow or backlogged Activity tasks assigned to the queue.\n- `ClosedWorkflowsOnly`: the Build ID does not have open Workflow Executions\n   and can't be reached by new Workflow Executions. It MAY have closed\n   Workflow Executions within the Namespace retention period.\n- `Unreachable`: this Build ID is not used for new Workflow Executions and\n  isn't used by any existing Workflow Execution within the retention period.\n\nTask reachability is eventually consistent. You may experience a delay until\nreachability converges to the most accurate value. This is designed to act\nin the most conservative way until convergence. For example, `Reachable` is\nmore conservative than `ClosedWorkflowsOnly`."
+		s.Command.Long = "Display a list of active Workers that have recently polled a Task Queue. The\nTemporal Server records each poll request time. A `LastAccessTime` over one\nminute may indicate the Worker is at capacity or has shut down. Temporal\nWorkers are removed if 5 minutes have passed since the last poll request.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\n```\ntemporal task-queue describe \\\n   --task-queue YourTaskQueue\n```\n\nThis command provides poller information for a given Task Queue.\nWorkflow and Activity polling use separate Task Queues:\n\n```\ntemporal task-queue describe \\\n    --task-queue YourTaskQueue \\\n    --task-queue-type \"activity\"\n```\n\nThis command provides the following task queue statistics:\n- `ApproximateBacklogCount`: The approximate number of tasks backlogged in this\n  task queue. May count expired tasks but eventually converges to the right\n  value.\n- `ApproximateBacklogAge`: Approximate age of the oldest task in the backlog,\n  based on its creation time, measured in seconds.\n- `TasksAddRate`: Approximate rate at which tasks are being added to the task\n  queue, measured in tasks per second, averaged over the last 30 seconds.\n  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog. (See note below.)\n- `TasksDispatchRate`: Approximate rate at which tasks are being dispatched from\n  the task queue, measured in tasks per second, averaged over the last 30\n  seconds.  Includes tasks dispatched immediately without going to the backlog\n  (sync-matched tasks), as well as tasks added to the backlog. (See note below.)\n- `Backlog Increase Rate`: Approximate rate at which the backlog size is\n  increasing (if positive) or decreasing (if negative), measured in tasks per\n  second, averaged over the last 30 seconds.  This is equivalent to:\n  `TasksAddRate` - `TasksDispatchRate`.\n\nNOTE: The `TasksAddRate` and `TasksDispatchRate` metrics may differ from the\nactual rate of add/dispatch, because tasks may be dispatched eagerly to an\navailable worker, or may apply only to specific workers (they are \"sticky\").\nSuch tasks are not counted by these metrics.\n\nSafely retire Workers assigned a Build ID by checking reachability across\nall task types. Use the flag `--report-reachability`:\n\n```\ntemporal task-queue describe \\\n   --task-queue YourTaskQueue \\\n   --build-id \"YourBuildId\" \\\n   --report-reachability\n```\n\nTask reachability information is returned for the requested versions and all\ntask types, which can be used to safely retire Workers with old code versions,\nprovided that they were assigned a Build ID.\n\nNote that task reachability status is experimental and may significantly change\nor be removed in a future release. Also, determining task reachability incurs a\nnon-trivial computing cost.\n\nTask reachability states are reported per build ID. The state may be one of the\nfollowing:\n\n- `Reachable`: using the current versioning rules, the Build ID may be used\n  by new Workflow Executions or Activities OR there are currently open\n  Workflow or backlogged Activity tasks assigned to the queue.\n- `ClosedWorkflowsOnly`: the Build ID does not have open Workflow Executions\n  and can't be reached by new Workflow Executions. It MAY have closed\n  Workflow Executions within the Namespace retention period.\n- `Unreachable`: this Build ID is not used for new Workflow Executions and\n  isn't used by any existing Workflow Execution within the retention period.\n\nTask reachability is eventually consistent. You may experience a delay until\nreachability converges to the most accurate value. This is designed to act\nin the most conservative way until convergence. For example, `Reachable` is\nmore conservative than `ClosedWorkflowsOnly`."
 	}
 	s.Command.Args = cobra.NoArgs
 	s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name. Required.")

temporalcli/commandsmd/commands.md

@@ -1512,29 +1512,33 @@ Workflow and Activity polling use separate Task Queues:
 ```
 temporal task-queue describe \
     --task-queue YourTaskQueue \
-    --task-queue-type "activity"`
+    --task-queue-type "activity"
 ```
 
 This command provides the following task queue statistics:
 - `ApproximateBacklogCount`: The approximate number of tasks backlogged in this
-  task queue.  May count expired tasks but eventually converges to the right
+  task queue. May count expired tasks but eventually converges to the right
   value.
-- `ApproximateBacklogAge`: How far "behind" the task queue is running. This is
-  the difference in age between the oldest and newest tasks in the backlog,
-  measured in seconds.
+- `ApproximateBacklogAge`: Approximate age of the oldest task in the backlog,
+  based on its creation time, measured in seconds.
 - `TasksAddRate`: Approximate rate at which tasks are being added to the task
   queue, measured in tasks per second, averaged over the last 30 seconds.
   Includes tasks dispatched immediately without going to the backlog
-  (sync-matched tasks), as well as tasks added to the backlog.
+  (sync-matched tasks), as well as tasks added to the backlog. (See note below.)
 - `TasksDispatchRate`: Approximate rate at which tasks are being dispatched from
   the task queue, measured in tasks per second, averaged over the last 30
   seconds.  Includes tasks dispatched immediately without going to the backlog
-  (sync-matched tasks), as well as tasks added to the backlog.
+  (sync-matched tasks), as well as tasks added to the backlog. (See note below.)
 - `Backlog Increase Rate`: Approximate rate at which the backlog size is
   increasing (if positive) or decreasing (if negative), measured in tasks per
   second, averaged over the last 30 seconds.  This is equivalent to:
   `TasksAddRate` - `TasksDispatchRate`.
 
+NOTE: The `TasksAddRate` and `TasksDispatchRate` metrics may differ from the
+actual rate of add/dispatch, because tasks may be dispatched eagerly to an
+available worker, or may apply only to specific workers (they are "sticky").
+Such tasks are not counted by these metrics.
+
 Safely retire Workers assigned a Build ID by checking reachability across
 all task types. Use the flag `--report-reachability`:
 
@@ -1557,11 +1561,11 @@ Task reachability states are reported per build ID. The state may be one of the
 following:
 
 - `Reachable`: using the current versioning rules, the Build ID may be used
-   by new Workflow Executions or Activities OR there are currently open
-   Workflow or backlogged Activity tasks assigned to the queue.
+  by new Workflow Executions or Activities OR there are currently open
+  Workflow or backlogged Activity tasks assigned to the queue.
 - `ClosedWorkflowsOnly`: the Build ID does not have open Workflow Executions
-   and can't be reached by new Workflow Executions. It MAY have closed
-   Workflow Executions within the Namespace retention period.
+  and can't be reached by new Workflow Executions. It MAY have closed
+  Workflow Executions within the Namespace retention period.
 - `Unreachable`: this Build ID is not used for new Workflow Executions and
   isn't used by any existing Workflow Execution within the retention period.
 
@@ -2813,4 +2817,3 @@ temporal workflow update start \
 
 Includes options set for [update starting](#options-set-for-update-starting).
 Includes options set for [payload input](#options-set-for-payload-input).
-