From 10cc689cbb5343d3ebea956a42187a4b99799504 Mon Sep 17 00:00:00 2001 From: Yuri Date: Tue, 18 Feb 2025 09:36:25 -0800 Subject: [PATCH 1/2] Add documentation for new activity commands - pause/unpause/reset/update --- docs/cli/activity.mdx | 183 +++++++++++++++++++++++++++++++++++++++ docs/cli/cmd-options.mdx | 69 +++++++++++++++ 2 files changed, 252 insertions(+) diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index b81546f3f2..9154449431 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -9,6 +9,10 @@ keywords: - activity complete - activity execution - activity fail + - activity update-options + - activity pause + - activity unpause + - activity reset - cli reference - cli-feature - command-line-interface-cli @@ -18,6 +22,8 @@ tags: - Temporal CLI --- +# Activity commands + Activity commands operate on [Activity Executions](/activities#activity-execution). Activity commands follow this syntax: @@ -118,3 +124,180 @@ Use the following options to change the behavior of this command. - [--tls-server-name](/cli/cmd-options#tls-server-name) - [--workflow-id](/cli/cmd-options#workflow-id) + +## update-options + +The `temporal activity update-options` command updates options for an [Activity Execution](/activities#activity-execution). +The Activity must already be running on a valid [Workflow](/workflows). +Updates are incremental, only changing the specified options. Either activity id or activity type must be provided. +If type is provided, and there are multiple pending activities of the provided type - all of them will be updated. +Command will return new activity options. + +Use the following options to change the behavior of this command. + +Routing options: +- [--activity-id](/cli/cmd-options#activity-id) +- [--activity-type](/cli/cmd-options#activity-type) +- [--workflow-id](/cli/cmd-options#workflow-id) +- [--run-id](/cli/cmd-options#run-id) +- [--namespace](/cli/cmd-options#namespace) + + +Update specific options: + +- [--task-queue](/cli/cmd-options#task-queue) +- [--schedule-to-close-timeout](/cli/cmd-options#schedule-to-close-timeout) +- [--schedule-to-start-timeout](/cli/cmd-options#schedule-to-start-timeout) +- [--start-to-close-timeout](/cli/cmd-options#start-to-close-timeout) +- [--heartbeat-timeout](/cli/cmd-options#heartbeat-timeout) +- [--retry-initial-interval](/cli/cmd-options#retry-initial-interval) +- [--retry-maximum-interval](/cli/cmd-options#retry-maximum-interval) +- [--retry-backoff-coefficient](/cli/cmd-options#retry-backoff-coefficient) +- [--retry-maximum-attempts](/cli/cmd-options#retry-maximum-attempts) + +Other options: +- [--identity](/cli/cmd-options#identity) +- [--tls](/cli/cmd-options#tls) +- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +- [--tls-key-path](/cli/cmd-options#tls-key-path) +- [--tls-server-name](/cli/cmd-options#tls-server-name) +- [--address](/cli/cmd-options#address) +- [--codec-auth](/cli/cmd-options#codec-auth) +- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +- [--color](/cli/cmd-options#color) +- [--command-timeout](/cli/cmd-options#command-timeout) +- [--detail](/cli/cmd-options#detail) +- [--env](/cli/cmd-options#env) +- [--grpc-meta](/cli/cmd-options#grpc-meta) + +## pause + +The `temporal activity pause` command pauses an [Activity Execution](/activities#activity-execution) specified by its ID or type. +If type is provided, and there are multiple pending activities of the provided type - all of them will be paused. +Pausing an activity means: +* If the activity is currently waiting for a retry or is running and subsequently fails, it will not be rescheduled until it is unpaused. +* If the activity is already paused, calling this method will have no effect. +* If the activity is running and finishes successfully, the activity will be completed. +* If the activity is running and finishes with failure: + * if there is no retry left - the activity will be completed. + * if there are more retries left - the activity will be paused. +For long-running activities, activities in paused state will send a cancellation with "activity_paused" set to 'true' in response to 'RecordActivityTaskHeartbeat'. +The activity should respond to the cancellation accordingly. + +This command returns a `NotFound` error if there is no pending activity with the provided ID or type. +Use the following options to change the behavior of this command. + +Routing options: +- [--activity-id](/cli/cmd-options#activity-id) +- [--activity-type](/cli/cmd-options#activity-type) +- [--workflow-id](/cli/cmd-options#workflow-id) +- [--run-id](/cli/cmd-options#run-id) +- [--namespace](/cli/cmd-options#namespace) + +Other options: + - [--identity](/cli/cmd-options#identity) + - [--tls](/cli/cmd-options#tls) + - [--tls-ca-path](/cli/cmd-options#tls-ca-path) + - [--tls-cert-path](/cli/cmd-options#tls-cert-path) + - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) + - [--tls-key-path](/cli/cmd-options#tls-key-path) + - [--tls-server-name](/cli/cmd-options#tls-server-name) + - [--address](/cli/cmd-options#address) + - [--codec-auth](/cli/cmd-options#codec-auth) + - [--codec-endpoint](/cli/cmd-options#codec-endpoint) + - [--color](/cli/cmd-options#color) + - [--command-timeout](/cli/cmd-options#command-timeout) + - [--detail](/cli/cmd-options#detail) + - [--env](/cli/cmd-options#env) + - [--grpc-meta](/cli/cmd-options#grpc-meta) + +## unpause + +The `temporal activity unpause` command unpauses an [Activity Execution](/activities#activity-execution) specified by its ID or type. +If there are multiple pending activities of the provided type - all of them will be unpaused. +If activity is not paused, this call will have no effect. +If the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag). +Once the activity is unpaused, all timeout timers will be regenerated. + +Command will fail with a `NotFound` error if there is no pending activity with the provided ID or type. + +Activities can be unpaused in bulk via a visibility Query list filter: + +``` +temporal activity unpause --query YourQuery \ + --reason YourReasonForUnpause +``` + + +Routing options: +- [--activity-id](/cli/cmd-options#activity-id) +- [--activity-type](/cli/cmd-options#activity-type) +- [--workflow-id](/cli/cmd-options#workflow-id) +- [--run-id](/cli/cmd-options#run-id) +- [--namespace](/cli/cmd-options#namespace) + +Unpause specific options: +- [--match-all](/cli/cmd-options#match-all) +- [--reset-attempts](/cli/cmd-options#reset-attempts) +- [--reset-heartbeat](/cli/cmd-options#reset-heartbeat) +- [--jitter](/cli/cmd-options#activity-jitter) + +Other options: + - [--identity](/cli/cmd-options#identity) + - [--tls](/cli/cmd-options#tls) + - [--tls-ca-path](/cli/cmd-options#tls-ca-path) + - [--tls-cert-path](/cli/cmd-options#tls-cert-path) + - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) + - [--tls-key-path](/cli/cmd-options#tls-key-path) + - [--tls-server-name](/cli/cmd-options#tls-server-name) + - [--address](/cli/cmd-options#address) + - [--codec-auth](/cli/cmd-options#codec-auth) + - [--codec-endpoint](/cli/cmd-options#codec-endpoint) + - [--color](/cli/cmd-options#color) + - [--command-timeout](/cli/cmd-options#command-timeout) + - [--detail](/cli/cmd-options#detail) + - [--env](/cli/cmd-options#env) + - [--grpc-meta](/cli/cmd-options#grpc-meta) + +## reset + +The `temporal activity reset` command resets an [Activity Execution](/activities#activity-execution) specified by its ID or type. +If there are multiple pending activities of the provided type - all of them will be reset. +Resetting an activity means: +* number of attempts will be reset to 0. +* activity timeouts will be reset. +* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided, it will be scheduled immediately (* see 'jitter' flag), + +Command will fail with a `NotFound` error if there is no pending activity with the provided ID or type. + +Routing options: +- [--activity-id](/cli/cmd-options#activity-id) +- [--activity-type](/cli/cmd-options#activity-type) +- [--workflow-id](/cli/cmd-options#workflow-id) +- [--run-id](/cli/cmd-options#run-id) +- [--namespace](/cli/cmd-options#namespace) + +Reset specific options: +- [--keep-paused](/cli/cmd-options#keep-paused) +- [--reset-heartbeat](/cli/cmd-options#reset-heartbeat) +- [--jitter](/cli/cmd-options#activity-jitter) + +Other options: + - [--identity](/cli/cmd-options#identity) + - [--tls](/cli/cmd-options#tls) + - [--tls-ca-path](/cli/cmd-options#tls-ca-path) + - [--tls-cert-path](/cli/cmd-options#tls-cert-path) + - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) + - [--tls-key-path](/cli/cmd-options#tls-key-path) + - [--tls-server-name](/cli/cmd-options#tls-server-name) + - [--address](/cli/cmd-options#address) + - [--codec-auth](/cli/cmd-options#codec-auth) + - [--codec-endpoint](/cli/cmd-options#codec-endpoint) + - [--color](/cli/cmd-options#color) + - [--command-timeout](/cli/cmd-options#command-timeout) + - [--detail](/cli/cmd-options#detail) + - [--env](/cli/cmd-options#env) + - [--grpc-meta](/cli/cmd-options#grpc-meta) + diff --git a/docs/cli/cmd-options.mdx b/docs/cli/cmd-options.mdx index 901f18996d..6e5cce1290 100644 --- a/docs/cli/cmd-options.mdx +++ b/docs/cli/cmd-options.mdx @@ -700,3 +700,72 @@ Workflow type name. ## yes Confirm all prompts. + +### activity-type + +Command is applied to the all running activities with of this type. + +## task-queue + +If specified, activity will be assigned to this task-queue. + +## schedule-to-close-timeout + +Indicates how long the caller is willing to wait for an activity completion. +Limits how long retries will be attempted. + +## schedule-to-start-timeout + +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. + +## start-to-close-timeout + +Maximum time an activity is allowed to execute after being picked up by a worker. +This timeout is always retryable. + +## heartbeat-timeout + +Maximum permitted time between successful worker heartbeats. + +## retry-initial-interval + +Interval of the first retry. If retryBackoffCoefficient is 1.0 then it is used for all retries. + +## retry-maximum-interval + +Maximum interval between retries. Exponential backoff leads to interval increase. +This value is the cap of the increase. Default is 100x of the initial interval. + +## retry-backoff-coefficient + +Coefficient used to calculate the next retry interval. +The next retry interval is previous interval multiplied by the coefficient. +Must be 1 or larger. + +## retry-maximum-attempts + +Maximum number of attempts. When exceeded the retries stop even if not expired yet. +1 disables retries. 0 means unlimited (up to the timeouts). + +## match-all + +If set, all currently running activities will be unpaused. + +## reset-attempts + +Providing this flag will reset the number of attempts. + +## reset-heartbeat + +Providing this flag will reset the heartbeat details. + +## activity-jitter + +If set, the activity will start at a random time within the specified jitter duration. + +## keep-paused + +If this flag is provided and activity was paused, it will stay paused after reset. + From d7b5c507f74c308e40fab237767b142009591baf Mon Sep 17 00:00:00 2001 From: Yuri Date: Wed, 19 Feb 2025 10:04:43 -0800 Subject: [PATCH 2/2] Comments from Drew --- docs/cli/activity.mdx | 30 +++++++++++++++++++----------- docs/cli/cmd-options.mdx | 2 +- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index 9154449431..b01d49abb3 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -127,11 +127,12 @@ Use the following options to change the behavior of this command. ## update-options -The `temporal activity update-options` command updates options for an [Activity Execution](/activities#activity-execution). +The `temporal activity update-options` command lets you fix running activities by updating the options that were passed in by the activity's parent workflow. + The Activity must already be running on a valid [Workflow](/workflows). Updates are incremental, only changing the specified options. Either activity id or activity type must be provided. -If type is provided, and there are multiple pending activities of the provided type - all of them will be updated. -Command will return new activity options. +If activity type is provided, and there are multiple pending activities of the provided type - all of them will be updated. +The command will return the new activity options for an [Activity Execution](/activities#activity-execution).. Use the following options to change the behavior of this command. @@ -143,7 +144,7 @@ Routing options: - [--namespace](/cli/cmd-options#namespace) -Update specific options: +You can update the following Activity options: - [--task-queue](/cli/cmd-options#task-queue) - [--schedule-to-close-timeout](/cli/cmd-options#schedule-to-close-timeout) @@ -175,7 +176,8 @@ Other options: ## pause The `temporal activity pause` command pauses an [Activity Execution](/activities#activity-execution) specified by its ID or type. -If type is provided, and there are multiple pending activities of the provided type - all of them will be paused. +Pausing the activity can be undone by using the `temporal activity unpause` command. + Pausing an activity means: * If the activity is currently waiting for a retry or is running and subsequently fails, it will not be rescheduled until it is unpaused. * If the activity is already paused, calling this method will have no effect. @@ -183,8 +185,11 @@ Pausing an activity means: * If the activity is running and finishes with failure: * if there is no retry left - the activity will be completed. * if there are more retries left - the activity will be paused. -For long-running activities, activities in paused state will send a cancellation with "activity_paused" set to 'true' in response to 'RecordActivityTaskHeartbeat'. -The activity should respond to the cancellation accordingly. + +If activity type is provided, and there are multiple pending activities of the provided type - all of them will be paused. + +For long-running activities, activities in paused state will send a cancellation with "activity_paused" set to 'true' as a part of [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) response. +### activity-typeYou can choose how you'd like to handle this case in your activity. This command returns a `NotFound` error if there is no pending activity with the provided ID or type. Use the following options to change the behavior of this command. @@ -263,14 +268,17 @@ Other options: ## reset -The `temporal activity reset` command resets an [Activity Execution](/activities#activity-execution) specified by its ID or type. +The `temporal activity reset` command restarts a running [Activity Execution](/activities#activity-execution) specified by its ID or type. If there are multiple pending activities of the provided type - all of them will be reset. Resetting an activity means: -* number of attempts will be reset to 0. -* activity timeouts will be reset. -* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided, it will be scheduled immediately (* see 'jitter' flag), +* number of attempts will be reset to 0; +* activity timeouts will be reset; +* if the activity is waiting for retry, it will be scheduled immediately (* see 'jitter' flag); +* if the activity is currently executing, it will be reset once/if it completes with failure; +* if the activity is paused, it will be unpaused. If you want it to stay paused, you can pass --keep-paused flag; Command will fail with a `NotFound` error if there is no pending activity with the provided ID or type. +This may happen if the activity has already completed. Routing options: - [--activity-id](/cli/cmd-options#activity-id) diff --git a/docs/cli/cmd-options.mdx b/docs/cli/cmd-options.mdx index 6e5cce1290..fdf65e4ca4 100644 --- a/docs/cli/cmd-options.mdx +++ b/docs/cli/cmd-options.mdx @@ -701,7 +701,7 @@ Workflow type name. Confirm all prompts. -### activity-type +## activity-type Command is applied to the all running activities with of this type.