package temporal.api.taskqueue.v1

Get desktop application:
View/edit binary Protocol Buffers messages

Assignment rules are applied to *new* Workflow and Activity executions at schedule time to assign them to a Build ID. Assignment rules will not be used in the following cases: - Child Workflows or Continue-As-New Executions who inherit their parent/previous Workflow's assigned Build ID (by setting the `inherit_build_id` flag - default behavior in SDKs when the same Task Queue is used.) - An Activity that inherits the assigned Build ID of its Workflow (by setting the `use_workflow_build_id` flag - default behavior in SDKs when the same Task Queue is used.) In absence of (applicable) redirect rules (`CompatibleBuildIdRedirectRule`s) the task will be dispatched to Workers of the Build ID determined by the assignment rules (or inherited). Otherwise, the final Build ID will be determined by the redirect rules. Once a Workflow completes its first Workflow Task in a particular Build ID it stays in that Build ID regardless of changes to assignment rules. Redirect rules can be used to move the workflow to another compatible Build ID. When using Worker Versioning on a Task Queue, in the steady state, there should typically be a single assignment rule to send all new executions to the latest Build ID. Existence of at least one such "unconditional" rule at all times is enforces by the system, unless the `force` flag is used by the user when replacing/deleting these rules (for exceptional cases). During a deployment, one or more additional rules can be added to assign a subset of the tasks to a new Build ID based on a "ramp percentage". When there are multiple assignment rules for a Task Queue, the rules are evaluated in order, starting from index 0. The first applicable rule will be applied and the rest will be ignored. In the event that no assignment rule is applicable on a task (or the Task Queue is simply not versioned), the tasks will be dispatched to an unversioned Worker.

Used in: TimestampedBuildIdAssignmentRule, workflowservice.v1.UpdateWorkerVersioningRulesRequest.InsertBuildIdAssignmentRule, workflowservice.v1.UpdateWorkerVersioningRulesRequest.ReplaceBuildIdAssignmentRule

• string target_build_id = 1

• oneof ramp

  If a ramp is provided, this rule will be applied only to a sample of tasks according to the provided percentage. This option can be used only on "terminal" Build IDs (the ones not used as source in any redirect rules).

  • RampByPercentage percentage_ramp = 3

    This ramp is useful for gradual Blue/Green deployments (and similar) where you want to send a certain portion of the traffic to the target Build ID.

Reachability of tasks for a worker by build id, in one or more task queues.

Used in: workflowservice.v1.GetWorkerTaskReachabilityResponse

• string build_id = 1

  A build id or empty if unversioned.

• repeated TaskQueueReachability task_queue_reachability = 2

  Reachability per task queue.

These rules apply to tasks assigned to a particular Build ID (`source_build_id`) to redirect them to another *compatible* Build ID (`target_build_id`). It is user's responsibility to ensure that the target Build ID is compatible with the source Build ID (e.g. by using the Patching API). Most deployments are not expected to need these rules, however following situations can greatly benefit from redirects: - Need to move long-running Workflow Executions from an old Build ID to a newer one. - Need to hotfix some broken or stuck Workflow Executions. In steady state, redirect rules are beneficial when dealing with old Executions ran on now-decommissioned Build IDs: - To redirecting the Workflow Queries to the current (compatible) Build ID. - To be able to Reset an old Execution so it can run on the current (compatible) Build ID. Redirect rules can be chained.

Used in: TimestampedCompatibleBuildIdRedirectRule, workflowservice.v1.UpdateWorkerVersioningRulesRequest.AddCompatibleBuildIdRedirectRule, workflowservice.v1.UpdateWorkerVersioningRulesRequest.ReplaceCompatibleBuildIdRedirectRule

• string source_build_id = 1

