@temporalio/core-bridge 1.11.2 → 1.11.4

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/activity/v1/message.proto

@@ -0,0 +1,67 @@
+// The MIT License
+//
+// Copyright (c) 2020 Temporal Technologies Inc.  All rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+syntax = "proto3";
+
+package temporal.api.activity.v1;
+
+option go_package = "go.temporal.io/api/activity/v1;activity";
+option java_package = "io.temporal.api.activity.v1";
+option java_multiple_files = true;
+option java_outer_classname = "MessageProto";
+option ruby_package = "Temporalio::Api::Activity::V1";
+option csharp_namespace = "Temporalio.Api.Activity.V1";
+
+import "temporal/api/common/v1/message.proto";
+import "temporal/api/taskqueue/v1/message.proto";
+
+import "google/protobuf/duration.proto";
+
+message ActivityOptions {
+    temporal.api.taskqueue.v1.TaskQueue task_queue = 1;
+
+    // Indicates how long the caller is willing to wait for an activity completion. Limits how long
+    // retries will be attempted. Either this or `start_to_close_timeout` must be specified.
+    //
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_close_timeout = 2;
+    // Limits time an activity task can stay in a task queue before a worker picks it up. This
+    // timeout is always non retryable, as all a retry would achieve is to put it back into the same
+    // queue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not
+    // specified.
+    //
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_start_timeout = 3;
+    // Maximum time an activity is allowed to execute after being picked up by a worker. This
+    // timeout is always retryable. Either this or `schedule_to_close_timeout` must be
+    // specified.
+    //
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration start_to_close_timeout = 4;
+    // Maximum permitted time between successful worker heartbeats.
+    google.protobuf.Duration heartbeat_timeout = 5;
+
+    temporal.api.common.v1.RetryPolicy retry_policy = 6;
+}

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/common/v1/message.proto

@@ -35,6 +35,7 @@ import "google/protobuf/duration.proto";
 import "google/protobuf/empty.proto";
 
 import "temporal/api/enums/v1/common.proto";
+import "temporal/api/enums/v1/event_type.proto";
 import "temporal/api/enums/v1/reset.proto";
 
 message DataBlob {
@@ -191,8 +192,53 @@ message Callback {
         map<string, string> header = 2;
     }
 
+    // Callbacks to be delivered internally within the system.
+    // This variant is not settable in the API and will be rejected by the service with an INVALID_ARGUMENT error.
+    // The only reason that this is exposed is because callbacks are replicated across clusters via the
+    // WorkflowExecutionStarted event, which is defined in the public API.
+    message Internal {
+        // Opaque internal data.
+        bytes data = 1;
+    }
+
     reserved 1; // For a generic callback mechanism to be added later.
     oneof variant {
         Nexus nexus = 2;
+        Internal internal = 3;
+    }
+}
+
+// Link can be associated with history events. It might contain information about an external entity
+// related to the history event. For example, workflow A makes a Nexus call that starts workflow B:
+// in this case, a history event in workflow A could contain a Link to the workflow started event in
+// workflow B, and vice-versa.
+message Link {
+    message WorkflowEvent {
+        message EventReference {
+            int64 event_id = 1;
+            temporal.api.enums.v1.EventType event_type = 2;
+        }
+
+        string namespace = 1;
+        string workflow_id = 2;
+        string run_id = 3;
+
+        // Additional information about the workflow event.
+        // Eg: the caller workflow can send the history event details that made the Nexus call.
+        oneof reference {
+            EventReference event_ref = 100;
+        }
     }
-}
+
+    // A link to a built-in batch job.
+    // Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).
+    // This link can be put on workflow history events generated by actions taken by a batch job.
+    message BatchJob {
+        string job_id = 1;
+    }
+
+    oneof variant {
+        WorkflowEvent workflow_event = 1;
+        BatchJob batch_job = 2;
+    }
+}

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/enums/v1/event_type.proto