• string target_build_id = 2

  Target Build ID must be compatible with the Source Build ID; that is it must be able to process event histories made by the Source Build ID by using [Patching](https://docs.temporal.io/workflows#patching) or other means.

Used by the worker versioning APIs, represents an unordered set of one or more versions which are considered to be compatible with each other. Currently the versions are always worker build IDs.

Used in: workflowservice.v1.GetWorkerBuildIdCompatibilityResponse

• repeated string build_ids = 1

  All the compatible versions, unordered, except for the last element, which is considered the set "default".

Used in: RateLimitConfig

• string reason = 1

  Reason for why the config was set.

• string update_identity = 2

  Identity of the last updater. Set by the request's identity field.

• optional google.protobuf.Timestamp update_time = 3

  Time of the last update.

Used in: workflowservice.v1.DescribeNamespaceResponse, workflowservice.v1.PollActivityTaskQueueResponse, workflowservice.v1.PollNexusTaskQueueResponse, workflowservice.v1.PollWorkflowTaskQueueResponse

• string id = 1

• float weight = 2

Used in: TaskQueueTypeInfo, workflowservice.v1.DescribeTaskQueueResponse

• optional google.protobuf.Timestamp last_access_time = 1

• string identity = 2

• double rate_per_second = 3

• optional common.v1.WorkerVersionCapabilities worker_version_capabilities = 4

  If a worker has opted into the worker versioning feature while polling, its capabilities will appear here. Deprecated. Replaced by deployment_options.

• optional deployment.v1.WorkerDeploymentOptions deployment_options = 5

  Worker deployment options that SDK sent to server.

Attached to task responses to give hints to the SDK about how it may adjust its number of pollers.

Used in: workflowservice.v1.PollActivityTaskQueueResponse, workflowservice.v1.PollNexusTaskQueueResponse, workflowservice.v1.PollWorkflowTaskQueueResponse

• int32 poll_request_delta_suggestion = 1

  How many poll requests to suggest should be added or removed, if any. As of now, server only scales up or down by 1. However, SDKs should allow for other values (while staying within defined min/max). The SDK is free to ignore this suggestion, EX: making more polls would not make sense because all slots are already occupied.

Used in: BuildIdAssignmentRule

• float ramp_percentage = 1

  Acceptable range is [0,100).

Used in: RateLimitConfig, workflowservice.v1.UpdateTaskQueueConfigRequest.RateLimitUpdate

• float requests_per_second = 1

  Zero is a valid rate limit.

Used in: TaskQueueConfig

• optional RateLimit rate_limit = 1

• optional ConfigMetadata metadata = 2

Used in: workflowservice.v1.RespondWorkflowTaskCompletedRequest

• optional TaskQueue worker_task_queue = 1

• optional google.protobuf.Duration schedule_to_start_timeout = 2

  (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --)

Used in: TaskQueueStatus

• int64 start_id = 1

• int64 end_id = 2

See https://docs.temporal.io/docs/concepts/task-queues/

Used in: activity.v1.ActivityOptions, command.v1.ContinueAsNewWorkflowExecutionCommandAttributes, command.v1.ScheduleActivityTaskCommandAttributes, command.v1.StartChildWorkflowExecutionCommandAttributes, history.v1.ActivityTaskScheduledEventAttributes, history.v1.StartChildWorkflowExecutionInitiatedEventAttributes, history.v1.WorkflowExecutionContinuedAsNewEventAttributes, history.v1.WorkflowExecutionStartedEventAttributes, history.v1.WorkflowTaskScheduledEventAttributes, StickyExecutionAttributes, workflow.v1.NewWorkflowExecutionInfo, workflow.v1.WorkflowExecutionConfig, workflowservice.v1.DescribeTaskQueueRequest, workflowservice.v1.ListTaskQueuePartitionsRequest, workflowservice.v1.PollActivityTaskQueueRequest, workflowservice.v1.PollNexusTaskQueueRequest, workflowservice.v1.PollWorkflowTaskQueueRequest, workflowservice.v1.PollWorkflowTaskQueueResponse, workflowservice.v1.SignalWithStartWorkflowExecutionRequest, workflowservice.v1.StartActivityExecutionRequest, workflowservice.v1.StartWorkflowExecutionRequest

• string name = 1

• enums.v1.TaskQueueKind kind = 2

  Default: TASK_QUEUE_KIND_NORMAL.

• string normal_name = 3

  Iff kind == TASK_QUEUE_KIND_STICKY, then this field contains the name of the normal task queue that the sticky worker is running on.

Used in: workflowservice.v1.DescribeTaskQueueResponse, workflowservice.v1.UpdateTaskQueueConfigResponse

• optional RateLimitConfig queue_rate_limit = 1

  Unless modified, this is the system-defined rate limit.

• optional RateLimitConfig fairness_keys_rate_limit_default = 2

  If set, each individual fairness key will be limited to this rate, scaled by the weight of the fairness key.

• map<string, float> fairness_weight_overrides = 3

  If set, overrides the fairness weights for the corresponding fairness keys.

Only applies to activity task queues

Used in: workflowservice.v1.PollActivityTaskQueueRequest

• optional google.protobuf.DoubleValue max_tasks_per_second = 1

  Allows throttling dispatch of tasks from this queue

Used in: workflowservice.v1.ListTaskQueuePartitionsResponse

• string key = 1

• string owner_host_name = 2

Reachability of tasks for a worker on a single task queue.

Used in: BuildIdReachability

• string task_queue = 1

• repeated enums.v1.TaskReachability reachability = 2

  Task reachability for a worker in a single task queue. See the TaskReachability docstring for information about each enum variant. If reachability is empty, this worker is considered unreachable in this task queue.

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.

Used in: TaskQueueTypeInfo, workflowservice.v1.DescribeTaskQueueResponse, workflowservice.v1.DescribeWorkerDeploymentVersionResponse.VersionTaskQueue

• int64 approximate_backlog_count = 1

  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.

• optional google.protobuf.Duration approximate_backlog_age = 2

  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.

• float tasks_add_rate = 3

  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_dispatch_rate = 4

  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.

Deprecated. Use `InternalTaskQueueStatus`. This is kept until `DescribeTaskQueue` supports legacy behavior.

Used in: workflowservice.v1.DescribeTaskQueueResponse

• int64 backlog_count_hint = 1

• int64 read_level = 2

• int64 ack_level = 3

• double rate_per_second = 4

• optional TaskIdBlock task_id_block = 5

Used in: TaskQueueVersionInfo

• repeated PollerInfo pollers = 1

  Unversioned workers (with `useVersioning=false`) are reported in unversioned result even if they set a Build ID.

• optional TaskQueueStats stats = 2

Used in: workflowservice.v1.DescribeTaskQueueResponse

• map<int32, TaskQueueTypeInfo> types_info = 1

  Task Queue info per Task Type. Key is the numerical value of the temporal.api.enums.v1.TaskQueueType enum.

• enums.v1.BuildIdTaskReachability task_reachability = 2

  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. 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 assignment rules of their Task Queue. Same goes for Child Workflows or Continue-As-New Workflows who inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make sure to query reachability for the parent/previous workflow's Task Queue as well.

Used for specifying versions the caller is interested in.

Used in: workflowservice.v1.DescribeTaskQueueRequest

• repeated string build_ids = 1

  Include specific Build IDs.

• bool unversioned = 2

  Include the unversioned queue.

• bool all_active = 3

  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.

Used in: workflowservice.v1.DescribeTaskQueueResponse

• optional deployment.v1.WorkerDeploymentVersion current_deployment_version = 7

  Specifies which Deployment Version should receive new workflow executions and tasks of existing unversioned or AutoUpgrade workflows. Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`).

• string current_version = 1

  Deprecated. Use `current_deployment_version`.

• optional deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9

  When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. Must always be different from `current_deployment_version` unless both are nil. Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) Note that it is possible to ramp from one Version to another Version, or from unversioned workers to a particular Version, or from a particular Version to unversioned workers.

• string ramping_version = 2

  Deprecated. Use `ramping_deployment_version`.

• float ramping_version_percentage = 3

  Percentage of tasks that are routed to the Ramping Version instead of the Current Version. Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but not yet "promoted" to be the Current Version, likely due to pending validations. A 0% value means the Ramping Version is receiving no traffic.

• optional google.protobuf.Timestamp update_time = 4

  Last time versioning information of this Task Queue changed.

Used in: workflowservice.v1.GetWorkerVersioningRulesResponse, workflowservice.v1.UpdateWorkerVersioningRulesResponse

• optional BuildIdAssignmentRule rule = 1

• optional google.protobuf.Timestamp create_time = 2

Used in: workflowservice.v1.GetWorkerVersioningRulesResponse, workflowservice.v1.UpdateWorkerVersioningRulesResponse

• optional CompatibleBuildIdRedirectRule rule = 1

• optional google.protobuf.Timestamp create_time = 2