@@ -151,9 +151,13 @@ enum EventType {
     EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_SIGNALED = 39;
     // Workflow search attributes should be updated and synchronized with the visibility store
     EVENT_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES = 40;
-    // An update was accepted (i.e. validated)
+    // An update was admitted. Note that not all admitted updates result in this
+    // event. See UpdateAdmittedEventOrigin for situations in which this event
+    // is created.
+    EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ADMITTED = 47;
+    // An update was accepted (i.e. passed validation, perhaps because no validator was defined)
     EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ACCEPTED = 41;
-    // An update was rejected (i.e. failed validation)
+    // This event is never written to history.
     EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_REJECTED = 42;
     // An update completed
     EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_COMPLETED = 43;
@@ -167,11 +171,6 @@ enum EventType {
     EVENT_TYPE_ACTIVITY_PROPERTIES_MODIFIED_EXTERNALLY = 45;
     // Workflow properties modified by user workflow code
     EVENT_TYPE_WORKFLOW_PROPERTIES_MODIFIED = 46;
-    // An update was admitted. Note that not all admitted updates result in this
-    // event. See UpdateAdmittedEventOrigin for situations in which this event
-    // is created.
-    EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ADMITTED = 47;
-
     // A Nexus operation was scheduled using a ScheduleNexusOperation command.
     EVENT_TYPE_NEXUS_OPERATION_SCHEDULED = 48;
     // An asynchronous Nexus operation was started by a Nexus handler.

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/enums/v1/failed_cause.proto

@@ -139,6 +139,8 @@ enum ResourceExhaustedCause {
     RESOURCE_EXHAUSTED_CAUSE_APS_LIMIT = 6;
     // Persistence storage limit exceeded.
     RESOURCE_EXHAUSTED_CAUSE_PERSISTENCE_STORAGE_LIMIT = 7;
+    // Circuit breaker is open/half-open.
+    RESOURCE_EXHAUSTED_CAUSE_CIRCUIT_BREAKER_OPEN = 8;
 }
 
 enum ResourceExhaustedScope {

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/enums/v1/reset.proto

@@ -31,13 +31,15 @@ option java_outer_classname = "ResetProto";
 option ruby_package = "Temporalio::Api::Enums::V1";
 option csharp_namespace = "Temporalio.Api.Enums.V1";
 
-// Event types to exclude when reapplying events.
+// Event types to exclude when reapplying events beyond the reset point.
 enum ResetReapplyExcludeType {
     RESET_REAPPLY_EXCLUDE_TYPE_UNSPECIFIED = 0;
-    // Exclude signals when reapplying events.
+    // Exclude signals when reapplying events beyond the reset point.
     RESET_REAPPLY_EXCLUDE_TYPE_SIGNAL = 1;
-    // Exclude updates when reapplying events.
+    // Exclude updates when reapplying events beyond the reset point.
     RESET_REAPPLY_EXCLUDE_TYPE_UPDATE = 2;
+    // Exclude nexus events when reapplying events beyond the reset point.
+    RESET_REAPPLY_EXCLUDE_TYPE_NEXUS = 3;
 }
 
 // Event types to include when reapplying events. Deprecated: applications

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/enums/v1/task_queue.proto

@@ -81,9 +81,9 @@ enum TaskReachability {
 
 // Specifies which category of tasks may reach a versioned worker of a certain Build ID.
 //
-// Task Reachability is eventually consistent; there may be a delay until it converges to the most
-// accurate value but it is designed in a way to take the more conservative side until it converges.
-// For example REACHABLE is more conservative than CLOSED_WORKFLOWS_ONLY.
+// Task Reachability is eventually consistent; there may be a delay (up to few minutes) until it
+// converges to the most accurate value but it is designed in a way to take the more conservative
+// side until it converges. For example REACHABLE is more conservative than CLOSED_WORKFLOWS_ONLY.
 //
 // Note: future activities who inherit their workflow's Build ID but not its Task Queue will not be
 // accounted for reachability as server cannot know if they'll happen as they do not use

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/enums/v1/update.proto

@@ -32,35 +32,36 @@ option ruby_package = "Temporalio::Api::Enums::V1";
 option csharp_namespace = "Temporalio.Api.Enums.V1";
 
 // UpdateWorkflowExecutionLifecycleStage is specified by clients invoking
-// workflow execution updates and used to indicate to the server how long the
-// client wishes to wait for a return value from the RPC. If any value other
+// Workflow Updates and used to indicate to the server how long the
+// client wishes to wait for a return value from the API. If any value other
 // than UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED is sent by the
-// client then the RPC will complete before the update is finished and will
-// return a handle to the running update so that it can later be polled for
+// client then the API will complete before the Update is finished and will
+// return a handle to the running Update so that it can later be polled for
 // completion.
+// If specified stage wasn't reached before server timeout, server returns
+// actual stage reached.
 enum UpdateWorkflowExecutionLifecycleStage {
-    // An unspecified vale for this enum.
+    // An unspecified value for this enum.
     UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED = 0;
-    // The gRPC call will not return until the update request has been admitted
+    // The API call will not return until the Update request has been admitted
     // by the server - it may be the case that due to a considerations like load
-    // or resource limits that an update is made to wait before the server will
+    // or resource limits that an Update is made to wait before the server will
     // indicate that it has been received and will be processed. This value
     // does not wait for any sort of acknowledgement from a worker.
     UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED = 1;
-    // The gRPC call will not return until the update has passed validation on
-    // a worker.
+    // The API call will not return until the Update has passed validation on a worker.
     UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED = 2;
-    // The gRPC call will not return until the update has executed to completion
+    // The API call will not return until the Update has executed to completion
     // on a worker and has either been rejected or returned a value or an error.
     UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED = 3;
 }
 
 // Records why a WorkflowExecutionUpdateAdmittedEvent was written to history.
-// Note that not all admitted updates result in this event.
+// Note that not all admitted Updates result in this event.
 enum UpdateAdmittedEventOrigin {
     UPDATE_ADMITTED_EVENT_ORIGIN_UNSPECIFIED = 0;
     // The UpdateAdmitted event was created when reapplying events during reset
-    // or replication. I.e. an accepted update on one branch of workflow history
-    // was converted into an admitted update on a different branch.
+    // or replication. I.e. an accepted Update on one branch of Workflow history
+    // was converted into an admitted Update on a different branch.
     UPDATE_ADMITTED_EVENT_ORIGIN_REAPPLY = 1;
 }

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/failure/v1/message.proto

@@ -44,8 +44,6 @@ message ApplicationFailureInfo {
     // retry interval calculated by the retry policy. Retry attempts will
     // still be subject to the maximum retries limit and total time limit
     // defined by the policy.
-    // ATTENTION: this value will be ignored if set for failures produced by
-    // the workflow.
     google.protobuf.Duration next_retry_delay = 4;
 }
 
@@ -111,7 +109,7 @@ message Failure {
     // The `encoded_attributes` Payload could represent any serializable object, e.g. JSON object or a `Failure` proto
     // message.
     //
-    // SDK authors: 
+    // SDK authors:
     // - The SDK should provide a default `encodeFailureAttributes` and `decodeFailureAttributes` implementation that:
     //   - Uses a JSON object to represent `{ message, stack_trace }`.
     //   - Overwrites the original message with "Encoded failure" to indicate that more information could be extracted.

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/history/v1/message.proto

@@ -822,6 +822,11 @@ message NexusOperationScheduledEventAttributes {
     // A unique ID generated by the history service upon creation of this event.
     // The ID will be transmitted with all nexus StartOperation requests and is used as an idempotentency key.
     string request_id = 8;
+
+    // Endpoint ID as resolved in the endpoint registry at the time this event was generated.
+    // This is stored on the event and used internally by the server in case the endpoint is renamed from the time the
+    // event was originally scheduled.
+    string endpoint_id = 9;
 }
 
 // Event marking an asynchronous operation was started by the responding Nexus handler.
@@ -834,6 +839,9 @@ message NexusOperationStartedEventAttributes {
     // The operation ID returned by the Nexus handler in the response to the StartOperation request.
     // This ID is used when canceling the operation.
     string operation_id = 3;
+
+    // The request ID allocated at schedule time.
+    string request_id = 4;
 }
 
 // Nexus operation completed successfully.
@@ -843,6 +851,9 @@ message NexusOperationCompletedEventAttributes {
     // Serialized result of the Nexus operation. The response of the Nexus handler.
     // Delivered either via a completion callback or as a response to a synchronous operation.
     temporal.api.common.v1.Payload result = 2;
+
+    // The request ID allocated at schedule time.
+    string request_id = 3;
 }
 
 // Nexus operation failed.
@@ -851,6 +862,9 @@ message NexusOperationFailedEventAttributes {
     int64 scheduled_event_id = 1;
     // Failure details. A NexusOperationFailureInfo wrapping an ApplicationFailureInfo.
     temporal.api.failure.v1.Failure failure = 2;
+
+    // The request ID allocated at schedule time.
+    string request_id = 3;
 }
 
 // Nexus operation timed out.
@@ -859,6 +873,9 @@ message NexusOperationTimedOutEventAttributes {
     int64 scheduled_event_id = 1;
     // Failure details. A NexusOperationFailureInfo wrapping a CanceledFailureInfo.
     temporal.api.failure.v1.Failure failure = 2;
+
+    // The request ID allocated at schedule time.
+    string request_id = 3;
 }
 
 // Nexus operation completed as canceled. May or may not have been due to a cancellation request by the workflow.
@@ -867,6 +884,9 @@ message NexusOperationCanceledEventAttributes {
     int64 scheduled_event_id = 1;
     // Cancellation details.
     temporal.api.failure.v1.Failure failure = 2;
+
+    // The request ID allocated at schedule time.
+    string request_id = 3;
 }
 
 message NexusOperationCancelRequestedEventAttributes {
@@ -902,6 +922,8 @@ message HistoryEvent {
     //  * timer_started_event_attributes - summary represents an identifier for the timer for use by
     //    user interfaces.
     temporal.api.sdk.v1.UserMetadata user_metadata = 301;
+    // Links associated with the event.
+    repeated temporal.api.common.v1.Link links = 302;
     // The event details. The type must match that in `event_type`.
     oneof attributes {
         WorkflowExecutionStartedEventAttributes workflow_execution_started_event_attributes = 6;

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/nexus/v1/message.proto

@@ -31,7 +31,6 @@ option csharp_namespace = "Temporalio.Api.Nexus.V1";
 
 import "google/protobuf/timestamp.proto";
 import "temporal/api/common/v1/message.proto";
-import "temporal/api/sdk/v1/user_metadata.proto";
 
 // A general purpose failure message.
 // See: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure
@@ -53,6 +52,12 @@ message UnsuccessfulOperationError {
     Failure failure = 2;
 }
 
+message Link {
+    // See https://github.com/nexus-rpc/api/blob/main/SPEC.md#links.
+    string url = 1;
+    string type = 2;
+}
+
 // A request to start an operation.
 message StartOperationRequest {
     // Name of service to start the operation in.
@@ -67,6 +72,8 @@ message StartOperationRequest {
     temporal.api.common.v1.Payload payload = 5;
     // Header that is expected to be attached to the callback request when the operation completes.
     map<string, string> callback_header = 6;
+    // Links contain caller information and can be attached to the operations started by the handler.
+    repeated Link links = 7;
 }
 
 // A request to cancel an operation.
@@ -107,6 +114,7 @@ message StartOperationResponse {
     // The returned ID can be used to reference this operation.
     message Async {
         string operation_id = 1;
+        repeated Link links = 2;
     }
 
     oneof variant {
@@ -162,7 +170,10 @@ message EndpointSpec {
     // Renaming an endpoint breaks all workflow callers that reference this endpoint, causing operations to fail.
     string name = 1;
 
-    temporal.api.sdk.v1.UserMetadata metadata = 2;
+    // Markdown description serialized as a single JSON string.
+    // If the Payload is encrypted, the UI and CLI may decrypt with the configured codec server endpoint.
+    // By default, the server enforces a limit of 20,000 bytes for this entire payload.
+    temporal.api.common.v1.Payload description = 2;
 
     // Target to route requests to.
     EndpointTarget target = 3;

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/operatorservice/v1/service.proto

@@ -58,7 +58,10 @@ service OperatorService {
     // ListSearchAttributes returns comprehensive information about search attributes.
     rpc ListSearchAttributes (ListSearchAttributesRequest) returns (ListSearchAttributesResponse) {
         option (google.api.http) = {
-            get: "/namespaces/{namespace}/search-attributes",
+            get: "/cluster/namespaces/{namespace}/search-attributes"
+            additional_bindings {
+                get: "/api/v1/namespaces/{namespace}/search-attributes"
+            }
         };
     }
 
@@ -81,7 +84,10 @@ service OperatorService {
     // Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.
     rpc GetNexusEndpoint(GetNexusEndpointRequest) returns (GetNexusEndpointResponse) {
         option (google.api.http) = {
-            get: "/nexus/endpoints/{id}"
+            get: "/cluster/nexus/endpoints/{id}"
+            additional_bindings {
+                get: "/api/v1/nexus/endpoints/{id}"
+            }
         };
     }
 
@@ -90,8 +96,12 @@ service OperatorService {
     // Returns the created endpoint with its initial version. You may use this version for subsequent updates.
     rpc CreateNexusEndpoint(CreateNexusEndpointRequest) returns (CreateNexusEndpointResponse) {
         option (google.api.http) = {
-            post: "/nexus/endpoints"
+            post: "/cluster/nexus/endpoints"
             body: "*"
+            additional_bindings {
+                post: "/api/v1/nexus/endpoints"
+                body: "*"
+            }
         };
     }
 
@@ -102,15 +112,22 @@ service OperatorService {
     // need to increment the version yourself. The server will increment the version for you after each update.
     rpc UpdateNexusEndpoint(UpdateNexusEndpointRequest) returns (UpdateNexusEndpointResponse) {
         option (google.api.http) = {
-            post: "/nexus/endpoints/{id}/update"
+            post: "/cluster/nexus/endpoints/{id}/update"
             body: "*"
+            additional_bindings {
+                post: "/api/v1/nexus/endpoints/{id}/update"
+                body: "*"
+            }
         };
     }
 
     // Delete an incoming Nexus service by ID.
     rpc DeleteNexusEndpoint(DeleteNexusEndpointRequest) returns (DeleteNexusEndpointResponse) {
         option (google.api.http) = {
-            delete: "/nexus/endpoints/{id}"
+            delete: "/cluster/nexus/endpoints/{id}"
+            additional_bindings {
+                delete: "/api/v1/nexus/endpoints/{id}"
+            }
         };
     }
 
@@ -120,7 +137,10 @@ service OperatorService {
     // earlier than the previous page's last endpoint's ID may be missed.
     rpc ListNexusEndpoints(ListNexusEndpointsRequest) returns (ListNexusEndpointsResponse) {
         option (google.api.http) = {
-            get: "/nexus/endpoints"
+            get: "/cluster/nexus/endpoints"
+            additional_bindings {
+                get: "/api/v1/nexus/endpoints"
+            }
         };
     }
 }

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/schedule/v1/message.proto

@@ -41,6 +41,7 @@ import "google/protobuf/timestamp.proto";
 
 import "temporal/api/common/v1/message.proto";
 import "temporal/api/enums/v1/schedule.proto";
+import "temporal/api/enums/v1/workflow.proto";
 import "temporal/api/workflow/v1/message.proto";
 
 // CalendarSpec describes an event specification relative to the calendar,
@@ -269,6 +270,10 @@ message ScheduleActionResult {
 
     // If action was start_workflow:
     temporal.api.common.v1.WorkflowExecution start_workflow_result = 11;
+
+    // If the action was start_workflow, this field will reflect an
+    // eventually-consistent view of the started workflow's status.
+    temporal.api.enums.v1.WorkflowExecutionStatus start_workflow_status = 12;
 }
 
 message ScheduleState {

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/sdk/v1/workflow_metadata.proto

@@ -45,8 +45,14 @@ message WorkflowDefinition {
   // A name scoped by the task queue that maps to this workflow definition.
   // If missing, this workflow is a dynamic workflow.
   string type = 1;
+
+  // Query definitions, sorted by name.
   repeated WorkflowInteractionDefinition query_definitions = 2;
+
+  // Signal definitions, sorted by name.
   repeated WorkflowInteractionDefinition signal_definitions = 3;
+
+  // Update definitions, sorted by name.
   repeated WorkflowInteractionDefinition update_definitions = 4;
 }
 

package/sdk-core/sdk-core-protos/protos/api_upstream/temporal/api/taskqueue/v1/message.proto

@@ -60,8 +60,8 @@ message TaskQueueVersionSelection {
     repeated string build_ids = 1;
     // Include the unversioned queue.
     bool unversioned = 2;
-    // Include all active versions. A version is considered active if it has had new
-    // tasks or polls recently.
+    // Include all active versions. A version is considered active if, in the last few minutes,
+    // it has had new tasks or polls, or it has been the subject of certain task queue API calls.
     bool all_active = 3;
 }
 
@@ -87,20 +87,54 @@ message TaskQueueTypeInfo {
     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.
+// TaskQueueStats contains statistics about task queue backlog and activity.
+//
+// For workflow task queue type, this result is partial because tasks sent to sticky queues are not included. Read
+// comments above each metric to understand the impact of sticky queue exclusion on that metric accuracy.
 message TaskQueueStats {
-    // The approximate number of tasks backlogged in this task queue. May count expired tasks but eventually converges
-    // to the right value.
+    // The approximate number of tasks backlogged in this task queue. May count expired tasks but eventually
+    // converges to the right value. Can be relied upon for scaling decisions.
+    //
+    // Special note for workflow task queue type: this metric does not count sticky queue tasks. However, because
+    // those tasks only remain valid for a few seconds, the inaccuracy becomes less significant as the backlog size
+    // grows.
     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.
+    // Approximate age of the oldest task in the backlog based on the creation time of the task at the head of
+    // the queue. Can be relied upon for scaling decisions.
+    //
+    // Special note for workflow task queue type: this metric does not count sticky queue tasks. However, because
+    // those tasks only remain valid for a few seconds, they should not affect the result when backlog is older than
+    // few seconds.
     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.
+    // The approximate tasks per second added to the task queue, averaging the last 30 seconds. These includes tasks
+    // whether or not they were added to/dispatched from the backlog or they were dispatched immediately without going
+    // to the backlog (sync-matched).
+    //
+    // The difference between `tasks_add_rate` and `tasks_dispatch_rate` is a reliable metric for the rate at which
+    // backlog grows/shrinks.
+    //
+    // Note: the actual tasks delivered to the workers may significantly be higher than the numbers reported by
+    // tasks_add_rate, because:
+    // - Tasks can be sent to workers without going to the task queue. This is called Eager dispatch. Eager dispatch is
+    //   enable for activities by default in the latest SDKs.
+    // - Tasks going to Sticky queue are not accounted for. Note that, typically, only the first workflow task of each
+    //   workflow goes to a normal queue, and the rest workflow tasks go to the Sticky queue associated with a specific
+    //   worker instance.
     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.
+    // The approximate tasks per second dispatched from the task queue, averaging the last 30 seconds. These includes
+    // tasks whether or not they were added to/dispatched from the backlog or they were dispatched immediately without
+    // going to the backlog (sync-matched).
+    //
+    // The difference between `tasks_add_rate` and `tasks_dispatch_rate` is a reliable metric for the rate at which
+    // backlog grows/shrinks.
+    //
+    // Note: the actual tasks delivered to the workers may significantly be higher than the numbers reported by
+    // tasks_dispatch_rate, because:
+    // - Tasks can be sent to workers without going to the task queue. This is called Eager dispatch. Eager dispatch is
+    //   enable for activities by default in the latest SDKs.
+    // - Tasks going to Sticky queue are not accounted for. Note that, typically, only the first workflow task of each
+    //   workflow goes to a normal queue, and the rest workflow tasks go to the Sticky queue associated with a specific
+    //   worker instance.
     float tasks_dispatch_rate = 4;
 }