From 24990fc32f718160fe8fa1142b64d96603420d53 Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Fri, 10 Jan 2025 14:51:29 -0600 Subject: [PATCH] EDU-3427: Project Nova: Worker pg break out including redirects and anchors (#3270) * restucturing * adding in intros * running yarn format * changing task queue * redirects for activity task execution and task queue * redirects for workflow task and workflow task execution * changing redirects for nexus tasks * changing redirects for activity tasks * restructuring * redirecting task routing * worker versioning redirects * legacy worker versioning redirect * redirect sticky execution * redirects for worker entity * redirecting task definition * worker session and task queue redirects * updating anchors on workers page --------- Co-authored-by: Brian MacDonald --- docs/cli/task-queue.mdx | 6 +- docs/cli/workflow.mdx | 2 +- docs/develop/dotnet/core-application.mdx | 6 +- docs/develop/dotnet/failure-detection.mdx | 6 +- docs/develop/dotnet/temporal-client.mdx | 2 +- docs/develop/go/core-application.mdx | 6 +- docs/develop/go/failure-detection.mdx | 6 +- docs/develop/go/schedules.mdx | 2 +- docs/develop/go/sessions.mdx | 2 +- docs/develop/go/temporal-client.mdx | 6 +- docs/develop/go/versioning.mdx | 6 +- docs/develop/java/core-application.mdx | 8 +- docs/develop/java/failure-detection.mdx | 6 +- docs/develop/java/temporal-client.mdx | 2 +- docs/develop/java/versioning.mdx | 4 +- docs/develop/php/core-application.mdx | 6 +- docs/develop/php/failure-detection.mdx | 6 +- docs/develop/python/core-application.mdx | 6 +- docs/develop/python/failure-detection.mdx | 6 +- docs/develop/python/temporal-clients.mdx | 2 +- docs/develop/python/versioning.mdx | 4 +- docs/develop/typescript/core-application.mdx | 8 +- docs/develop/typescript/failure-detection.mdx | 10 +- docs/develop/typescript/temporal-clients.mdx | 2 +- docs/develop/typescript/testing-suite.mdx | 2 +- docs/develop/typescript/versioning.mdx | 6 +- docs/develop/worker-performance.mdx | 8 +- docs/encyclopedia/activities.mdx | 10 +- docs/encyclopedia/clusters.mdx | 2 +- .../detecting-activity-failures.mdx | 8 +- .../detecting-workflow-failures.mdx | 2 +- docs/encyclopedia/namespaces.mdx | 4 +- docs/encyclopedia/nexus-error-handling.mdx | 4 +- docs/encyclopedia/nexus-metrics.mdx | 2 +- docs/encyclopedia/nexus-operations.mdx | 8 +- docs/encyclopedia/nexus.mdx | 2 +- docs/encyclopedia/retry-policies.mdx | 6 +- .../encyclopedia/worker-versioning-legacy.mdx | 10 +- docs/encyclopedia/workers.mdx | 444 ------------------ .../encyclopedia/workers/sticky-execution.mdx | 30 ++ docs/encyclopedia/workers/task-queues.mdx | 143 ++++++ .../workers/task-routing-worker-sessions.mdx | 99 ++++ docs/encyclopedia/workers/tasks.mdx | 101 ++++ .../workers/worker-versioning.mdx | 36 ++ docs/encyclopedia/workers/workers.mdx | 150 ++++++ docs/encyclopedia/workflows.mdx | 8 +- docs/glossary.md | 18 +- .../cloud/account-setup/namespaces.mdx | 2 +- .../cloud/nexus/latency-availability.mdx | 2 +- docs/references/commands.mdx | 4 +- docs/references/errors.mdx | 62 +-- docs/references/events.mdx | 38 +- docs/tctl-v1/admin.mdx | 2 +- docs/tctl-v1/index.mdx | 2 +- docs/tctl-v1/taskqueue.mdx | 12 +- docs/tctl-v1/workflow.mdx | 12 +- docs/web-ui.mdx | 2 +- sidebars.js | 17 +- vercel.json | 12 +- 59 files changed, 760 insertions(+), 630 deletions(-) delete mode 100644 docs/encyclopedia/workers.mdx create mode 100644 docs/encyclopedia/workers/sticky-execution.mdx create mode 100644 docs/encyclopedia/workers/task-queues.mdx create mode 100644 docs/encyclopedia/workers/task-routing-worker-sessions.mdx create mode 100644 docs/encyclopedia/workers/tasks.mdx create mode 100644 docs/encyclopedia/workers/worker-versioning.mdx create mode 100644 docs/encyclopedia/workers/workers.mdx diff --git a/docs/cli/task-queue.mdx b/docs/cli/task-queue.mdx index 28b40ec6b8..15c4372f0e 100644 --- a/docs/cli/task-queue.mdx +++ b/docs/cli/task-queue.mdx @@ -15,12 +15,12 @@ tags: - Temporal CLI --- -Task Queue commands allow operations to be performed on [Task Queues](/workers#task-queue). +Task Queue commands allow operations to be performed on [Task Queues](/task-queue). To run a Task Queue command, run `temporal task-queue [command] [command options]` ## describe -The `temporal task-queue describe` command provides [poller](/develop/worker-performance#poller-count) information for a given [Task Queue](/workers#task-queue). +The `temporal task-queue describe` command provides [poller](/develop/worker-performance#poller-count) information for a given [Task Queue](/task-queue). The [Server](/clusters#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. @@ -73,7 +73,7 @@ Use the following options to change the behavior of this command. ## list-partition -The `temporal task-queue list-partition` command displays the partitions of a [Task Queue](/workers#task-queue), along with the matching node they are assigned to. +The `temporal task-queue list-partition` command displays the partitions of a [Task Queue](/task-queue), along with the matching node they are assigned to. Use the following options to change the command's behavior. diff --git a/docs/cli/workflow.mdx b/docs/cli/workflow.mdx index 0afb9c6fee..d7f7cd8d99 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -50,7 +50,7 @@ Workflow commands use this syntax: The `temporal workflow cancel` command cancels a [Workflow Execution](/workflows#workflow-execution). Canceling a running Workflow Execution records a [`WorkflowExecutionCancelRequested` event](/references/events#workflowexecutioncancelrequested) in the [Event History](/workflows#event-history). -A new [Workflow Task](/workers#workflow-task) will be scheduled, and the Workflow Execution performs cleanup work. +A new [Workflow Task](/tasks#workflow-task) will be scheduled, and the Workflow Execution performs cleanup work. `temporal workflow cancel --workflow-id=meaningful-business-id` diff --git a/docs/develop/dotnet/core-application.mdx b/docs/develop/dotnet/core-application.mdx index 2a43f3b9f4..6436c0edd7 100644 --- a/docs/develop/dotnet/core-application.mdx +++ b/docs/develop/dotnet/core-application.mdx @@ -230,7 +230,7 @@ A single argument is limited to a maximum size of 2 MB. And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB. Also, keep in mind that all Payload data is recorded in the [Workflow Execution Event History](/workflows#event-history) and large Event Histories can affect Worker performance. -This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/workers#workflow-task). +This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/tasks#workflow-task). Some SDKs require that you pass context objects, others do not. When it comes to your application data—that is, data that is serialized and encoded into a Payload—we recommend that you use a single object as an argument that wraps the application data passed to Activities. @@ -246,7 +246,7 @@ Technically this can be multiple parameters, but Temporal strongly encourages a Calls to spawn [Activity Executions](/activities#activity-execution) are written within a [Workflow Definition](/workflows#workflow-definition). The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command. -This results in the set of three [Activity Task](/workers#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. +This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. A single instance of the Activities implementation is shared across multiple simultaneous Activity invocations. Activity implementation code should be _idempotent_. @@ -293,7 +293,7 @@ The Activity result is the returned in the task from the `ExecuteActivityAsync` The [Worker Process](/workers#worker-process) is where Workflow Functions and Activity Functions are executed. - Each [Worker Entity](/workers#worker-entity) in the Worker Process must register the exact Workflow Types and Activity Types it may execute. -- Each Worker Entity must also associate itself with exactly one [Task Queue](/workers#task-queue). +- Each Worker Entity must also associate itself with exactly one [Task Queue](/task-queue). - Each Worker Entity polling the same Task Queue must be registered with the same Workflow Types and Activity Types. A [Worker Entity](/workers#worker-entity) is the component within a Worker Process that listens to a specific Task Queue. diff --git a/docs/develop/dotnet/failure-detection.mdx b/docs/develop/dotnet/failure-detection.mdx index 278d5c806e..16a91261a0 100644 --- a/docs/develop/dotnet/failure-detection.mdx +++ b/docs/develop/dotnet/failure-detection.mdx @@ -87,8 +87,8 @@ Each Activity Timeout controls the maximum duration of a different aspect of an The following Timeouts are available in the Activity Options. - **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution). -- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution). -- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. +- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution). +- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set. @@ -149,7 +149,7 @@ throw new ApplicationFailureException( An [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) is a ping from the [Worker Process](/workers#worker-process) that is executing the Activity to the [Temporal Service](/clusters). Each Heartbeat informs the Temporal Service that the [Activity Execution](/activities#activity-execution) is making progress and the Worker has not crashed. -If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. Heartbeats may not always be sent to the Temporal Service—they may be [throttled](/encyclopedia/detecting-activity-failures#throttling) by the Worker. diff --git a/docs/develop/dotnet/temporal-client.mdx b/docs/develop/dotnet/temporal-client.mdx index 39e4e84079..e4350fe3f1 100644 --- a/docs/develop/dotnet/temporal-client.mdx +++ b/docs/develop/dotnet/temporal-client.mdx @@ -93,7 +93,7 @@ A request to spawn a Workflow Execution causes the Temporal Service to create th The Temporal Service then creates the first Workflow Task, resulting in the first [WorkflowTaskScheduled](/references/events#workflowtaskscheduled) Event. To start a Workflow Execution in .NET, use either the `StartWorkflowAsync()` or `ExecuteWorkflowAsync()` methods in the Client. -You must set a [Workflow Id](/workflows#workflow-id) and [Task Queue](/workers#task-queue) in the `WorkflowOptions` given to the method. +You must set a [Workflow Id](/workflows#workflow-id) and [Task Queue](/task-queue) in the `WorkflowOptions` given to the method. ```csharp var result = await client.ExecuteWorkflowAsync( diff --git a/docs/develop/go/core-application.mdx b/docs/develop/go/core-application.mdx index 5233c4e9ba..cd31369fd2 100644 --- a/docs/develop/go/core-application.mdx +++ b/docs/develop/go/core-application.mdx @@ -454,7 +454,7 @@ A single argument is limited to a maximum size of 2 MB. And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB. Also, keep in mind that all Payload data is recorded in the [Workflow Execution Event History](/workflows#event-history) and large Event Histories can affect Worker performance. -This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/workers#workflow-task). +This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/tasks#workflow-task). {/* TODO link to gRPC limit section when available */} @@ -557,7 +557,7 @@ func main() { Calls to spawn [Activity Executions](/activities#activity-execution) are written within a [Workflow Definition](/workflows#workflow-definition). The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command. -This results in the set of three [Activity Task](/workers#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. +This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. A single instance of the Activities implementation is shared across multiple simultaneous Activity invocations. Activity implementation code should be _idempotent_. @@ -691,7 +691,7 @@ if err != nil { } ``` -- [What is a Task Queue](/workers#task-queue) +- [What is a Task Queue](/task-queue) #### ScheduleToCloseTimeout diff --git a/docs/develop/go/failure-detection.mdx b/docs/develop/go/failure-detection.mdx index 17656c7a16..4e33c2d336 100644 --- a/docs/develop/go/failure-detection.mdx +++ b/docs/develop/go/failure-detection.mdx @@ -97,8 +97,8 @@ Each Activity timeout controls the maximum duration of a different aspect of an The following timeouts are available in the Activity Options. - **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution). -- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution). -- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. +- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution). +- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set. @@ -189,7 +189,7 @@ return temporal.NewApplicationErrorWithOptions(fmt.Sprintf("Something bad happen An [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) is a ping from the [Worker Process](/workers#worker-process) that is executing the Activity to the [Temporal Service](/clusters). Each Heartbeat informs the Temporal Service that the [Activity Execution](/activities#activity-execution) is making progress and the Worker has not crashed. -If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. Heartbeats may not always be sent to the Temporal Service—they may be [throttled](/encyclopedia/detecting-activity-failures#throttling) by the Worker. diff --git a/docs/develop/go/schedules.mdx b/docs/develop/go/schedules.mdx index 3568941b99..b5d8d83d7f 100644 --- a/docs/develop/go/schedules.mdx +++ b/docs/develop/go/schedules.mdx @@ -81,7 +81,7 @@ The Temporal Service doesn't guarantee when this removal will happen. **How to Backfill a Schedule for a Workflow using the Go SDK.** -Backfilling a Schedule executes [Workflow Tasks](/workers#workflow-task) ahead of the Schedule's specified time range. +Backfilling a Schedule executes [Workflow Tasks](/tasks#workflow-task) ahead of the Schedule's specified time range. This is useful for executing a missed or delayed Action, or for testing the Workflow ahead of time. To backfill a Schedule in Go, use `Backfill()` on `ScheduleHandle`. diff --git a/docs/develop/go/sessions.mdx b/docs/develop/go/sessions.mdx index 7a675e44c1..e4e217a53f 100644 --- a/docs/develop/go/sessions.mdx +++ b/docs/develop/go/sessions.mdx @@ -24,7 +24,7 @@ This page shows how to do the following: ::: -A Worker Session is a feature that provides a straightforward API for [Task Routing](/workers#task-routing) to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. +A Worker Session is a feature that provides a straightforward API for [Task Routing](/task-routing) to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. ## Enable Worker Sessions {#enable-sessions} diff --git a/docs/develop/go/temporal-client.mdx b/docs/develop/go/temporal-client.mdx index 446de49ec5..99a7985aa8 100644 --- a/docs/develop/go/temporal-client.mdx +++ b/docs/develop/go/temporal-client.mdx @@ -244,7 +244,7 @@ workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, "Yo **How to set a Workflow's Task Queue using the Go SDK** -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/workers#task-queue). +In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name. @@ -266,7 +266,7 @@ if err != nil { ``` You can configure Task Queues that are host-specific, Worker-specific or Workflow-specific to distribute your application load. -For more information, refer to [Task Queues Processing Tuning](/develop/worker-performance#task-queues-processing-tuning) and [Worker Versioning](https://docs.temporal.io/workers#worker-versioning). +For more information, refer to [Task Queues Processing Tuning](/develop/worker-performance#task-queues-processing-tuning) and [Worker Versioning](https://docs.temporal.io/worker-versioning). ### Set custom Workflow Id {#workflow-id} @@ -719,7 +719,7 @@ You can start a Workflow Execution on a regular schedule with [the CronSchedule ### How to set a Workflow's Task Queue {#set-task-queue} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/workers#task-queue). +In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name. diff --git a/docs/develop/go/versioning.mdx b/docs/develop/go/versioning.mdx index 9794445580..6e341ff5e2 100644 --- a/docs/develop/go/versioning.mdx +++ b/docs/develop/go/versioning.mdx @@ -182,7 +182,7 @@ See the [Pre-release README](https://github.com/temporalio/temporal/blob/main/do ::: A Build ID corresponds to a deployment. If you don't already have one, we recommend a hash of the code--such as a Git SHA--combined with a human-readable timestamp. -To use [Worker Versioning](/workers#worker-versioning), you need to pass a Build ID to your Go Worker and opt in to Worker Versioning. +To use [Worker Versioning](/worker-versioning), you need to pass a Build ID to your Go Worker and opt in to Worker Versioning. ### Assign a Build ID to your Worker and opt in to Worker Versioning @@ -215,7 +215,7 @@ When configured to run on a separate Task Queue, they will default to using the If you want to override this behavior, you can specify your intent via the `VersioningIntent` field on the appropriate options struct. -{/* For more information refer to the [conceptual documentation](/workers#worker-versioning). */} +{/* For more information refer to the [conceptual documentation](/worker-versioning). */} For example, if you want an Activity to use the latest assignment rules rather than inheriting from its parent: @@ -244,7 +244,7 @@ err := workflow.NewContinueAsNewError(ctx, "WorkflowName") :::caution -This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning). +This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning). ::: diff --git a/docs/develop/java/core-application.mdx b/docs/develop/java/core-application.mdx index b7c07b1a98..8aeea58f60 100644 --- a/docs/develop/java/core-application.mdx +++ b/docs/develop/java/core-application.mdx @@ -327,7 +327,7 @@ A single argument is limited to a maximum size of 2 MB. And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB. Also, keep in mind that all Payload data is recorded in the [Workflow Execution Event History](/workflows#event-history) and large Event Histories can affect Worker performance. -This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/workers#workflow-task). +This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/tasks#workflow-task). {/* TODO link to gRPC limit section when available */} @@ -478,7 +478,7 @@ Systems such as Prometheus may ignore metrics with tags using unsupported charac Calls to spawn [Activity Executions](/activities#activity-execution) are written within a [Workflow Definition](/workflows#workflow-definition). The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command. -This results in the set of three [Activity Task](/workers#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. +This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. A single instance of the Activities implementation is shared across multiple simultaneous Activity invocations. Activity implementation code should be _idempotent_. @@ -930,7 +930,7 @@ Note that if you define options per-Activity Type options with `WorkflowImplemen .build(); ``` -See [Task Queue](/workers#task-queue) +See [Task Queue](/task-queue) #### RetryOptions @@ -1064,7 +1064,7 @@ When the download is complete, the download service potentially can complete the The [Worker Process](/workers#worker-process) is where Workflow Functions and Activity Functions are executed. - Each [Worker Entity](/workers#worker-entity) in the Worker Process must register the exact Workflow Types and Activity Types it may execute. -- Each Worker Entity must also associate itself with exactly one [Task Queue](/workers#task-queue). +- Each Worker Entity must also associate itself with exactly one [Task Queue](/task-queue). - Each Worker Entity polling the same Task Queue must be registered with the same Workflow Types and Activity Types. A [Worker Entity](/workers#worker-entity) is the component within a Worker Process that listens to a specific Task Queue. diff --git a/docs/develop/java/failure-detection.mdx b/docs/develop/java/failure-detection.mdx index dae0265b2f..4a68be1caf 100644 --- a/docs/develop/java/failure-detection.mdx +++ b/docs/develop/java/failure-detection.mdx @@ -96,8 +96,8 @@ Each Activity timeout controls the maximum duration of a different aspect of an The following timeouts are available in the Activity Options. - **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution). -- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution). -- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. +- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution). +- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set. @@ -218,7 +218,7 @@ throw ApplicationFailure.newFailureWithCauseAndDelay( An [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) is a ping from the [Worker Process](/workers#worker-process) that is executing the Activity to the [Temporal Service](/clusters). Each Heartbeat informs the Temporal Service that the [Activity Execution](/activities#activity-execution) is making progress and the Worker has not crashed. -If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. Heartbeats may not always be sent to the Temporal Service—they may be [throttled](/encyclopedia/detecting-activity-failures#throttling) by the Worker. diff --git a/docs/develop/java/temporal-client.mdx b/docs/develop/java/temporal-client.mdx index 63303e942e..6d5c9ae44e 100644 --- a/docs/develop/java/temporal-client.mdx +++ b/docs/develop/java/temporal-client.mdx @@ -307,7 +307,7 @@ You can start a Workflow Execution on a regular schedule by using [`setCronSched ### How to set a Workflow's Task Queue {#set-task-queue} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/workers#task-queue). +In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name. diff --git a/docs/develop/java/versioning.mdx b/docs/develop/java/versioning.mdx index 814fcb3815..d82d391faf 100644 --- a/docs/develop/java/versioning.mdx +++ b/docs/develop/java/versioning.mdx @@ -190,7 +190,7 @@ See the [Pre-release README](https://github.com/temporalio/temporal/blob/main/do ::: A Build ID corresponds to a deployment. If you don't already have one, we recommend a hash of the code--such as a Git SHA--combined with a human-readable timestamp. -To use [Worker Versioning](/workers#worker-versioning), you need to pass a Build ID to your Java Worker and opt in to Worker Versioning. +To use [Worker Versioning](/worker-versioning), you need to pass a Build ID to your Java Worker and opt in to Worker Versioning. ### Assign a Build ID to your Worker and opt in to Worker Versioning @@ -249,7 +249,7 @@ private final MyActivity activity = :::caution -This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning). +This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning). ::: diff --git a/docs/develop/php/core-application.mdx b/docs/develop/php/core-application.mdx index bf395d44b4..4f3fcb839b 100644 --- a/docs/develop/php/core-application.mdx +++ b/docs/develop/php/core-application.mdx @@ -176,7 +176,7 @@ A single argument is limited to a maximum size of 2 MB. And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB. Also, keep in mind that all Payload data is recorded in the [Workflow Execution Event History](/workflows#event-history) and large Event Histories can affect Worker performance. -This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/workers#workflow-task). +This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/tasks#workflow-task). {/* TODO link to gRPC limit section when available */} @@ -253,7 +253,7 @@ The `#[ActivityInterface("file_activities.")]` is an attribute that tells the PH Calls to spawn [Activity Executions](/activities#activity-execution) are written within a [Workflow Definition](/workflows#workflow-definition). The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command. -This results in the set of three [Activity Task](/workers#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. +This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. A single instance of the Activities implementation is shared across multiple simultaneous Activity invocations. Activity implementation code should be _idempotent_. @@ -380,7 +380,7 @@ $greetingActivity = Workflow::newActivityStub( The [Worker Process](/workers#worker-process) is where Workflow Functions and Activity Functions are executed. - Each [Worker Entity](/workers#worker-entity) in the Worker Process must register the exact Workflow Types and Activity Types it may execute. -- Each Worker Entity must also associate itself with exactly one [Task Queue](/workers#task-queue). +- Each Worker Entity must also associate itself with exactly one [Task Queue](/task-queue). - Each Worker Entity polling the same Task Queue must be registered with the same Workflow Types and Activity Types. A [Worker Entity](/workers#worker-entity) is the component within a Worker Process that listens to a specific Task Queue. diff --git a/docs/develop/php/failure-detection.mdx b/docs/develop/php/failure-detection.mdx index e2480d67e9..cffc115c9a 100644 --- a/docs/develop/php/failure-detection.mdx +++ b/docs/develop/php/failure-detection.mdx @@ -74,8 +74,8 @@ Each Activity timeout controls the maximum duration of a different aspect of an The following timeouts are available in the Activity Options. - **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution). -- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution). -- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. +- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution). +- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set. @@ -154,7 +154,7 @@ throw new \Temporal\Exception\Failure\ApplicationFailure( An [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) is a ping from the [Worker Process](/workers#worker-process) that is executing the Activity to the [Temporal Service](/clusters). Each Heartbeat informs the Temporal Service that the [Activity Execution](/activities#activity-execution) is making progress and the Worker has not crashed. -If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. Heartbeats may not always be sent to the Temporal Service—they may be [throttled](/encyclopedia/detecting-activity-failures#throttling) by the Worker. diff --git a/docs/develop/python/core-application.mdx b/docs/develop/python/core-application.mdx index 60caf5314c..24d8e44f6c 100644 --- a/docs/develop/python/core-application.mdx +++ b/docs/develop/python/core-application.mdx @@ -249,7 +249,7 @@ A single argument is limited to a maximum size of 2 MB. And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB. Also, keep in mind that all Payload data is recorded in the [Workflow Execution Event History](/workflows#event-history) and large Event Histories can affect Worker performance. -This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/workers#workflow-task). +This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/tasks#workflow-task). {/* TODO link to gRPC limit section when available */} @@ -335,7 +335,7 @@ async def your_activity(input: YourParams) -> str: Calls to spawn [Activity Executions](/activities#activity-execution) are written within a [Workflow Definition](/workflows#workflow-definition). The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command. -This results in the set of three [Activity Task](/workers#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. +This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. A single instance of the Activities implementation is shared across multiple simultaneous Activity invocations. Activity implementation code should be _idempotent_. @@ -455,7 +455,7 @@ class YourWorkflow: The [Worker Process](/workers#worker-process) is where Workflow Functions and Activity Functions are executed. - Each [Worker Entity](/workers#worker-entity) in the Worker Process must register the exact Workflow Types and Activity Types it may execute. -- Each Worker Entity must also associate itself with exactly one [Task Queue](/workers#task-queue). +- Each Worker Entity must also associate itself with exactly one [Task Queue](/task-queue). - Each Worker Entity polling the same Task Queue must be registered with the same Workflow Types and Activity Types. A [Worker Entity](/workers#worker-entity) is the component within a Worker Process that listens to a specific Task Queue. diff --git a/docs/develop/python/failure-detection.mdx b/docs/develop/python/failure-detection.mdx index e173aec792..f15474f5fb 100644 --- a/docs/develop/python/failure-detection.mdx +++ b/docs/develop/python/failure-detection.mdx @@ -110,8 +110,8 @@ Each Activity timeout controls the maximum duration of a different aspect of an The following timeouts are available in the Activity Options. - **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution). -- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution). -- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. +- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution). +- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set. @@ -209,7 +209,7 @@ async def my_activity(input: MyActivityInput): An [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) is a ping from the [Worker Process](/workers#worker-process) that is executing the Activity to the [Temporal Service](/clusters). Each Heartbeat informs the Temporal Service that the [Activity Execution](/activities#activity-execution) is making progress and the Worker has not crashed. -If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered failed and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. Heartbeats may not always be sent to the Temporal Service—they may be [throttled](/encyclopedia/detecting-activity-failures#throttling) by the Worker. diff --git a/docs/develop/python/temporal-clients.mdx b/docs/develop/python/temporal-clients.mdx index f5d936f4fa..e506a2f628 100644 --- a/docs/develop/python/temporal-clients.mdx +++ b/docs/develop/python/temporal-clients.mdx @@ -232,7 +232,7 @@ if __name__ == "__main__": **How to set a Workflow's Task Queue using the Python SDK** -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/workers#task-queue). +In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name. diff --git a/docs/develop/python/versioning.mdx b/docs/develop/python/versioning.mdx index de7dcfae2c..53050c72dc 100644 --- a/docs/develop/python/versioning.mdx +++ b/docs/develop/python/versioning.mdx @@ -229,7 +229,7 @@ See the [Pre-release README](https://github.com/temporalio/temporal/blob/main/do ::: A Build ID corresponds to a deployment. If you don't already have one, we recommend a hash of the code--such as a Git SHA--combined with a human-readable timestamp. -To use [Worker Versioning](/workers#worker-versioning), you need to pass a Build ID to your Java Worker and opt in to Worker Versioning. +To use [Worker Versioning](/worker-versioning), you need to pass a Build ID to your Java Worker and opt in to Worker Versioning. ### Assign a Build ID to your Worker and opt in to Worker Versioning @@ -285,7 +285,7 @@ await workflow.execute_activity( :::caution -This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning). +This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning). ::: diff --git a/docs/develop/typescript/core-application.mdx b/docs/develop/typescript/core-application.mdx index 17b02439ff..ae745a2e12 100644 --- a/docs/develop/typescript/core-application.mdx +++ b/docs/develop/typescript/core-application.mdx @@ -476,7 +476,7 @@ A single argument is limited to a maximum size of 2 MB. And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB. Also, keep in mind that all Payload data is recorded in the [Workflow Execution Event History](/workflows#event-history) and large Event Histories can affect Worker performance. -This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/workers#workflow-task). +This is because the entire Event History could be transferred to a Worker Process with a [Workflow Task](/tasks#workflow-task). {/* TODO link to gRPC limit section when available */} @@ -679,7 +679,7 @@ ApplicationFailure: Activity function actC is not registered on this Worker, ava Calls to spawn [Activity Executions](/activities#activity-execution) are written within a [Workflow Definition](/workflows#workflow-definition). The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command. -This results in the set of three [Activity Task](/workers#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. +This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and ActivityTask[Closed])in your Workflow Execution Event History. A single instance of the Activities implementation is shared across multiple simultaneous Activity invocations. Activity implementation code should be _idempotent_. @@ -743,7 +743,7 @@ The `proxyActivities()` returns an object that calls the Activities in the funct The [Worker Process](/workers#worker-process) is where Workflow Functions and Activity Functions are executed. - Each [Worker Entity](/workers#worker-entity) in the Worker Process must register the exact Workflow Types and Activity Types it may execute. -- Each Worker Entity must also associate itself with exactly one [Task Queue](/workers#task-queue). +- Each Worker Entity must also associate itself with exactly one [Task Queue](/task-queue). - Each Worker Entity polling the same Task Queue must be registered with the same Workflow Types and Activity Types. A [Worker Entity](/workers#worker-entity) is the component within a Worker Process that listens to a specific Task Queue. @@ -1028,7 +1028,7 @@ Workflow Execution run in a separate V8 isolate context in order to provide a [d ### How to set a Workflow's Task Queue {#set-task-queue} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/workers#task-queue). +In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name. diff --git a/docs/develop/typescript/failure-detection.mdx b/docs/develop/typescript/failure-detection.mdx index 5587d49aa7..7b0cb13ee3 100644 --- a/docs/develop/typescript/failure-detection.mdx +++ b/docs/develop/typescript/failure-detection.mdx @@ -86,9 +86,9 @@ Each Activity Timeout controls the maximum duration of a different aspect of an The following Timeouts are available in the Activity Options: -- **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the entire [Activity Execution](/activities#activity-execution), from when the [Activity Task](/workers#activity-task) is initially scheduled by the Workflow to when the server receives a sucessful completion for that Activity Task -- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution), from when the Activity Task Execution gets polled by a [Worker](/workers#worker) to when the server receives a successfull completion for that Activity Task -- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is initially scheduled by the Workflow to when a [Worker](/workers#worker) polls the Activity Task Execution +- **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout):** is the maximum amount of time allowed for the entire [Activity Execution](/activities#activity-execution), from when the [Activity Task](/tasks#activity-task) is initially scheduled by the Workflow to when the server receives a sucessful completion for that Activity Task +- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout):** is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution), from when the Activity Task Execution gets polled by a [Worker](/workers#worker) to when the server receives a successfull completion for that Activity Task +- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is initially scheduled by the Workflow to when a [Worker](/workers#worker) polls the Activity Task Execution An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set. @@ -148,7 +148,7 @@ throw ApplicationFailure.create({ An [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) is a ping from the [Worker Process](/workers#worker-process) that is executing the Activity to the [Temporal Service](/clusters). Each Heartbeat informs the Temporal Service that the [Activity Execution](/activities#activity-execution) is making progress and the Worker has not crashed. -If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered as timed out and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Service does not receive a Heartbeat within a [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) time period, the Activity will be considered as timed out and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. Activity Cancellations are delivered to Activities from the Temporal Service when they Heartbeat. Activities that don't Heartbeat can't get notified of Cancellation requests. @@ -192,7 +192,7 @@ export async function myActivity(): Promise { **How to set a Heartbeat Timeout using the Temporal TypeScript SDK** A [Heartbeat Timeout](/encyclopedia/detecting-activity-failures#heartbeat-timeout) works in conjunction with [Activity Heartbeats](/encyclopedia/detecting-activity-failures#activity-heartbeat). -If the Temporal Server doesn't receive a Heartbeat before expiration of the Heartbeat Timeout, the Activity is considered as timed out and another [Activity Task Execution](/workers#activity-task-execution) may be scheduled according to the Retry Policy. +If the Temporal Server doesn't receive a Heartbeat before expiration of the Heartbeat Timeout, the Activity is considered as timed out and another [Activity Task Execution](/tasks#activity-task-execution) may be scheduled according to the Retry Policy. To set an Activity's Heartbeat Timeout in TypeScript, set the [`ActivityOptions.heartbeatTimeout`](https://typescript.temporal.io/api/interfaces/common.ActivityOptions#heartbeattimeout) property when creating the corresponding Activity proxy functions using the [`proxyActivities()`](https://typescript.temporal.io/api/namespaces/workflow#proxyactivities) API. diff --git a/docs/develop/typescript/temporal-clients.mdx b/docs/develop/typescript/temporal-clients.mdx index bf4abe7095..caa5548706 100644 --- a/docs/develop/typescript/temporal-clients.mdx +++ b/docs/develop/typescript/temporal-clients.mdx @@ -173,7 +173,7 @@ Workflow Execution run in a separate V8 isolate context in order to provide a [d ### Set a Workflow's Task Queue {#set-task-queue} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/workers#task-queue). +In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name. diff --git a/docs/develop/typescript/testing-suite.mdx b/docs/develop/typescript/testing-suite.mdx index 93f735b07f..0582f592d8 100644 --- a/docs/develop/typescript/testing-suite.mdx +++ b/docs/develop/typescript/testing-suite.mdx @@ -487,7 +487,7 @@ The `assert` method is available in Python and TypeScript. The Node.js [`assert`](https://nodejs.org/api/assert.html) module is included in Workflow bundles. -By default, a failed `assert` statement throws `AssertionError`, which causes a [Workflow Task](/workers#workflow-task) to fail and be indefinitely retried. +By default, a failed `assert` statement throws `AssertionError`, which causes a [Workflow Task](/tasks#workflow-task) to fail and be indefinitely retried. To prevent this behavior, use [`workflowInterceptorModules`](https://typescript.temporal.io/api/namespaces/testing/#workflowinterceptormodules) from `@temporalio/testing`. These interceptors catch an `AssertionError` and turn it into an `ApplicationFailure` that fails the entire Workflow Execution (not just the Workflow Task). diff --git a/docs/develop/typescript/versioning.mdx b/docs/develop/typescript/versioning.mdx index ff3225f346..406b4e7f8e 100644 --- a/docs/develop/typescript/versioning.mdx +++ b/docs/develop/typescript/versioning.mdx @@ -254,7 +254,7 @@ See the [Pre-release README](https://github.com/temporalio/temporal/blob/main/do ::: A Build ID corresponds to a deployment. If you don't already have one, we recommend a hash of the code--such as a Git SHA--combined with a human-readable timestamp. -To use [Worker Versioning](/workers#worker-versioning), you need to pass a Build ID to your Typescript Worker and opt in to Worker Versioning. +To use [Worker Versioning](/worker-versioning), you need to pass a Build ID to your Typescript Worker and opt in to Worker Versioning. ### Assign a Build ID to your Worker and opt in to Worker Versioning @@ -294,7 +294,7 @@ When configured to run on a separate task queue, they will default to using the If you want to override this behavior, you can specify your intent via the `versioningIntent` field available on the options object for each of these commands. -{/* For more information refer to the [conceptual documentation](/workers#worker-versioning). */} +{/* For more information refer to the [conceptual documentation](/worker-versioning). */} For example, if you want an Activity to use the latest assignment rules rather than inheriting from its parent: @@ -311,7 +311,7 @@ const { echo } = proxyActivities({ :::caution -This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning). +This section is for a previous Worker Versioning API that is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning). ::: diff --git a/docs/develop/worker-performance.mdx b/docs/develop/worker-performance.mdx index 37779ef317..6bbb60583a 100644 --- a/docs/develop/worker-performance.mdx +++ b/docs/develop/worker-performance.mdx @@ -451,7 +451,7 @@ The age is based on the creation time of the Task at the head of the queue. You can rely on both these counts when making scaling decisions. -Please note: [Sticky queues](https://docs.temporal.io/workers#sticky-execution) will affect these values, but only for a few seconds. +Please note: [Sticky queues](https://docs.temporal.io/sticky-execution) will affect these values, but only for a few seconds. That's because Tasks sent to Sticky queues are not included in the returned values for `ApproximateBacklogCount` and `ApproximateBacklogAge`. Inaccuracies diminish as the backlog grows. @@ -483,11 +483,11 @@ While individual `add` and `dispatch` rates may be inaccurate due to Eager and S ## Evaluate Task Queue performance {#evaluate-worker-loads} -A [Task Queue](https://docs.temporal.io/workers#task-queue) is a lightweight, dynamically allocated queue. -[Worker Entities](https://docs.temporal.io/workers#worker-entity) poll the queue for [Tasks](https://docs.temporal.io/workers#task) and retrieve Tasks to work on. +A [Task Queue](https://docs.temporal.io/task-queue) is a lightweight, dynamically allocated queue. +[Worker Entities](https://docs.temporal.io/workers#worker-entity) poll the queue for [Tasks](https://docs.temporal.io/tasks#task) and retrieve Tasks to work on. Tasks are contexts that a Worker progresses using a specific Workflow Execution, Activity Execution, or a Nexus Task Execution. Each Task Queue type offers its Tasks to compatible Workers for Task completion. -The Temporal Service dynamically creates different [Task Queue types](/workers#task-queue) including Activity Task Queues, Workflow Task Queues, and Nexus Task Queues. +The Temporal Service dynamically creates different [Task Queue types](/task-queue) including Activity Task Queues, Workflow Task Queues, and Nexus Task Queues. With an accurate estimate of backlog Tasks, you can determine the optimal number of Workers to deploy. Balance your Worker count with the number of Tasks to achieve the best performance. diff --git a/docs/encyclopedia/activities.mdx b/docs/encyclopedia/activities.mdx index e2f7007472..9d9f335794 100644 --- a/docs/encyclopedia/activities.mdx +++ b/docs/encyclopedia/activities.mdx @@ -34,7 +34,7 @@ For other Activity-related Events, see [Activity Events](/workflows#activity-eve ## What is an Activity Definition? {#activity-definition} -An Activity Definition is the code that defines the constraints of an [Activity Task Execution](/workers#activity-task-execution). +An Activity Definition is the code that defines the constraints of an [Activity Task Execution](/tasks#activity-task-execution). - [How to develop an Activity Definition using the Go SDK](/develop/go/core-application#activity-definition) - [How to develop an Activity Definition using the Java SDK](/develop/java/core-application#develop-activities) @@ -43,7 +43,7 @@ An Activity Definition is the code that defines the constraints of an [Activity - [How to develop an Activity Definition using the TypeScript SDK](/develop/typescript/core-application#develop-activities) - [How to develop an Activity Definition using the .NET SDK](/develop/dotnet/core-application#develop-activity) -The term 'Activity Definition' is used to refer to the full set of primitives in any given language SDK that provides an access point to an Activity Function Definition——the method or function that is invoked for an [Activity Task Execution](/workers#activity-task-execution). +The term 'Activity Definition' is used to refer to the full set of primitives in any given language SDK that provides an access point to an Activity Function Definition——the method or function that is invoked for an [Activity Task Execution](/tasks#activity-task-execution). Therefore, the terms Activity Function and Activity Method refer to the source of an instance of an execution. Activity Definitions are named and referenced in code by their [Activity Type](#activity-type). @@ -74,7 +74,7 @@ By design, completed Activities will not re-execute as part of a [Workflow Repla ::: -An Activity is idempotent if multiple [Activity Task Executions](/workers#activity-task-execution) do not change the state of the system beyond the first Activity Task Execution. +An Activity is idempotent if multiple [Activity Task Executions](/tasks#activity-task-execution) do not change the state of the system beyond the first Activity Task Execution. We recommend using idempotency keys for critical side effects. @@ -119,7 +119,7 @@ Activity Types are scoped through Task Queues. ## What is an Activity Execution? {#activity-execution} -An Activity Execution is the full chain of [Activity Task Executions](/workers#activity-task-execution). +An Activity Execution is the full chain of [Activity Task Executions](/tasks#activity-task-execution). - [How to start an Activity Execution using the Go SDK](/develop/go/core-application#activity-execution) - [How to start an Activity Execution using the Java SDK](/develop/java/core-application#activity-execution) @@ -258,7 +258,7 @@ In the second scenario, the failure is retried sooner. This is particularly help #### What is a Task Token? {#task-token} -A Task Token is a unique identifier for an [Activity Task Execution](/workers#activity-task-execution). +A Task Token is a unique identifier for an [Activity Task Execution](/tasks#activity-task-execution). [Asynchronous Activity Completion](#asynchronous-activity-completion) calls take either of the following as arguments: diff --git a/docs/encyclopedia/clusters.mdx b/docs/encyclopedia/clusters.mdx index 2611bbfc76..c8e86a8d93 100644 --- a/docs/encyclopedia/clusters.mdx +++ b/docs/encyclopedia/clusters.mdx @@ -170,7 +170,7 @@ Each History Shard maintains the Workflow Execution Event History, Workflow Exec ### What is a Matching Service? {#matching-service} -The Matching Service is responsible for hosting user-facing [Task Queues](/workers#task-queue) for Task dispatching. +The Matching Service is responsible for hosting user-facing [Task Queues](/task-queue) for Task dispatching.
diff --git a/docs/encyclopedia/detecting-activity-failures.mdx b/docs/encyclopedia/detecting-activity-failures.mdx index 13edbc80af..20bc62fb7f 100644 --- a/docs/encyclopedia/detecting-activity-failures.mdx +++ b/docs/encyclopedia/detecting-activity-failures.mdx @@ -29,7 +29,7 @@ A Workflow can detect different kinds of Activity Execution failures through the **What is a Schedule-To-Start Timeout in Temporal?** -A Schedule-To-Start Timeout is the maximum amount of time that is allowed from when an [Activity Task](/workers#activity-task) is scheduled (that is, placed in a Task Queue) to when a [Worker](/workers#worker) starts (that is, picks up from the Task Queue) that Activity Task. +A Schedule-To-Start Timeout is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled (that is, placed in a Task Queue) to when a [Worker](/workers#worker) starts (that is, picks up from the Task Queue) that Activity Task. In other words, it's a limit for how long an Activity Task can be enqueued. @@ -73,7 +73,7 @@ In most cases, we recommend monitoring the `temporal_activity_schedule_to_start_ **What is a Start-To-Close Timeout in Temporal?** -A Start-To-Close Timeout is the maximum time allowed for a single [Activity Task Execution](/workers#activity-task-execution). +A Start-To-Close Timeout is the maximum time allowed for a single [Activity Task Execution](/tasks#activity-task-execution). @@ -121,7 +121,7 @@ If this timeout is reached, the following actions occur: **What is a Schedule-To-Close Timeout in Temporal?** -A Schedule-To-Close Timeout is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution), from when the first [Activity Task](/workers#activity-task) is scheduled to when the last Activity Task, in the chain of Activity Tasks that make up the Activity Execution, reaches a Closed status. +A Schedule-To-Close Timeout is the maximum amount of time allowed for the overall [Activity Execution](/activities#activity-execution), from when the first [Activity Task](/tasks#activity-task) is scheduled to when the last Activity Task, in the chain of Activity Tasks that make up the Activity Execution, reaches a Closed status. @@ -183,7 +183,7 @@ For _long-running_ Activities, we recommend using a relatively short Heartbeat T That way if a Worker fails it can be handled in a timely manner. A Heartbeat can include an application layer payload that can be used to _save_ Activity Execution progress. -If an [Activity Task Execution](/workers#activity-task-execution) times out due to a missed Heartbeat, the next Activity Task can access and continue with that payload. +If an [Activity Task Execution](/tasks#activity-task-execution) times out due to a missed Heartbeat, the next Activity Task can access and continue with that payload. Activity Cancellations are delivered to Activities from the Temporal Service when they Heartbeat. Activities that don't Heartbeat can't receive a Cancellation. Heartbeat throttling may lead to Cancellation getting delivered later than expected. diff --git a/docs/encyclopedia/detecting-workflow-failures.mdx b/docs/encyclopedia/detecting-workflow-failures.mdx index f839bc94bd..45824649bc 100644 --- a/docs/encyclopedia/detecting-workflow-failures.mdx +++ b/docs/encyclopedia/detecting-workflow-failures.mdx @@ -72,7 +72,7 @@ If the Workflow Run Timeout is reached, the Workflow Execution will be Timed Out **What is a Workflow Task Timeout in Temporal?** -A Workflow Task Timeout is the maximum amount of time allowed for a [Worker](/workers#worker) to execute a [Workflow Task](/workers#workflow-task) after the Worker has pulled that Workflow Task from the [Task Queue](/workers#task-queue). +A Workflow Task Timeout is the maximum amount of time allowed for a [Worker](/workers#worker) to execute a [Workflow Task](/tasks#workflow-task) after the Worker has pulled that Workflow Task from the [Task Queue](/task-queue). diff --git a/docs/encyclopedia/namespaces.mdx b/docs/encyclopedia/namespaces.mdx index 03468b2b29..8744255bdf 100644 --- a/docs/encyclopedia/namespaces.mdx +++ b/docs/encyclopedia/namespaces.mdx @@ -28,7 +28,7 @@ Namespaces are created on the Temporal Service, and provide a range of controls See the [Registration](#registration) section for details. - Namespaces created on self-hosted Temporal Service are case-sensitive. For example, `foo` and `Foo` are two different Namespaces. On Temporal Cloud, Namespaces are case-insensitive, and we recommend using lowercase for Namespace names to avoid potential issues. -- **Membership:** [Task Queue](/workers#task-queue) names and [Workflow Ids](/workflows#workflow-id) must all correspond to a specific Namespace. +- **Membership:** [Task Queue](/task-queue) names and [Workflow Ids](/workflows#workflow-id) must all correspond to a specific Namespace. For example, when a Workflow Execution is spawned, it does so within a specific Namespace. - **Uniqueness:** Temporal guarantees a unique Workflow Id within a Namespace. Workflow Executions may have the same Workflow Id if they are in different Namespaces. @@ -125,7 +125,7 @@ For a failover to be successful, Worker Processes must be polling for Tasks for A Global Namespace has a failover version. Because a failover can be triggered from any Cluster, the failover version prevents certain conflicts from occurring if a failover is mistakenly triggered simultaneously on two Clusters. -Only the active Cluster dispatches [Tasks](/workers#task); however, certain conflicts are possible. +Only the active Cluster dispatches [Tasks](/tasks#task); however, certain conflicts are possible. Unlike regular Namespaces, which provide at-most-once semantics for an Activity Execution, Global Namespaces can support only at-least-once semantics (see [Conflict resolution](/clusters#conflict-resolution)). Worker Processes on the standby Clusters are idle until a failover occurs and their Cluster becomes active. diff --git a/docs/encyclopedia/nexus-error-handling.mdx b/docs/encyclopedia/nexus-error-handling.mdx index 8f8718be73..76c6357a52 100644 --- a/docs/encyclopedia/nexus-error-handling.mdx +++ b/docs/encyclopedia/nexus-error-handling.mdx @@ -31,7 +31,7 @@ Nexus handlers run in a Temporal Worker and use Temporal SDK builder functions l Nexus handlers may return [different error types](/references/failures#nexus-errors). Nexus Operations can end up in [completed](/references/events#nexusoperationcompleted), [failed](/references/events#nexusoperationfailed), [canceled](/references/events#nexusoperationcanceled), and [timed out](/references/events#nexusoperationtimedout) states. -The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/workers#nexus-task) that a Nexus handler is responsible for processing. +The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/tasks#nexus-task) that a Nexus handler is responsible for processing. It creates a Nexus Task to start an Operation and may create additional Nexus Tasks, for example to cancel a long-running [asynchronous Operation](/nexus/operations#asynchronous-operation-lifecycle). By default, Nexus handler errors are considered retryable, unless specified below: @@ -45,7 +45,7 @@ For example, if an unknown error is returned from a Nexus handler it will be cla When an error is received by the caller's Nexus Machinery: - If a [non-retryable error](/references/failures#non-retryable-nexus-errors) is returned, the caller Workflow will have a [NexusOperationFailed](/references/events#nexusoperationfailed) event added to its Workflow History. -- If a [retryable error](/references/failures#retryable-nexus-errors) is returned, the Nexus Machinery will automatically retry the [Nexus Task](/workers#nexus-task), as discussed in [automatic retries](/nexus/operations#automatic-retries). +- If a [retryable error](/references/failures#retryable-nexus-errors) is returned, the Nexus Machinery will automatically retry the [Nexus Task](/tasks#nexus-task), as discussed in [automatic retries](/nexus/operations#automatic-retries). These errors are visible to the caller Workflow as part of integrated execution debugging in [Pending Operations](/nexus/execution-debugging/#pending-operations). :::tip diff --git a/docs/encyclopedia/nexus-metrics.mdx b/docs/encyclopedia/nexus-metrics.mdx index b54265c7f1..9635bdb5df 100644 --- a/docs/encyclopedia/nexus-metrics.mdx +++ b/docs/encyclopedia/nexus-metrics.mdx @@ -42,7 +42,7 @@ Nexus provides SDK metrics, Cloud metrics, and OSS Cluster metrics in addition t - Caller Namespace - RespondWorkflowTaskCompleted \- schedule a Nexus Operation. - Handler Namespace - - PollNexusTaskQueue \- get a [Nexus Task](/workers#nexus-task) to process, for example to start a Nexus Operation. + - PollNexusTaskQueue \- get a [Nexus Task](/tasks#nexus-task) to process, for example to start a Nexus Operation. - RespondNexusTaskCompleted \- report the Nexus Task was successful. - RespondNexusTaskFailed \- report the Nexus Task failed. diff --git a/docs/encyclopedia/nexus-operations.mdx b/docs/encyclopedia/nexus-operations.mdx index b6a2b58bf6..998831e3b4 100644 --- a/docs/encyclopedia/nexus-operations.mdx +++ b/docs/encyclopedia/nexus-operations.mdx @@ -77,7 +77,7 @@ The lifecycle for a synchronous Nexus Operation, for example to Signal or Query 1. Caller Namespace records a [NexusOperationScheduled](/references/events#nexusoperationscheduled) event in the caller's Workflow History. 1. Caller Nexus Machinery makes a Nexus call to start a Nexus Operation. 1. Handler Nexus Machinery receives the Nexus request and sync matches to a handler Worker. -1. Handler Worker gets a [Nexus Task](/workers#nexus-task) to start a Nexus Operation, by polling the Nexus Endpoint's target Task Queue. +1. Handler Worker gets a [Nexus Task](/tasks#nexus-task) to start a Nexus Operation, by polling the Nexus Endpoint's target Task Queue. 1. Handler processes the Nexus Task, using the Temporal SDK **New-Sync-Operation**. 1. Handler responds to it's Namespace gRPC endpoint with the Operation result. 1. Caller Namespace records the result in the caller's Workflow history as a Nexus event, for example [Completed](/references/events#nexusoperationcompleted) or [Failed](/references/events#nexusoperationfailed). @@ -106,7 +106,7 @@ The lifecycle of an asynchronous Nexus Operation, with differences between the s 1. Caller Namespace records a [NexusOperationScheduled](/references/events#nexusoperationscheduled) event in the caller Workflow's History. 1. Caller Nexus Machinery makes a Nexus RPC to start a Nexus Operation. 1. Handler Nexus Machinery receives the Nexus request and sync matches to a handler Worker. -1. Handler Worker gets a [Nexus Task](/workers#nexus-task) to start a Nexus Operation, by polling the Nexus Endpoint's target Task Queue. +1. Handler Worker gets a [Nexus Task](/tasks#nexus-task) to start a Nexus Operation, by polling the Nexus Endpoint's target Task Queue. 1. Handler processes the Nexus Task, using the Temporal SDK **New-Workflow-Run-Operation**. 1. Handler responds to it's Namespace gRPC endpoint with the **start Operation response**. 1. Caller Namespace records the response in the caller's Workflow history as a Nexus event, for example **[NexusOperationStarted](/references/events#nexusoperationstarted)**. @@ -136,7 +136,7 @@ Nexus Machinery on both sides handles the cross-namepace communication. For example, when you execute a Nexus Operation in a caller Workflow the following Namespace gRPC calls are made: 1. **RespondWorkflowTaskCompleted ([ScheduleNexusOperation command](/references/commands#schedulenexusoperation)) is used by the caller Worker to schedule a Nexus Operation, which atomically hands off execution to the caller's Nexus Machinery. -1. **PollNexusTaskQueue** is used by the handler Worker to receive a [Nexus Task](/workers#nexus-task) to process, for example to start a Nexus Operation. +1. **PollNexusTaskQueue** is used by the handler Worker to receive a [Nexus Task](/tasks#nexus-task) to process, for example to start a Nexus Operation. 1. **RespondNexusTaskCompleted** or **RespondNexusTaskFailed** is used by the handler Worker to return the Nexus Task result. When asked to start a Nexus Operation, the Nexus handler decides if the Operation will be synchronous or asynchronous. 1. This is typically a static decision based on the [Temporal SDK builder function used](#sdk-support). @@ -173,7 +173,7 @@ See [errors in Nexus handlers](/nexus/error-handling#errors-in-nexus-handlers) t The Nexus Machinery provides reliable execution with at-least-once execution semantics for a Nexus Operation, until the caller's Schedule-to-Close-Timeout is exceeded, at which time the overall Nexus Operation times out. -The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/workers#nexus-task) that a Nexus handler is responsible for processing. +The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/tasks#nexus-task) that a Nexus handler is responsible for processing. If a Nexus handler times out or returns a non-retryable Nexus error, then the Nexus Machinery will retry the Nexus request to provide at-least-once execution. This means it's possible for your Nexus handler to be invoked multiple times for a given Nexus Operation. diff --git a/docs/encyclopedia/nexus.mdx b/docs/encyclopedia/nexus.mdx index cd8ee5c980..d8b7acf65b 100644 --- a/docs/encyclopedia/nexus.mdx +++ b/docs/encyclopedia/nexus.mdx @@ -57,7 +57,7 @@ Nexus Operations can be implemented with Temporal primitives, like Workflows, or Nexus uses the Temporal queue-based Worker architecture and built-in Nexus Machinery to ensure reliable execution of Nexus Operations. If a Nexus Service is down, a caller Workflow can continue to schedule Nexus Operations and they will be processed when the service is up. -Nexus handler Workers poll the Endpoint's target Namespace and Task Queue for [Nexus Tasks](/workers#nexus-task) to process. +Nexus handler Workers poll the Endpoint's target Namespace and Task Queue for [Nexus Tasks](/tasks#nexus-task) to process. Workers authenticate to their Namespace's gRPC endpoint with supported methods including mTLS client certificates or API Keys in Temporal Cloud. ![NexusYourCloud](/img/nexus/nexus-workers-short.png) diff --git a/docs/encyclopedia/retry-policies.mdx b/docs/encyclopedia/retry-policies.mdx index 0f246f65f4..effa0bba57 100644 --- a/docs/encyclopedia/retry-policies.mdx +++ b/docs/encyclopedia/retry-policies.mdx @@ -17,8 +17,8 @@ import { RelatedReadContainer, RelatedReadItem } from '@site/src/components/rela A Retry Policy works in cooperation with the timeouts to provide fine controls to optimize the execution experience. -A Retry Policy is a collection of attributes that instructs the Temporal Server how to retry a failure of a [Workflow Execution](/workflows#workflow-execution) or an [Activity Task Execution](/workers#activity-task-execution). -(Retry Policies do not apply to [Workflow Task Executions](/workers#workflow-task-execution), which always retry indefinitely.) +A Retry Policy is a collection of attributes that instructs the Temporal Server how to retry a failure of a [Workflow Execution](/workflows#workflow-execution) or an [Activity Task Execution](/tasks#activity-task-execution). +(Retry Policies do not apply to [Workflow Task Executions](/tasks#workflow-task-execution), which always retry indefinitely.) Try out the [Activity retry simulator](/develop/activity-retry-simulator) to visiualize how a Retry Policy works. @@ -48,7 +48,7 @@ Try out the [Activity retry simulator](/develop/activity-retry-simulator) to vis The intention is that a Workflow Definition should be written to never fail due to intermittent issues; an Activity is designed to handle such issues. - **Activity Execution:** When an Activity Execution is spawned, it is associated with a default Retry Policy, and thus Activity Task Executions are retried by default. - When an Activity Task Execution is retried, the Temporal Service places a new [Activity Task](/workers#activity-task) into its respective [Activity Task Queue](/workers#task-queue), which results in a new Activity Task Execution. + When an Activity Task Execution is retried, the Temporal Service places a new [Activity Task](/tasks#activity-task) into its respective [Activity Task Queue](/task-queue), which results in a new Activity Task Execution. ## Custom Retry Policy diff --git a/docs/encyclopedia/worker-versioning-legacy.mdx b/docs/encyclopedia/worker-versioning-legacy.mdx index fc47afeb7d..e65baf1680 100644 --- a/docs/encyclopedia/worker-versioning-legacy.mdx +++ b/docs/encyclopedia/worker-versioning-legacy.mdx @@ -26,7 +26,7 @@ tags: :::caution -This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning) +This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning) ::: @@ -36,7 +36,7 @@ The Temporal Server uses the Build ID to determine which versions of a Workflow We recommend that you read about Workflow Definitions before proceeding, because Workflow Versioning is largely concerned with helping to manage nondeterministic changes to those definitions. -Worker Versioning helps manage nondeterministic changes by providing a convenient way to ensure that [Workers](/workers) with different Workflow and Activity Definitions operating on the same Task Queue don't attempt to process [Workflow Tasks](/workers#workflow-task) and [Activity Tasks](/workers#activity-task-execution) that they can't successfully process, according to sets of versions associated with that Task Queue that you've defined. +Worker Versioning helps manage nondeterministic changes by providing a convenient way to ensure that [Workers](/workers) with different Workflow and Activity Definitions operating on the same Task Queue don't attempt to process [Workflow Tasks](/tasks#workflow-task) and [Activity Tasks](/tasks#activity-task-execution) that they can't successfully process, according to sets of versions associated with that Task Queue that you've defined. Accomplish this goal by assigning a Build ID (a free-form string) to the code that defines a Worker, and specifying which Build IDs are compatible with each other by updating the version sets associated with the Task Queue, stored by the Temporal Server. @@ -44,7 +44,7 @@ Accomplish this goal by assigning a Build ID (a free-form string) to the code th :::caution -This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning) +This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning) ::: @@ -105,7 +105,7 @@ You also have the option to specify that the continued Workflow should start usi :::caution -This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning) +This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning) ::: @@ -230,7 +230,7 @@ This limit is configurable on the server via the `limit.workerBuildIdSize` dynam :::caution -This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/workers#worker-versioning) +This version of Worker Versioning is deprecated and will go away at some point. Please redirect your attention to [Worker Versioning](/worker-versioning) ::: diff --git a/docs/encyclopedia/workers.mdx b/docs/encyclopedia/workers.mdx deleted file mode 100644 index 5de7a6a45b..0000000000 --- a/docs/encyclopedia/workers.mdx +++ /dev/null @@ -1,444 +0,0 @@ ---- -id: workers -title: What is a Temporal Worker? -sidebar_label: Workers -description: Temporal Workers are tightly coupled with Task Queues and Worker Processes. Workers include Worker Programs, Worker Processes, and Worker Entities, executing Workflow and Activity Tasks. Worker Processes, external to Temporal Service, handle Task polling and execution. Worker Identity aids debugging. Task Queues, supporting Task Routing and Sticky Execution -slug: /workers -toc_max_heading_level: 4 -keywords: - - workers - - versioning -tags: - - Workers - - Concepts ---- - -There is a tight coupling between Temporal Task Queues and Worker Processes. - -## What is a Worker? {#worker} - -In day-to-day conversations, the term Worker is used to denote either a [Worker Program](#worker-program), a [Worker Process](#worker-process), or a [Worker Entity](#worker-entity). -Temporal documentation aims to be explicit and differentiate between them. - -## What is a Task? {#task} - -A Task is the context that a Worker needs to progress with a specific [Workflow Execution](/workflows#workflow-execution), [Activity Execution](/activities#activity-execution), or a [Nexus Task Execution](#nexus-task-execution). - -There are three types of Tasks: - -- [Activity Task](#activity-task) -- [Workflow Task](#workflow-task) -- [Nexus Task](#nexus-task) - -## What is a Worker Program? {#worker-program} - -A Worker Program is the static code that defines the constraints of the Worker Process, developed using the APIs of a Temporal SDK. - -- [How to run a development Worker using the Go SDK](/develop/go/core-application#develop-worker) -- [How to run a development Worker using the Java SDK](/develop/java/core-application#run-a-dev-worker) -- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker) -- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker) -- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker) -- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process) - -- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker) -- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker) - -## What is a Worker Entity? {#worker-entity} - -A Worker Entity is the individual Worker within a Worker Process that listens to a specific Task Queue. - -A Worker Entity listens and polls on a single Task Queue. -A Worker Entity contains a Workflow Worker and/or an Activity Worker, which makes progress on Workflow Executions and Activity Executions, respectively. - -**Can a Worker handle more Workflow Executions than its cache size or number of supported threads?** - -Yes it can. -However, the trade off is added latency. - -Workers are stateless, so any Workflow Execution in a blocked state can be safely removed from a Worker. -Later on, it can be resurrected on the same or different Worker when the need arises (in the form of an external event). -Therefore, a single Worker can handle millions of open Workflow Executions, assuming it can handle the update rate and that a slightly higher latency is not a concern. - -**Operation guides:** - -- [How to tune Workers](/develop/worker-performance) - -## What is a Worker Identity? {#worker-identity} - -Workers have an associated identifier that helps identify the specific Worker instance. -By default, Temporal SDKs set a Worker Identity to `${process.pid}@${os.hostname()}`, which combines the Worker's process ID (`process.pid`) and the hostname of the machine running the Worker (`os.hostname()`). - -The Worker Identity is visible in various contexts, such as Workflow History and the list of pollers on a Task Queue. - -You can use the Worker Identity to aid in debugging operational issues. -By providing a user assigned identifier, you can trace issues back to specific Worker instances. - -**What are some limitations of the default identity?** - -While the default identity format may seem sensible, it often proves to be of limited usefulness in cloud environments. -Some common issues include: - -- **Docker containers**: When running Workers inside Docker containers, the process ID is always `1`, as each container typically runs a single process. This makes the process identifier meaningless for identification purposes. -- **Random hostnames**: In some cloud environments, such as Amazon ECS (Elastic Container Service), the hostname is a randomly generated string that does not provide any meaningful information about the Worker's execution context. -- **Ephemeral IP addresses**: In certain cases, the hostname might be set to an ephemeral IP address, which can change over time and does not uniquely identify a Worker instance. - -**What are some recommended approaches?** - -It is recommended that you ensure that the Worker Identity can be linked back to the corresponding machine, process, execution context, or log stream. -In some execution environment, this might require that you explicitly specify the Worker Identity. - -Here are some approaches: - -- **Use environment-specific identifiers**: Choose an identifier that is specific to your execution environment. For example, when running Workers on Amazon ECS, you can set the Worker Identity to the ECS Task ID, which uniquely identifies the task running the Worker. -- **Include relevant context**: Incorporate information that helps establish the context of the Worker, such as the deployment environment (`staging` or `production`), region, or any other relevant details. -- **Ensure uniqueness**: Make sure that the Worker Identity is unique within your system to avoid ambiguity when debugging issues. -- **Keep it concise**: While including relevant information is important, try to keep the Worker Identity concise and easily readable to facilitate quick identification and troubleshooting. - -## What is a Worker Process? {#worker-process} - -
-
-

- Component diagram of a Worker Process and the Temporal Server -

-
-
- Component diagram of a Worker Process and the Temporal Server -
-
- -A Worker Process is responsible for polling a [Task Queue](#task-queue), dequeueing a [Task](#task), executing your code in response to a Task, and responding to the [Temporal Service](/clusters) with the results. - -More formally, a Worker Process is any process that implements the Task Queue Protocol and the Task Execution Protocol. - -- A Worker Process is a Workflow Worker Process if the process implements the Workflow Task Queue Protocol and executes the Workflow Task Execution Protocol to make progress on a Workflow Execution. - A Workflow Worker Process can listen on an arbitrary number of Workflow Task Queues and can execute an arbitrary number of Workflow Tasks. -- A Worker Process is an Activity Worker Process if the process implements the Activity Task Queue Protocol and executes the Activity Task Processing Protocol to make progress on an Activity Execution. - An Activity Worker Process can listen on an arbitrary number of Activity Task Queues and can execute an arbitrary number of Activity Tasks. - -**Worker Processes are external to a Temporal Service.** -Temporal Application developers are responsible for developing [Worker Programs](#worker-program) and operating Worker Processes. -Said another way, the [Temporal Service](/clusters) (including the Temporal Cloud) doesn't execute any of your code (Workflow and Activity Definitions) on Temporal Service machines. The Temporal Service is solely responsible for orchestrating [State Transitions](/workflows#state-transition) and providing Tasks to the next available [Worker Entity](#worker-entity). - -While data transferred in Event Histories is [secured by mTLS](/self-hosted-guide/security#encryption-in-transit-with-mtls), by default, it is still readable at rest in the Temporal Service. - -To solve this, Temporal SDKs offer a [Data Converter API](/dataconversion) that you can use to customize the serialization of data going out of and coming back in to a Worker Entity, with the net effect of guaranteeing that the Temporal Service cannot read sensitive business data. - -In many of our tutorials, we show you how to run both a Temporal Service and one Worker on the same machine for local development. -However, a production-grade Temporal Application typically has a _fleet_ of Worker Processes, all running on hosts external to the Temporal Service. -A Temporal Application can have as many Worker Processes as needed. - -A Worker Process can be both a Workflow Worker Process and an Activity Worker Process. -Many SDKs support the ability to have multiple Worker Entities in a single Worker Process. -(Worker Entity creation and management differ between SDKs.) -A single Worker Entity can listen to only a single Task Queue. -But if a Worker Process has multiple Worker Entities, the Worker Process could be listening to multiple Task Queues. - -![Entity relationship diagram (meta model) of Worker Processes, Task Queues, and Tasks](/diagrams/worker-and-server-entity-relationship.svg) - -Worker Processes executing Activity Tasks must have access to any resources needed to execute the actions that are defined in Activity Definitions, such as the following: - -- Network access for external API calls. -- Credentials for infrastructure provisioning. -- Specialized GPUs for machine learning utilities. - -The Temporal Service itself has [internal workers](https://temporal.io/blog/workflow-engine-principles/#system-workflows-1910) for system Workflow Executions. -However, these internal workers are not visible to the developer. - -## What is a Workflow Task? {#workflow-task} - -A Workflow Task is a Task that contains the context needed to make progress with a Workflow Execution. - -- Every time a new external event that might affect a Workflow state is recorded, a Workflow Task that contains the event is added to a Task Queue and then picked up by a Workflow Worker. -- After the new event is handled, the Workflow Task is completed with a list of [Commands](/workflows#command). -- Handling of a Workflow Task is usually very fast and is not related to the duration of operations that the Workflow invokes. - -## What is a Workflow Task Execution? {#workflow-task-execution} - -A Workflow Task Execution occurs when a [Worker](#worker-entity) picks up a [Workflow Task](#workflow-task) and uses it to make progress on the execution of a [Workflow Definition](/workflows#workflow-definition) (also known as a Workflow function). - -## What is an Activity Task? {#activity-task} - -An Activity Task contains the context needed to proceed with an [Activity Task Execution](#activity-task-execution). -Activity Tasks largely represent the Activity Task Scheduled Event, which contains the data needed to execute an Activity Function. - -If Heartbeat data is being passed, an Activity Task will also contain the latest Heartbeat details. - -## What is an Activity Task Execution? {#activity-task-execution} - -An Activity Task Execution occurs when a [Worker](#worker-entity) uses the context provided from the [Activity Task](#activity-task) and executes the [Activity Definition](/activities#activity-definition) (also known as the Activity Function). - -The [ActivityTaskScheduled Event](/references/events#activitytaskscheduled) corresponds to when the Temporal Service puts the Activity Task into the Task Queue. - -The [ActivityTaskStarted Event](/references/events#activitytaskstarted) corresponds to when the Worker picks up the Activity Task from the Task Queue. - -Either [ActivityTaskCompleted](/references/events#activitytaskcompleted) or one of the other Closed Activity Task Events corresponds to when the Worker has yielded back to the Temporal Service. - -The API to schedule an Activity Execution provides an "effectively once" experience, even though there may be several Activity Task Executions that take place to successfully complete an Activity. - -Once an Activity Task finishes execution, the Worker responds to the Temporal Service with a specific Event: - -- ActivityTaskCanceled -- ActivityTaskCompleted -- ActivityTaskFailed -- ActivityTaskTerminated -- ActivityTaskTimedOut - -## What is a Nexus Task? {#nexus-task} - -A Nexus Task represents a single Nexus request to start or cancel a Nexus Operation. -The Nexus Task includes details such as the Nexus Service and Nexus Operation names, and other information required to process the Nexus request. -The Temporal Worker triggers the registered Operation handler based on the Nexus task information. - -## What is a Nexus Task Execution? {#nexus-task-execution} - -A Nexus Task Execution occurs when a Worker uses the context provided from the Nexus Task and executes an action associated with a Nexus Operation which commonly includes starting a Nexus Operation using it's Nexus Operation handler plus many additional actions that may be performed on a Nexus Operation. - -The NexusOperationScheduled Event corresponds to when the Temporal Service records the Workflow's intent to schedule an operation. - -The NexusOperationStarted Event corresponds to when the Worker picks up the Nexus Task from the Task Queue, starts an asynchronous Nexus Operation, and returns an Operation ID to the caller indicating the asynchronous Nexus Operation has started. - -Either NexusOperationCompleted or one of the other Closed Nexus Operation Events corresponds to when the Nexus Operation has reached a final state due to successfully completing the operation or unsuccessfully completing the operation in the case of a failure, timeout, or cancellation. - -A Nexus Operation Execution appears to the caller Workflow as a single RPC, while under the hood the Temporal Service may issue several Nexus Tasks to attempt to start the Operation. -Hence, a Nexus Operation Handler implementation should be idempotent. -The WorkflowRunOperation provided by the SDK leverages Workflow ID based deduplication to ensures idempotency and provide an "effectively once" experience. - -A Nexus Task Execution completes when a Worker responds to the Temporal Service with either a RespondNexusTaskCompleted or RespondNexusTaskFailed call, or when the Task times out. - -The Temporal Service interprets the outcome and determines whether to retry the Task or record the progress in a History Event: - -- NexusTaskCompleted -- NexusTaskFailed - -## What is a Task Queue? {#task-queue} - -A Task Queue is a lightweight, dynamically allocated queue that one or more [Worker Entities](#worker-entity) poll for [Tasks](#task). - -There are two types of Task Queues, Activity Task Queues and Workflow Task Queues. - -
-
-

Task Queue component

-
-
- Task Queue component -
-
- -Task Queues are very lightweight components. -Task Queues do not require explicit registration but instead are created on demand when a Workflow Execution or Activity spawns or when a Worker Process subscribes to it. -When a Task Queue is created, both a Workflow Task Queue and an Activity Task Queue are created under the same name. -There is no limit to the number of Task Queues a Temporal Application can use or a Temporal Service can maintain. - -Workers poll for Tasks in Task Queues via synchronous RPC. -This implementation offers several benefits: - -- A Worker Process polls for a message only when it has spare capacity, avoiding overloading itself. -- In effect, Task Queues enable load balancing across many Worker Processes. -- Task Queues enable what we call [Task Routing](#task-routing), which is the routing of specific Tasks to specific Worker Processes or even a specific process. -- Task Queues support server-side throttling, which enables you to limit the Task dispatching rate to the pool of Worker Processes while still supporting Task dispatching at higher rates when spikes happen. -- When all Worker Processes are down, messages simply persist in a Task Queue, waiting for the Worker Processes to recover. -- Worker Processes do not need to advertise themselves through DNS or any other network discovery mechanism. -- Worker Processes do not need to have any open ports, which is more secure. - -All Workers listening to a given Task Queue must have identical registrations of Activities and/or Workflows. -The one exception is during a Server upgrade, where it is okay to have registration temporarily misaligned while the binary rolls out. - -#### Where to set Task Queues - -There are four places where the name of the Task Queue can be set by the developer. - -1. A Task Queue must be set when spawning a Workflow Execution: - -- [How to start a Workflow Execution using the Temporal CLI](/cli/workflow#start) -- [How to start a Workflow Execution using the Go SDK](/develop/go/temporal-clients#start-workflow-execution) -- [How to start a Workflow Execution using the Java SDK](/develop/java/temporal-clients#start-workflow-execution) -- [How to start a Workflow Execution using the PHP SDK](/develop/php/temporal-clients#start-workflow-execution) -- [How to start a Workflow Execution using the Python SDK](/develop/python/temporal-clients#start-workflow-execution) -- [How to start a Workflow Execution using the TypeScript SDK](/develop/typescript/temporal-clients#start-workflow-execution) -- [How to start a Workflow Execution using the .NET SDK](/develop/dotnet/temporal-client#start-workflow) - -2. A Task Queue name must be set when creating a Worker Entity and when running a Worker Process: - -- [How to run a development Worker using the Go SDK](/develop/go/core-application#develop-worker) -- [How to run a development Worker using the Java SDK](/develop/java/core-application#run-a-dev-worker) -- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker) -- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker) -- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker) -- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process) - -- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker) -- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker) - -Note that all Worker Entities listening to the same Task Queue name must be registered to handle the exact same Workflows Types and Activity Types. - -If a Worker Entity polls a Task for a Workflow Type or Activity Type it does not know about, it will fail that Task. -However, the failure of the Task will not cause the associated Workflow Execution to fail. - -3. A Task Queue name can be provided when spawning an Activity Execution: - -This is optional. -An Activity Execution inherits the Task Queue name from its Workflow Execution if one is not provided. - -- [How to start an Activity Execution using the Go SDK](/develop/go/core-application#activity-execution) -- [How to start an Activity Execution using the Java SDK](/develop/java/core-application#activity-execution) -- [How to start an Activity Execution using the PHP SDK](/develop/php/core-application#activity-execution) -- [How to start an Activity Execution using the Python SDK](/develop/python/core-application#activity-execution) -- [How to start an Activity Execution using the TypeScript SDK](/develop/typescript/core-application#activity-execution) -- [How to start an Activity Execution using the .NET SDK](/develop/dotnet/core-application#activity-execution) - -4. A Task Queue name can be provided when spawning a Child Workflow Execution: - -This is optional. -A Child Workflow Execution inherits the Task Queue name from its Parent Workflow Execution if one is not provided. - -- [How to start a Child Workflow Execution using the Go SDK](/develop/go/child-workflows) -- [How to start a Child Workflow Execution using the Java SDK](/develop/java/child-workflows) -- [How to start a Child Workflow Execution using the PHP SDK](/develop/php/continue-as-new) -- [How to start a Child Workflow Execution using the Python SDK](/develop/python/child-workflows) -- [How to start a Child Workflow Execution using the TypeScript SDK](/develop/typescript/child-workflows) -- [How to start a Child Workflow Execution using the .NET SDK](/develop/dotnet/child-workflows) - -#### Task ordering - -Task Queues can be scaled by adding partitions. -The [default](/references/dynamic-configuration#service-level-rps-limits) number of partitions is 4. - -Task Queues with multiple partitions do not have any ordering guarantees. -Once there is a backlog of Tasks that have been written to disk, Tasks that can be dispatched immediately (“sync matches”) are delivered before tasks from the backlog (“async matches”). -This approach optimizes throughput. - -Task Queues with a single partition are almost always first-in, first-out, with rare edge case exceptions. -However, using a single partition limits you to low- and medium-throughput use cases. - -:::note - -This section is on the ordering of individual Tasks, and does not apply to the ordering of Workflow Executions, Activity Executions, or [Events](/workflows#event) in a single Workflow Execution. -The order of Events in a Workflow Execution is guaranteed to remain constant once they have been written to that Workflow Execution's [History](/workflows#event-history). - -::: - -## What is a Sticky Execution? {#sticky-execution} - -A Sticky Execution is when a Worker Entity caches the Workflow in memory and creates a dedicated Task Queue to listen on. - -A Sticky Execution occurs after a Worker Entity completes the first Workflow Task in the chain of Workflow Tasks for the Workflow Execution. - -The Worker Entity caches the Workflow in memory and begins polling the dedicated Task Queue for Workflow Tasks that contain updates, rather than the entire Event History. - -If the Worker Entity does not pick up a Workflow Task from the dedicated Task Queue in an appropriate amount of time, the Temporal Service will resume Scheduling Workflow Tasks on the original Task Queue. -Another Worker Entity can then resume the Workflow Execution, and can set up its own Sticky Execution for future Workflow Tasks. - -- [How to set a `StickyScheduleToStartTimeout` on a Worker Entity in Go](/develop/go/core-application#stickyscheduletostarttimeout) - -Sticky Executions are the default behavior of the Temporal Platform. - -## What is Task Routing? {#task-routing} - -Task Routing is simply when a Task Queue is paired with one or more Workers, primarily for Activity Task Executions. - -This could also mean employing multiple Task Queues, each one paired with a Worker Process. - -Task Routing has many applicable use cases. - -Some SDKs provide a [Session API](#worker-session) that provides a straightforward way to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. -It also includes features like concurrent session limitations and worker failure detection. - -### Flow control - -A Worker that consumes from a Task Queue asks for an Activity Task only when it has available capacity, so it is never overloaded by request spikes. -If Activity Tasks get created faster than Workers can process them, they are backlogged in the Task Queue. - -### Throttling - -The rate at which each Activity Worker polls for and processes Activity Tasks is configurable per Worker. -Workers do not exceed this rate even if it has spare capacity. -There is also support for global Task Queue rate limiting. -This limit works across all Workers for the given Task Queue. -It is frequently used to limit load on a downstream service that an Activity calls into. - -### Specific environments - -In some cases, you might need to execute Activities in a dedicated environment. -To send Activity Tasks to this environment, use a dedicated Task Queue. - -#### Route Activity Tasks to a specific host - -In some use cases, such as file processing or machine learning model training, an Activity Task must be routed to a specific Worker Process or Worker Entity. - -For example, suppose that you have a Workflow with the following three separate Activities: - -- Download a file. -- Process the file in some way. -- Upload a file to another location. - -The first Activity, to download the file, could occur on any Worker on any host. -However, the second and third Activities must be executed by a Worker on the same host where the first Activity downloaded the file. - -In a real-life scenario, you might have many Worker Processes scaled over many hosts. -You would need to develop your Temporal Application to route Tasks to specific Worker Processes when needed. - -Code samples: - -- [Go file processing example](https://github.com/temporalio/samples-go/tree/main/fileprocessing) -- [Java file processing example](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/fileprocessing) -- [PHP file processing example](https://github.com/temporalio/samples-php/tree/master/app/src/FileProcessing) - -#### Route Activity Tasks to a specific process - -Some Activities load large datasets and cache them in the process. -The Activities that rely on those datasets should be routed to the same process. - -In this case, a unique Task Queue would exist for each Worker Process involved. - -#### Workers with different capabilities - -Some Workers might exist on GPU boxes versus non-GPU boxes. -In this case, each type of box would have its own Task Queue and a Workflow can pick one to send Activity Tasks. - -### Multiple priorities - -If your use case involves more than one priority, you can create one Task Queue per priority, with a Worker pool per priority. - -### Versioning - -Task Routing is the simplest way to version your code. - -If you have a new backward-incompatible Activity Definition, start by using a different Task Queue. - -### What is a Worker Session? {#worker-session} - -A Worker Session is a feature provided by some SDKs that provides a straightforward API for [Task Routing](#task-routing) to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. -It also includes features like concurrent session limitations and Worker failure detection. - -- [How to use Worker Sessions](/develop/go/sessions) - -## What is Worker Versioning? {#worker-versioning} - -:::tip Support, stability, and dependency info - -- In [Pre-release](/evaluate/development-production-features/release-stages#pre-release) -- Introduced in Temporal Server version [1.21.0](https://github.com/temporalio/temporal/releases/tag/v1.21.0) -- CLI, recommended and minimum [0.13.1](https://github.com/temporalio/cli/releases/tag/v0.13.1) -- [Go SDK](/develop/go/versioning#worker-versioning) recommended [v1.27.0](https://github.com/temporalio/sdk-go/releases/tag/v1.27.0), minimum [v1.23.0](https://github.com/temporalio/sdk-go/releases/tag/v1.23.0) -- [Java SDK](/develop/java/versioning#worker-versioning) minimum [v1.20.0](https://github.com/temporalio/sdk-java/releases/tag/v1.20.0) -- [TypeScript SDK](/develop/typescript/versioning#worker-versioning) minimum [v1.8.0](https://github.com/temporalio/sdk-typescript/releases/tag/v1.8.0) -- [Python SDK](/develop/python/versioning#worker-versioning) minimum [v1.3.0](https://github.com/temporalio/sdk-python/releases/tag/1.3.0) -- [.NET SDK](https://dotnet.temporal.io/api/Temporalio.Worker.TemporalWorkerOptions.html#Temporalio_Worker_TemporalWorkerOptions_UseWorkerVersioning) minimum [v0.1.0-beta1](https://github.com/temporalio/sdk-dotnet/releases/tag/0.1.0-beta1) - ::: - -Worker Versioning simplifies the process of deploying changes to [Workflow Definitions](/workflows#workflow-definition). - -See the [Pre-release README.md](https://github.com/temporalio/temporal/blob/main/docs/worker-versioning.md) for more information. - -If you're using the older version of the Worker Versioning pre-release that was released in late 2023, go [here](/encyclopedia/worker-versioning-legacy.mdx). diff --git a/docs/encyclopedia/workers/sticky-execution.mdx b/docs/encyclopedia/workers/sticky-execution.mdx new file mode 100644 index 0000000000..9cc08ae1b8 --- /dev/null +++ b/docs/encyclopedia/workers/sticky-execution.mdx @@ -0,0 +1,30 @@ +--- +id: sticky-execution +title: Sticky Execution +sidebar_label: Sticky Execution +description: Learn about Sticky Execution and how it optimizes Task processing in Temporal by caching Workflow state locally. +slug: /sticky-execution +toc_max_heading_level: 4 +keywords: + - sticky execution +tags: + - Sticky Execution + - Worker +--- + +This page discusses [Sticky Executions](#sticky-execution). + +## What is a Sticky Execution? {#sticky-execution} + +A Sticky Execution is when a Worker Entity caches the Workflow in memory and creates a dedicated Task Queue to listen on. + +A Sticky Execution occurs after a Worker Entity completes the first Workflow Task in the chain of Workflow Tasks for the Workflow Execution. + +The Worker Entity caches the Workflow in memory and begins polling the dedicated Task Queue for Workflow Tasks that contain updates, rather than the entire Event History. + +If the Worker Entity does not pick up a Workflow Task from the dedicated Task Queue in an appropriate amount of time, the Temporal Service will resume Scheduling Workflow Tasks on the original Task Queue. +Another Worker Entity can then resume the Workflow Execution, and can set up its own Sticky Execution for future Workflow Tasks. + +- [How to set a `StickyScheduleToStartTimeout` on a Worker Entity in Go](/develop/go/core-application#stickyscheduletostarttimeout) + +Sticky Executions are the default behavior of the Temporal Platform. \ No newline at end of file diff --git a/docs/encyclopedia/workers/task-queues.mdx b/docs/encyclopedia/workers/task-queues.mdx new file mode 100644 index 0000000000..97d641dc94 --- /dev/null +++ b/docs/encyclopedia/workers/task-queues.mdx @@ -0,0 +1,143 @@ +--- +id: task-queues +title: Task Queues +sidebar_label: Task Queues +description: Explore the role of Worker Processes in polling Task Queues and executing Tasks. +slug: /task-queue +toc_max_heading_level: 4 +keywords: + - task queues +tags: + - Workers + - Task Queues +--- + +This page discusses [Task Queues](#task-queue) including [where to set Task Queues](#set-task-queue) and [Task Ordering](#task-ordering). + +## What is a Task Queue? {#task-queue} + +A Task Queue is a lightweight, dynamically allocated queue that one or more [Worker Entities](/workers#worker-entity) poll for [Tasks](/tasks#task). + +There are two types of Task Queues, Activity Task Queues and Workflow Task Queues. + +
+
+

Task Queue component

+
+
+ Task Queue component +
+
+ +Task Queues are very lightweight components. +Task Queues do not require explicit registration but instead are created on demand when a Workflow Execution or Activity spawns or when a Worker Process subscribes to it. +When a Task Queue is created, both a Workflow Task Queue and an Activity Task Queue are created under the same name. +There is no limit to the number of Task Queues a Temporal Application can use or a Temporal Service can maintain. + +Workers poll for Tasks in Task Queues via synchronous RPC. +This implementation offers several benefits: + +- A Worker Process polls for a message only when it has spare capacity, avoiding overloading itself. +- In effect, Task Queues enable load balancing across many Worker Processes. +- Task Queues enable what we call [Task Routing](/task-routing), which is the routing of specific Tasks to specific Worker Processes or even a specific process. +- Task Queues support server-side throttling, which enables you to limit the Task dispatching rate to the pool of Worker Processes while still supporting Task dispatching at higher rates when spikes happen. +- When all Worker Processes are down, messages simply persist in a Task Queue, waiting for the Worker Processes to recover. +- Worker Processes do not need to advertise themselves through DNS or any other network discovery mechanism. +- Worker Processes do not need to have any open ports, which is more secure. + +All Workers listening to a given Task Queue must have identical registrations of Activities and/or Workflows. +The one exception is during a Server upgrade, where it is okay to have registration temporarily misaligned while the binary rolls out. + +### Where to set Task Queues {#set-task-queue} + +There are four places where the name of the Task Queue can be set by the developer. + +1. A Task Queue must be set when spawning a Workflow Execution: + +:::info + +- [How to start a Workflow Execution using the Temporal CLI](/cli/workflow#start) +- [How to start a Workflow Execution using the Go SDK](/develop/go/temporal-clients#start-workflow-execution) +- [How to start a Workflow Execution using the Java SDK](/develop/java/temporal-clients#start-workflow-execution) +- [How to start a Workflow Execution using the PHP SDK](/develop/php/temporal-clients#start-workflow-execution) +- [How to start a Workflow Execution using the Python SDK](/develop/python/temporal-clients#start-workflow-execution) +- [How to start a Workflow Execution using the TypeScript SDK](/develop/typescript/temporal-clients#start-workflow-execution) +- [How to start a Workflow Execution using the .NET SDK](/develop/dotnet/temporal-client#start-workflow) + +::: + +2. A Task Queue name must be set when creating a Worker Entity and when running a Worker Process: + +:::info + +- [How to run a development Worker using the Go SDK](/develop/go/core-application#develop-worker) +- [How to run a development Worker using the Java SDK](/develop/java/core-application#run-a-dev-worker) +- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker) +- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker) +- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker) +- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process) + +- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker) +- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker) + +::: + +Note that all Worker Entities listening to the same Task Queue name must be registered to handle the exact same Workflows Types and Activity Types. + +If a Worker Entity polls a Task for a Workflow Type or Activity Type it does not know about, it will fail that Task. +However, the failure of the Task will not cause the associated Workflow Execution to fail. + +3. A Task Queue name can be provided when spawning an Activity Execution: + +This is optional. +An Activity Execution inherits the Task Queue name from its Workflow Execution if one is not provided. + +:::info + +- [How to start an Activity Execution using the Go SDK](/develop/go/core-application#activity-execution) +- [How to start an Activity Execution using the Java SDK](/develop/java/core-application#activity-execution) +- [How to start an Activity Execution using the PHP SDK](/develop/php/core-application#activity-execution) +- [How to start an Activity Execution using the Python SDK](/develop/python/core-application#activity-execution) +- [How to start an Activity Execution using the TypeScript SDK](/develop/typescript/core-application#activity-execution) +- [How to start an Activity Execution using the .NET SDK](/develop/dotnet/core-application#activity-execution) + +::: + +4. A Task Queue name can be provided when spawning a Child Workflow Execution: + +This is optional. +A Child Workflow Execution inherits the Task Queue name from its Parent Workflow Execution if one is not provided. + +:::info + +- [How to start a Child Workflow Execution using the Go SDK](/develop/go/child-workflows) +- [How to start a Child Workflow Execution using the Java SDK](/develop/java/child-workflows) +- [How to start a Child Workflow Execution using the PHP SDK](/develop/php/continue-as-new) +- [How to start a Child Workflow Execution using the Python SDK](/develop/python/child-workflows) +- [How to start a Child Workflow Execution using the TypeScript SDK](/develop/typescript/child-workflows) +- [How to start a Child Workflow Execution using the .NET SDK](/develop/dotnet/child-workflows) + +::: + +### Task ordering {#task-ordering} + +Task Queues can be scaled by adding partitions. +The [default](/references/dynamic-configuration#service-level-rps-limits) number of partitions is 4. + +Task Queues with multiple partitions do not have any ordering guarantees. +Once there is a backlog of Tasks that have been written to disk, Tasks that can be dispatched immediately (“sync matches”) are delivered before tasks from the backlog (“async matches”). +This approach optimizes throughput. + +Task Queues with a single partition are almost always first-in, first-out, with rare edge case exceptions. +However, using a single partition limits you to low- and medium-throughput use cases. + +:::note + +This section is on the ordering of individual Tasks, and does not apply to the ordering of Workflow Executions, Activity Executions, or [Events](/workflows#event) in a single Workflow Execution. +The order of Events in a Workflow Execution is guaranteed to remain constant once they have been written to that Workflow Execution's [History](/workflows#event-history). + +::: diff --git a/docs/encyclopedia/workers/task-routing-worker-sessions.mdx b/docs/encyclopedia/workers/task-routing-worker-sessions.mdx new file mode 100644 index 0000000000..8de0eacfcd --- /dev/null +++ b/docs/encyclopedia/workers/task-routing-worker-sessions.mdx @@ -0,0 +1,99 @@ +--- +id: task-routing-worker-sessions +title: Task Routing and Worker Sessions +sidebar_label: Task Routing and Worker Sessions +description: Learn about routing Tasks and Worker Sessions. +slug: /task-routing +toc_max_heading_level: 4 +keywords: + - task routing + - sticky execution +tags: + - Workers + - Task Queues +--- + +This page discusses the following: + +- [Task Routing](#task-routing) +- [Worker Sessions](#worker-session) + +## What is Task Routing? {#task-routing} + +Task Routing is simply when a Task Queue is paired with one or more Workers, primarily for Activity Task Executions. + +This could also mean employing multiple Task Queues, each one paired with a Worker Process. + +Task Routing has many applicable use cases. + +Some SDKs provide a [Session API](#worker-session) that provides a straightforward way to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. +It also includes features like concurrent session limitations and worker failure detection. + +### Flow control + +A Worker that consumes from a Task Queue asks for an Activity Task only when it has available capacity, so it is never overloaded by request spikes. +If Activity Tasks get created faster than Workers can process them, they are backlogged in the Task Queue. + +### Throttling + +The rate at which each Activity Worker polls for and processes Activity Tasks is configurable per Worker. +Workers do not exceed this rate even if it has spare capacity. +There is also support for global Task Queue rate limiting. +This limit works across all Workers for the given Task Queue. +It is frequently used to limit load on a downstream service that an Activity calls into. + +### Specific environments + +In some cases, you might need to execute Activities in a dedicated environment. +To send Activity Tasks to this environment, use a dedicated Task Queue. + +#### Route Activity Tasks to a specific host + +In some use cases, such as file processing or machine learning model training, an Activity Task must be routed to a specific Worker Process or Worker Entity. + +For example, suppose that you have a Workflow with the following three separate Activities: + +- Download a file. +- Process the file in some way. +- Upload a file to another location. + +The first Activity, to download the file, could occur on any Worker on any host. +However, the second and third Activities must be executed by a Worker on the same host where the first Activity downloaded the file. + +In a real-life scenario, you might have many Worker Processes scaled over many hosts. +You would need to develop your Temporal Application to route Tasks to specific Worker Processes when needed. + +Code samples: + +- [Go file processing example](https://github.com/temporalio/samples-go/tree/main/fileprocessing) +- [Java file processing example](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/fileprocessing) +- [PHP file processing example](https://github.com/temporalio/samples-php/tree/master/app/src/FileProcessing) + +#### Route Activity Tasks to a specific process + +Some Activities load large datasets and cache them in the process. +The Activities that rely on those datasets should be routed to the same process. + +In this case, a unique Task Queue would exist for each Worker Process involved. + +#### Workers with different capabilities + +Some Workers might exist on GPU boxes versus non-GPU boxes. +In this case, each type of box would have its own Task Queue and a Workflow can pick one to send Activity Tasks. + +### Multiple priorities + +If your use case involves more than one priority, you can create one Task Queue per priority, with a Worker pool per priority. + +### Versioning + +Task Routing is the simplest way to version your code. + +If you have a new backward-incompatible Activity Definition, start by using a different Task Queue. + +## What is a Worker Session? {#worker-session} + +A Worker Session is a feature provided by some SDKs that provides a straightforward API for [Task Routing](#task-routing) to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. +It also includes features like concurrent session limitations and Worker failure detection. + +- [How to use Worker Sessions](/develop/go/sessions) \ No newline at end of file diff --git a/docs/encyclopedia/workers/tasks.mdx b/docs/encyclopedia/workers/tasks.mdx new file mode 100644 index 0000000000..450d07efbe --- /dev/null +++ b/docs/encyclopedia/workers/tasks.mdx @@ -0,0 +1,101 @@ +--- +id: tasks +title: Tasks +sidebar_label: Tasks +description: Learn about the types of Tasks in Temporal and their role in Workflow and Activity Executions. +slug: /tasks +toc_max_heading_level: 4 +keywords: + - tasks + - activity task + - workflow task +tags: + - Tasks + - Concepts +--- + +This page discusses the following: + +- [Task](#task) +- [Workflow Task](#workflow-task) +- [Workflow Task Execution](#workflow-task-execution) +- [Activity Task](#activity-task) +- [Activity Task Execution](#activity-task-execution) +- [Nexus Task](#nexus-task) +- [Nexus Task Execution](#nexus-task-execution) + +## What is a Task? {#task} + +A Task is the context that a Worker needs to progress with a specific [Workflow Execution](/workflows#workflow-execution), [Activity Execution](/activities#activity-execution), or a [Nexus Task Execution](#nexus-task-execution). + +There are three types of Tasks: + +- [Workflow Task](#workflow-task) +- [Activity Task](#activity-task) +- [Nexus Task](#nexus-task) + +## What is a Workflow Task? {#workflow-task} + +A Workflow Task is a Task that contains the context needed to make progress with a Workflow Execution. + +- Every time a new external event that might affect a Workflow state is recorded, a Workflow Task that contains the event is added to a Task Queue and then picked up by a Workflow Worker. +- After the new event is handled, the Workflow Task is completed with a list of [Commands](/workflows#command). +- Handling of a Workflow Task is usually very fast and is not related to the duration of operations that the Workflow invokes. + +### What is a Workflow Task Execution? {#workflow-task-execution} + +A Workflow Task Execution occurs when a [Worker](/workers#worker-entity) picks up a [Workflow Task](#workflow-task) and uses it to make progress on the execution of a [Workflow Definition](/workflows#workflow-definition) (also known as a Workflow function). + +## What is an Activity Task? {#activity-task} + +An Activity Task contains the context needed to proceed with an [Activity Task Execution](#activity-task-execution). +Activity Tasks largely represent the Activity Task Scheduled Event, which contains the data needed to execute an Activity Function. + +If Heartbeat data is being passed, an Activity Task will also contain the latest Heartbeat details. + +### What is an Activity Task Execution? {#activity-task-execution} + +An Activity Task Execution occurs when a [Worker](/workers#worker-entity) uses the context provided from the [Activity Task](#activity-task) and executes the [Activity Definition](/activities#activity-definition) (also known as the Activity Function). + +The [ActivityTaskScheduled Event](/references/events#activitytaskscheduled) corresponds to when the Temporal Service puts the Activity Task into the Task Queue. + +The [ActivityTaskStarted Event](/references/events#activitytaskstarted) corresponds to when the Worker picks up the Activity Task from the Task Queue. + +Either [ActivityTaskCompleted](/references/events#activitytaskcompleted) or one of the other Closed Activity Task Events corresponds to when the Worker has yielded back to the Temporal Service. + +The API to schedule an Activity Execution provides an "effectively once" experience, even though there may be several Activity Task Executions that take place to successfully complete an Activity. + +Once an Activity Task finishes execution, the Worker responds to the Temporal Service with a specific Event: + +- ActivityTaskCanceled +- ActivityTaskCompleted +- ActivityTaskFailed +- ActivityTaskTerminated +- ActivityTaskTimedOut + +## What is a Nexus Task? {#nexus-task} + +A Nexus Task represents a single Nexus request to start or cancel a Nexus Operation. +The Nexus Task includes details such as the Nexus Service and Nexus Operation names, and other information required to process the Nexus request. +The Temporal Worker triggers the registered Operation handler based on the Nexus task information. + +### What is a Nexus Task Execution? {#nexus-task-execution} + +A Nexus Task Execution occurs when a Worker uses the context provided from the Nexus Task and executes an action associated with a Nexus Operation which commonly includes starting a Nexus Operation using it's Nexus Operation handler plus many additional actions that may be performed on a Nexus Operation. + +The NexusOperationScheduled Event corresponds to when the Temporal Service records the Workflow's intent to schedule an operation. + +The NexusOperationStarted Event corresponds to when the Worker picks up the Nexus Task from the Task Queue, starts an asynchronous Nexus Operation, and returns an Operation ID to the caller indicating the asynchronous Nexus Operation has started. + +Either NexusOperationCompleted or one of the other Closed Nexus Operation Events corresponds to when the Nexus Operation has reached a final state due to successfully completing the operation or unsuccessfully completing the operation in the case of a failure, timeout, or cancellation. + +A Nexus Operation Execution appears to the caller Workflow as a single RPC, while under the hood the Temporal Service may issue several Nexus Tasks to attempt to start the Operation. +Hence, a Nexus Operation Handler implementation should be idempotent. +The WorkflowRunOperation provided by the SDK leverages Workflow ID based deduplication to ensures idempotency and provide an "effectively once" experience. + +A Nexus Task Execution completes when a Worker responds to the Temporal Service with either a RespondNexusTaskCompleted or RespondNexusTaskFailed call, or when the Task times out. + +The Temporal Service interprets the outcome and determines whether to retry the Task or record the progress in a History Event: + +- NexusTaskCompleted +- NexusTaskFailed diff --git a/docs/encyclopedia/workers/worker-versioning.mdx b/docs/encyclopedia/workers/worker-versioning.mdx new file mode 100644 index 0000000000..b73730bee3 --- /dev/null +++ b/docs/encyclopedia/workers/worker-versioning.mdx @@ -0,0 +1,36 @@ +--- +id: worker-versioning +title: Worker Versioning +sidebar_label: Worker Versioning +description: Understand how Worker Versioning facilitates deployment changes. +slug: /worker-versioning +toc_max_heading_level: 4 +keywords: + - worker sessions + - worker versioning +tags: + - Workers + - Concepts +--- + +This page discusses [Worker Versioning](#worker-versioning). + +## What is Worker Versioning? {#worker-versioning} + +:::tip Support, stability, and dependency info + +- In [Pre-release](/evaluate/development-production-features/release-stages#pre-release) +- Introduced in Temporal Server version [1.21.0](https://github.com/temporalio/temporal/releases/tag/v1.21.0) +- CLI, recommended and minimum [0.13.1](https://github.com/temporalio/cli/releases/tag/v0.13.1) +- [Go SDK](/develop/go/versioning#worker-versioning) recommended [v1.27.0](https://github.com/temporalio/sdk-go/releases/tag/v1.27.0), minimum [v1.23.0](https://github.com/temporalio/sdk-go/releases/tag/v1.23.0) +- [Java SDK](/develop/java/versioning#worker-versioning) minimum [v1.20.0](https://github.com/temporalio/sdk-java/releases/tag/v1.20.0) +- [TypeScript SDK](/develop/typescript/versioning#worker-versioning) minimum [v1.8.0](https://github.com/temporalio/sdk-typescript/releases/tag/v1.8.0) +- [Python SDK](/develop/python/versioning#worker-versioning) minimum [v1.3.0](https://github.com/temporalio/sdk-python/releases/tag/1.3.0) +- [.NET SDK](https://dotnet.temporal.io/api/Temporalio.Worker.TemporalWorkerOptions.html#Temporalio_Worker_TemporalWorkerOptions_UseWorkerVersioning) minimum [v0.1.0-beta1](https://github.com/temporalio/sdk-dotnet/releases/tag/0.1.0-beta1) + ::: + +Worker Versioning simplifies the process of deploying changes to [Workflow Definitions](/workflows#workflow-definition). + +See the [Pre-release README.md](https://github.com/temporalio/temporal/blob/main/docs/worker-versioning.md) for more information. + +If you're using the older version of the Worker Versioning pre-release that was released in late 2023, go [here](/encyclopedia/worker-versioning-legacy.mdx). diff --git a/docs/encyclopedia/workers/workers.mdx b/docs/encyclopedia/workers/workers.mdx new file mode 100644 index 0000000000..9aae15837d --- /dev/null +++ b/docs/encyclopedia/workers/workers.mdx @@ -0,0 +1,150 @@ +--- +id: workers +title: What is a Temporal Worker? +sidebar_label: Workers +description: Temporal Workers are tightly coupled with Task Queues and Worker Processes. +slug: /workers +toc_max_heading_level: 4 +keywords: + - workers + - versioning +tags: + - Workers + - Concepts +--- + +This page discusses the following: + +- [Worker](#worker) +- [Worker Program](#worker-program) +- [Worker Entity](#worker-entity) +- [Worker Identity?](#worker-identity) + +## What is a Worker? {#worker} + +In day-to-day conversations, the term Worker is used to denote either a [Worker Program](#worker-program), a [Worker Process](#worker-process), or a [Worker Entity](/workers#worker-entity). +Temporal documentation aims to be explicit and differentiate between them. + +## What is a Worker Program? {#worker-program} + +A Worker Program is the static code that defines the constraints of the Worker Process, developed using the APIs of a Temporal SDK. + +:::info + +- [How to run a development Worker using the Go SDK](/develop/go/core-application#develop-worker) +- [How to run a development Worker using the Java SDK](/develop/java/core-application#run-a-dev-worker) +- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker) +- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker) +- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker) +- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process) + +- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker) +- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker) + +::: + +## What is a Worker Entity? {#worker-entity} + +A Worker Entity is the individual Worker within a Worker Process that listens to a specific Task Queue. + +A Worker Entity listens and polls on a single Task Queue. +A Worker Entity contains a Workflow Worker and/or an Activity Worker, which makes progress on Workflow Executions and Activity Executions, respectively. + +**Can a Worker handle more Workflow Executions than its cache size or number of supported threads?** + +Yes it can. +However, the trade off is added latency. + +Workers are stateless, so any Workflow Execution in a blocked state can be safely removed from a Worker. +Later on, it can be resurrected on the same or different Worker when the need arises (in the form of an external event). +Therefore, a single Worker can handle millions of open Workflow Executions, assuming it can handle the update rate and that a slightly higher latency is not a concern. + +**Operation guides:** + +- [How to tune Workers](/develop/worker-performance) + +## What is a Worker Identity? {#worker-identity} + +Workers have an associated identifier that helps identify the specific Worker instance. +By default, Temporal SDKs set a Worker Identity to `${process.pid}@${os.hostname()}`, which combines the Worker's process ID (`process.pid`) and the hostname of the machine running the Worker (`os.hostname()`). + +The Worker Identity is visible in various contexts, such as Workflow History and the list of pollers on a Task Queue. + +You can use the Worker Identity to aid in debugging operational issues. +By providing a user assigned identifier, you can trace issues back to specific Worker instances. + +**What are some limitations of the default identity?** + +While the default identity format may seem sensible, it often proves to be of limited usefulness in cloud environments. +Some common issues include: + +- **Docker containers**: When running Workers inside Docker containers, the process ID is always `1`, as each container typically runs a single process. This makes the process identifier meaningless for identification purposes. +- **Random hostnames**: In some cloud environments, such as Amazon ECS (Elastic Container Service), the hostname is a randomly generated string that does not provide any meaningful information about the Worker's execution context. +- **Ephemeral IP addresses**: In certain cases, the hostname might be set to an ephemeral IP address, which can change over time and does not uniquely identify a Worker instance. + +**What are some recommended approaches?** + +It is recommended that you ensure that the Worker Identity can be linked back to the corresponding machine, process, execution context, or log stream. +In some execution environment, this might require that you explicitly specify the Worker Identity. + +Here are some approaches: + +- **Use environment-specific identifiers**: Choose an identifier that is specific to your execution environment. For example, when running Workers on Amazon ECS, you can set the Worker Identity to the ECS Task ID, which uniquely identifies the task running the Worker. +- **Include relevant context**: Incorporate information that helps establish the context of the Worker, such as the deployment environment (`staging` or `production`), region, or any other relevant details. +- **Ensure uniqueness**: Make sure that the Worker Identity is unique within your system to avoid ambiguity when debugging issues. +- **Keep it concise**: While including relevant information is important, try to keep the Worker Identity concise and easily readable to facilitate quick identification and troubleshooting. + +## What is a Worker Process? {#worker-process} + +
+
+

+ Component diagram of a Worker Process and the Temporal Server +

+
+
+ Component diagram of a Worker Process and the Temporal Server +
+
+ +A Worker Process is responsible for polling a [Task Queue](/task-queue), dequeueing a [Task](/tasks#task), executing your code in response to a Task, and responding to the [Temporal Service](/clusters) with the results. + +More formally, a Worker Process is any process that implements the Task Queue Protocol and the Task Execution Protocol. + +- A Worker Process is a Workflow Worker Process if the process implements the Workflow Task Queue Protocol and executes the Workflow Task Execution Protocol to make progress on a Workflow Execution. + A Workflow Worker Process can listen on an arbitrary number of Workflow Task Queues and can execute an arbitrary number of Workflow Tasks. +- A Worker Process is an Activity Worker Process if the process implements the Activity Task Queue Protocol and executes the Activity Task Processing Protocol to make progress on an Activity Execution. + An Activity Worker Process can listen on an arbitrary number of Activity Task Queues and can execute an arbitrary number of Activity Tasks. + +**Worker Processes are external to a Temporal Service.** +Temporal Application developers are responsible for developing [Worker Programs](#worker-program) and operating Worker Processes. +Said another way, the [Temporal Service](/clusters) (including the Temporal Cloud) doesn't execute any of your code (Workflow and Activity Definitions) on Temporal Service machines. The Temporal Service is solely responsible for orchestrating [State Transitions](/workflows#state-transition) and providing Tasks to the next available [Worker Entity](/workers#worker-entity). + +While data transferred in Event Histories is [secured by mTLS](/self-hosted-guide/security#encryption-in-transit-with-mtls), by default, it is still readable at rest in the Temporal Service. + +To solve this, Temporal SDKs offer a [Data Converter API](/dataconversion) that you can use to customize the serialization of data going out of and coming back in to a Worker Entity, with the net effect of guaranteeing that the Temporal Service cannot read sensitive business data. + +In many of our tutorials, we show you how to run both a Temporal Service and one Worker on the same machine for local development. +However, a production-grade Temporal Application typically has a _fleet_ of Worker Processes, all running on hosts external to the Temporal Service. +A Temporal Application can have as many Worker Processes as needed. + +A Worker Process can be both a Workflow Worker Process and an Activity Worker Process. +Many SDKs support the ability to have multiple Worker Entities in a single Worker Process. +(Worker Entity creation and management differ between SDKs.) +A single Worker Entity can listen to only a single Task Queue. +But if a Worker Process has multiple Worker Entities, the Worker Process could be listening to multiple Task Queues. + +![Entity relationship diagram (meta model) of Worker Processes, Task Queues, and Tasks](/diagrams/worker-and-server-entity-relationship.svg) + +Worker Processes executing Activity Tasks must have access to any resources needed to execute the actions that are defined in Activity Definitions, such as the following: + +- Network access for external API calls. +- Credentials for infrastructure provisioning. +- Specialized GPUs for machine learning utilities. + +The Temporal Service itself has [internal workers](https://temporal.io/blog/workflow-engine-principles/#system-workflows-1910) for system Workflow Executions. +However, these internal workers are not visible to the developer. diff --git a/docs/encyclopedia/workflows.mdx b/docs/encyclopedia/workflows.mdx index 54f5ca6364..9dc0a619e5 100644 --- a/docs/encyclopedia/workflows.mdx +++ b/docs/encyclopedia/workflows.mdx @@ -254,7 +254,7 @@ This feature is useful for Workflow Definition logic that needs to be updated bu - [How to patch Workflow code in TypeScript](/develop/typescript/versioning#patching) - [How to patch Workflow code in .NET](/develop/dotnet/versioning#dotnet-sdk-patching-api) -You can also use [Worker Versioning](/workers#worker-versioning) instead of Patching. +You can also use [Worker Versioning](/worker-versioning) instead of Patching. ### Handling unreliable Worker Processes @@ -454,7 +454,7 @@ These limits are set with the following [dynamic configuration keys](https://git ### What is a Command? {#command} -A Command is a requested action issued by a [Worker](/workers#worker) to the [Temporal Service](/clusters) after a [Workflow Task Execution](/workers#workflow-task-execution) completes. +A Command is a requested action issued by a [Worker](/workers#worker) to the [Temporal Service](/clusters) after a [Workflow Task Execution](/tasks#workflow-task-execution) completes. The action that the Temporal Service takes is recorded in the [Workflow Execution's](#workflow-execution) [Event History](#event-history) as an [Event](#event). The Workflow Execution can await on some of the Events that come as a result from some of the Commands. @@ -479,7 +479,7 @@ A list of all possible Events that could appear in a Workflow Execution Event Hi Seven Activity-related Events are added to Event History at various points in an Activity Execution: -- After a [Workflow Task Execution](/workers#activity-task-execution) reaches a line of code that starts/executes an Activity, the Worker sends the Activity Type and arguments to the Temporal Service, and the Temporal Service adds an [ActivityTaskScheduled](/references/events#activitytaskscheduled) Event to Event History. +- After a [Workflow Task Execution](/tasks#activity-task-execution) reaches a line of code that starts/executes an Activity, the Worker sends the Activity Type and arguments to the Temporal Service, and the Temporal Service adds an [ActivityTaskScheduled](/references/events#activitytaskscheduled) Event to Event History. - When `ActivityTaskScheduled` is added to History, the Temporal Service adds a corresponding Activity Task to the Task Queue. - A Worker polling that Task Queue picks up the Activity Task and runs the Activity function or method. - If the Activity function returns, the Worker reports completion to the Temporal Service, and the Temporal Service adds [ActivityTaskStarted](/references/events#activitytaskstarted) and [ActivityTaskCompleted](/references/events#activitytaskcompleted) to Event History. @@ -1116,4 +1116,4 @@ Some operations, such as [Activity Heartbeats](/encyclopedia/detecting-activity- Most operations require multiple State Transitions. -For example, a simple Workflow with two sequential [Activity Tasks](/workers#activity-task) (and no retries) produces 11 State Transitions: two for Workflow start, four for each Activity, and one for Workflow completion. +For example, a simple Workflow with two sequential [Activity Tasks](/tasks#activity-task) (and no retries) produces 11 State Transitions: two for Workflow start, four for each Activity, and one for Workflow completion. diff --git a/docs/glossary.md b/docs/glossary.md index 2b9711e65e..d75845bc1e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -59,13 +59,13 @@ A unique identifier for an Activity Execution. -#### [Activity Task](/workers#activity-task) +#### [Activity Task](/tasks#activity-task) An Activity Task contains the context needed to make an Activity Task Execution. -#### [Activity Task Execution](/workers#activity-task-execution) +#### [Activity Task Execution](/tasks#activity-task-execution) An Activity Task Execution occurs when a Worker uses the context provided from the Activity Task and executes the Activity Definition. @@ -520,25 +520,25 @@ A State Transition is a unit of progress by a Workflow Execution. -#### [Sticky Execution](/workers#sticky-execution) +#### [Sticky Execution](/sticky-execution) A Sticky Execution is a when a Worker Entity caches the Workflow Execution Event History and creates a dedicated Task Queue to listen on. -#### [Task](/workers#task) +#### [Task](/tasks#task) A Task is the context needed to make progress with a specific Workflow Execution or Activity Execution. -#### [Task Queue](/workers#task-queue) +#### [Task Queue](/task-queue) A Task Queue is a first-in, first-out queue that a Worker Process polls for Tasks. -#### [Task Routing](/workers#task-routing) +#### [Task Routing](/task-routing) Task Routing is when a Task Queue is paired with one or more Worker Processes, primarily for Activity Task Executions. @@ -698,7 +698,7 @@ The Worker Service runs background processing for the replication queue, system -#### [Worker Session](/workers#worker-session) +#### [Worker Session](/task-routing#worker-session) A Worker Session is a feature provided by some SDKs that provides a straightforward way to ensure that Activity Tasks are executed with the same Worker without requiring you to manually specify Task Queue names. @@ -758,13 +758,13 @@ This is the maximum amount of time that a single Workflow Run is restricted to. -#### [Workflow Task](/workers#workflow-task) +#### [Workflow Task](/tasks#workflow-task) A Workflow Task is a Task that contains the context needed to make progress with a Workflow Execution. -#### [Workflow Task Execution](/workers#workflow-task-execution) +#### [Workflow Task Execution](/tasks#workflow-task-execution) A Workflow Task Execution occurs when a Worker picks up a Workflow Task and uses it to make progress on the execution of a Workflow Definition. diff --git a/docs/production-deployment/cloud/account-setup/namespaces.mdx b/docs/production-deployment/cloud/account-setup/namespaces.mdx index 99d28eced6..43a086b4f8 100644 --- a/docs/production-deployment/cloud/account-setup/namespaces.mdx +++ b/docs/production-deployment/cloud/account-setup/namespaces.mdx @@ -249,7 +249,7 @@ Before considering an appropriate Namespace configuration, you should be aware o - A Namespace is an endpoint. To access a Namespace from a Temporal Client requires mTLS authorization, which requires [CA certificates](/cloud/certificates#ca-certificates). - [Workflow Id](/workflows#workflow-id) uniqueness is per Namespace. -- [Task Queue](/workers#task-queue) names are unique per Namespace. +- [Task Queue](/task-queue) names are unique per Namespace. - Closed Workflow retention is per Namespace. - RBAC [permissions](/cloud/users#namespace-level-permissions) are implemented at the Namespace level. diff --git a/docs/production-deployment/cloud/nexus/latency-availability.mdx b/docs/production-deployment/cloud/nexus/latency-availability.mdx index 69b134c971..60eaad13fc 100644 --- a/docs/production-deployment/cloud/nexus/latency-availability.mdx +++ b/docs/production-deployment/cloud/nexus/latency-availability.mdx @@ -45,7 +45,7 @@ This applies to the following Nexus-related interactions between a Worker and Te - Caller Namespace - RespondWorkflowTaskCompleted \- schedule a Nexus Operation. - Handler Namespace - - PollNexusTaskQueue \- get a [Nexus Task](/workers#nexus-task) to process, for example to start a Nexus Operation. + - PollNexusTaskQueue \- get a [Nexus Task](/tasks#nexus-task) to process, for example to start a Nexus Operation. - RespondNexusTaskCompleted \- report the Nexus Task was successful. - RespondNexusTaskFailed \- report the Nexus Task failed. diff --git a/docs/references/commands.mdx b/docs/references/commands.mdx index 38294b66a4..b9fb9ee62d 100644 --- a/docs/references/commands.mdx +++ b/docs/references/commands.mdx @@ -10,7 +10,7 @@ tags: - Reference --- -A [Command](/workflows#command) is a requested action issued by a [Worker](/workers#worker) to the [Temporal Service](/clusters) after a [Workflow Task Execution](/workers#workflow-task-execution) completes. +A [Command](/workflows#command) is a requested action issued by a [Worker](/workers#worker) to the [Temporal Service](/clusters) after a [Workflow Task Execution](/tasks#workflow-task-execution) completes. The following is a complete list of possible Commands. @@ -84,7 +84,7 @@ By default, you cannot schedule more than 2,000 Activities concurrently. ### RequestCancelActivityTask -This Command is triggered by a call to request the cancellation of an [Activity Task](/workers#activity-task). +This Command is triggered by a call to request the cancellation of an [Activity Task](/tasks#activity-task). - Awaitable: No, a Workflow Execution can not await on the action resulting from this Command. - Corresponding Event: [ActivityTaskCancelRequested](/references/events#activitytaskcancelrequested) diff --git a/docs/references/errors.mdx b/docs/references/errors.mdx index 5c952a18bb..5996cfbf52 100644 --- a/docs/references/errors.mdx +++ b/docs/references/errors.mdx @@ -12,7 +12,7 @@ tags: - Reference --- -This reference lists possible [Workflow Task](/workers#workflow-task) errors and how to resolve them. +This reference lists possible [Workflow Task](/tasks#workflow-task) errors and how to resolve them. > For other types of errors, see [Temporal Failures](https://docs.temporal.io/kb/failures). @@ -20,7 +20,7 @@ Each of the below errors corresponds with a [WorkflowTaskFailedCause](https://ap ## Bad Cancel Timer Attributes {#bad-cancel-timer-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed while attempting to cancel a Timer. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed while attempting to cancel a Timer. {/* TODO add Timer term definition and link to it */} @@ -29,20 +29,20 @@ Add a valid Timer Id and redeploy the code. ## Bad Cancel Workflow Execution Attributes {#bad-cancel-workflow-execution-attributes} -The [Workflow Task](/workers#workflow-task) failed due to unset [CancelWorkflowExecution](/references/commands#cancelworkflowexecution) attributes. +The [Workflow Task](/tasks#workflow-task) failed due to unset [CancelWorkflowExecution](/references/commands#cancelworkflowexecution) attributes. Reset any missing attributes and redeploy the Workflow Task. ## Bad Complete Workflow Execution Attributes {#bad-complete-workflow-execution-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed due to unset attributes on [CompleteWorkflowExecution](/references/commands#completeworkflowexecution). +This error indicates that the [Workflow Task](/tasks#workflow-task) failed due to unset attributes on [CompleteWorkflowExecution](/references/commands#completeworkflowexecution). Reset any missing attributes. Adjust the size of your Payload if it exceeds size limits. ## Bad Continue as New Attributes {#bad-continue-as-new-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed to validate a [ContinueAsNew](/references/commands#continueasnewworkflowexecution) attribute. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed to validate a [ContinueAsNew](/references/commands#continueasnewworkflowexecution) attribute. The attribute could be unset or invalid. Reset any missing attributes. @@ -52,14 +52,14 @@ Check that the [Workflow](/workflows) is validating search attributes after unal ## Bad Fail Workflow Execution Attributes {#bad-fail-workflow-execution-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed due to unset [FailWorkflowExecution](/references/commands#failworkflowexecution) attributes. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed due to unset [FailWorkflowExecution](/references/commands#failworkflowexecution) attributes. If you encounter this error, make sure that `StartToClostTimeout` or `ScheduleToCloseTimeout` are set. Restart the [Worker](/workers) that the [Workflow](/workflows) and [Activity](/activities) are registered to. ## Bad Modify Workflow Properties Attributes {#bad-modify-workflow-properties-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed to validate attributes on a property in the Upsert Memo or in a payload. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed to validate attributes on a property in the Upsert Memo or in a payload. These attributes are either unset or exceeding size limits. Reset any unset and empty attributes. @@ -67,7 +67,7 @@ Adjust the size of the [Memo](/workflows#memo) or payload to fit within the syst ## Bad Record Marker Attributes {#bad-record-marker-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed due to an unset or incorrect [Marker](/references/events#markerrecorded) name. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed due to an unset or incorrect [Marker](/references/events#markerrecorded) name. Enter a valid Marker name and redeploy the Task. @@ -76,13 +76,13 @@ Enter a valid Marker name and redeploy the Task. This error either indicates the possibility of unset attributes for [RequestCancelActivity](/references/commands#requestcancelactivitytask), or an invalid History Builder state. Update the [Temporal SDK](/encyclopedia/temporal-sdks) to the most recent release. -Reset any unset attributes before retrying the [Workflow Task](/workers#workflow-task). +Reset any unset attributes before retrying the [Workflow Task](/tasks#workflow-task). If you continue to see this error, review your code for [nondeterministic causes](/workflows#non-deterministic-change). ## Bad Request Cancel External Workflow Execution Attributes {#bad-request-cancel-external-workflow-execution} -This error indicates that the [Workflow Task](/workers#workflow-task) failed while trying to cancel an external Workflow. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed while trying to cancel an external Workflow. Unset or invalid attributes can cause this to occur. Reset any missing attributes, such as Workflow Id or Run Id. @@ -106,7 +106,7 @@ Inspect the reason given in the error for mitigation when possible. ## Bad Search Attributes {#bad-search-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) has unset or invalid [Search Attributes](/visibility#search-attribute). +This error indicates that the [Workflow Task](/tasks#workflow-task) has unset or invalid [Search Attributes](/visibility#search-attribute). This can cause Workflow Tasks to continue to retry without success. Make sure that all attributes are defined before retrying the Task. @@ -116,18 +116,18 @@ Adjust the size of the Payload to fit within the system's size limits. This error indicates that the Payload has exceeded the [Signal's](/encyclopedia/workflow-message-passing#sending-signals) available input size. -Adjust the size of the Payload, and redeploy the [Workflow Task](/workers#workflow-task). +Adjust the size of the Payload, and redeploy the [Workflow Task](/tasks#workflow-task). ## Bad Signal Workflow Execution Attributes {#bad-signal-workflow-execution-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed to validate attributes for [SignalExternalWorkflowExecution](/references/commands#signalexternalworkflowexecution). +This error indicates that the [Workflow Task](/tasks#workflow-task) failed to validate attributes for [SignalExternalWorkflowExecution](/references/commands#signalexternalworkflowexecution). Reset any unset, missing, nil, or invalid attributes. Adjust the input to fit within the system's size limits. ## Bad Start Child Execution Attributes {#bad-start-child-execution-attributes} -This error indicates that the [Workflow Task](/workers#workflow-task) failed to validate attributes for [`StartChildWorkflowExecution`](/references/commands#startchildworkflowexecution) +This error indicates that the [Workflow Task](/tasks#workflow-task) failed to validate attributes for [`StartChildWorkflowExecution`](/references/commands#startchildworkflowexecution) Adjust the input size of the attributes to fall within the system's size limits. @@ -139,7 +139,7 @@ This error indicates that the scheduled [Event](/workflows#event) is missing a T {/* TODO add Timer Id as anchor for term and link to it */} -Set a valid Timer Id and retry the [Workflow Task](/workers#workflow-task). +Set a valid Timer Id and retry the [Workflow Task](/tasks#workflow-task). ## Cause Bad Binary {#cause-bad-binary} @@ -160,7 +160,7 @@ Make sure you're using a [supported SDK](/encyclopedia/temporal-sdks). ## Cause Reset Workflow {#cause-reset-workflow} -This error indicates that the [Workflow Task](/workers#workflow-task) failed due to a request to reset the [Workflow](/workflows). +This error indicates that the [Workflow Task](/tasks#workflow-task) failed due to a request to reset the [Workflow](/workflows). If the system hasn't started a new Workflow, manually reset the Workflow. @@ -174,41 +174,41 @@ This error can happen when the Workflow receives frequent Updates. ## Cause Unspecified {#cause-unspecified} -This error indicates that the [Workflow Task](/workers#workflow-task) has failed for an unknown reason. +This error indicates that the [Workflow Task](/tasks#workflow-task) has failed for an unknown reason. If you see this error, examine your Workflow Definition. ## Failover Close Command {#failover-close-command} -This error indicates that a [Namespace](/namespaces) failover forced the [Workflow Task](/workers#workflow-task) to close. +This error indicates that a [Namespace](/namespaces) failover forced the [Workflow Task](/tasks#workflow-task) to close. The system automatically schedules a retry when this error occurs. {/* TODO: troubleshooting */} ## Force Close Command {#force-close-command} -This error indicates that the [Workflow Task](/workers#workflow-task) was forced to close. +This error indicates that the [Workflow Task](/tasks#workflow-task) was forced to close. A retry will be scheduled if the error is recoverable. {/* TODO: more info */} ## Nondeterminism Error {#non-deterministic-error} -The [Workflow Task](/workers#workflow-task) failed due to a [nondeterminism error](/workflows#non-deterministic-change). +The [Workflow Task](/tasks#workflow-task) failed due to a [nondeterminism error](/workflows#non-deterministic-change). {/* TODO: info */} ## Pending Activities Limit Exceeded {#pending-activities-limit-exceeded} The [Workflow](/workflows) has reached capacity for pending [Activities](/activities). -Therefore, the [Workflow Task](/workers#workflow-task) was failed to prevent the creation of another Activity. +Therefore, the [Workflow Task](/tasks#workflow-task) was failed to prevent the creation of another Activity. Let the Workflow complete any current Activities before redeploying the code. ## Pending Child Workflows Limit Exceeded {#pending-child-workflows-limit-exceeded} This error indicates that the [Workflow](/workflows) has reached capacity for pending [Child Workflows](/encyclopedia/child-workflows). -Therefore, the [Workflow Task](/workers#workflow-task) was failed to prevent additional Child Workflows from being added. +Therefore, the [Workflow Task](/tasks#workflow-task) was failed to prevent additional Child Workflows from being added. Wait for the system to finish any currently running Child Workflows before redeploying this Task. @@ -228,7 +228,7 @@ See [Per Workflow Nexus Operation Limits](/cloud/limits#per-workflow-nexus-opera ## Pending Request Cancel Limit Exceeded {#pending-request-cancel-limit-exceeded} -This error indicates that the [Workflow Task](/workers#workflow-task) failed after attempting to add more cancel requests. +This error indicates that the [Workflow Task](/tasks#workflow-task) failed after attempting to add more cancel requests. The [Workflow](/workflows) has reached capacity for pending requests to cancel other Workflows, and cannot accept more requests. If you see this error, give the system time to process pending requests before retrying the Task. @@ -236,13 +236,13 @@ If you see this error, give the system time to process pending requests before r ## Pending Signals Limit Exceeded {#pending-signals-limit-exceeded} The Workflow has reached capacity for pending Signals. -Therefore, the [Workflow Task](/workers#workflow-task) was failed after attempting to add more [Signals](/encyclopedia/workflow-message-passing#sending-signals) to an external Workflow. +Therefore, the [Workflow Task](/tasks#workflow-task) was failed after attempting to add more [Signals](/encyclopedia/workflow-message-passing#sending-signals) to an external Workflow. Wait for Signals to be processed by the Workflow before retrying the Task. ## Reset Sticky Task Queue {#reset-sticky-task-queue} -This error indicates that the Sticky [Task Queue](/workers#task-queue) needs to be reset. +This error indicates that the Sticky [Task Queue](/task-queue) needs to be reset. If you see this error, reset the Sticky Task Queue. The system will retry automatically. @@ -269,19 +269,19 @@ This error indicates that the [Workflow](/workflows) has exhausted its RPS limit ## Resource Exhausted Cause System Overload {#resource-exhausted-cause-system-overload} -This error indicates that the system is overloaded and cannot allocate further resources to [Workflow Tasks](/workers#workflow-task). +This error indicates that the system is overloaded and cannot allocate further resources to [Workflow Tasks](/tasks#workflow-task). {/* TODO: more info needed */} ## Resource Exhausted Cause Unspecified {#resource-exhausted-cause-unspecified} -This error indicates that an unknown cause is preventing resources from being allocated to further [Workflow Tasks](/workers#workflow-task). +This error indicates that an unknown cause is preventing resources from being allocated to further [Workflow Tasks](/tasks#workflow-task). {/* TODO: more info needed */} ## Schedule Activity Duplicate Id {#schedule-activity-duplicate-id} -The [Workflow Task](/workers#workflow-task) failed because the [Activity](/activities) Id is already in use. +The [Workflow Task](/tasks#workflow-task) failed because the [Activity](/activities) Id is already in use. Check your code to see if you've already specified the same Activity Id in your [Workflow](/workflows). Enter another Activity Id, and try running the Workflow Task again. @@ -292,11 +292,11 @@ This error indicates that a Timer with the given Timer Id has already started. {/* TODO link to Timer term when exists */} -Try entering a different Timer Id, and retry the [Workflow Task](/workers#workflow-task). +Try entering a different Timer Id, and retry the [Workflow Task](/tasks#workflow-task). ## Unhandled Command {#unhandled-command} -This error indicates new available [Events](/references/events) since the last [Workflow Task](/workers#workflow-task) started. +This error indicates new available [Events](/references/events) since the last [Workflow Task](/tasks#workflow-task) started. The Workflow Task was failed because the [Workflow](/workflows) attempted to close itself without handling the new Events. `UnhandledCommand` can happen when the Workflow is receiving a high number of [Signals](/encyclopedia/workflow-message-passing#sending-signals). @@ -309,6 +309,6 @@ The Workflow may have been picked up by a different [Worker](/workers#worker). ## Workflow Worker Unhandled Failure {#workflow-worker-unhandled-failure} -This error indicates that the [Workflow Task](/workers#workflow-task) encountered an unhandled failure from the [Workflow Definition](/workflows#workflow-definition). +This error indicates that the [Workflow Task](/tasks#workflow-task) encountered an unhandled failure from the [Workflow Definition](/workflows#workflow-definition). {/* TODO: more info needed */} diff --git a/docs/references/events.mdx b/docs/references/events.mdx index 81dbd69823..ef75dc069c 100644 --- a/docs/references/events.mdx +++ b/docs/references/events.mdx @@ -24,7 +24,7 @@ It indicates that the Temporal Service received a request to spawn the Workflow | parent_workflow_namespace | The [Namespace](/namespaces) of the Parent [Workflow Execution](/workflows#workflow-execution), if applicable. | | parent_workflow_execution | Identifies the parent Workflow and the execution run. | | parent_initiated_event_id | Id of the [StartWorkflowExecutionInitiated](#startchildworkflowexecutioninitiated) Event this Event corresponds to. | -| task_queue | The [Task Queue](/workers#task-queue) that this [Workflow Task](/workers#workflow-task) was enqueued in. | +| task_queue | The [Task Queue](/task-queue) that this [Workflow Task](/tasks#workflow-task) was enqueued in. | | input | Information that is deserialized by the SDK to provide arguments to the Workflow. | | workflow_execution_timeout | The total timeout period for a [Workflow Execution](/workflows#workflow-execution), including retries and continue-as-new. | | workflow_run_timeout | Timeout of a single Workflow run. | @@ -32,7 +32,7 @@ It indicates that the Temporal Service received a request to spawn the Workflow | continued_execution_run_id | [Run Id](/workflows#run-id) of the previous Workflow which continued-as-new, retried or was executed by Cron into this Workflow. | | initiator | Allows the Workflow to continue as a new Workflow Execution. | | continued_failure | Serialized result of a failure. | -| last_completion_result | Information from the previously completed [Task](/workers#task), if applicable. | +| last_completion_result | Information from the previously completed [Task](/tasks#task), if applicable. | | original_execution_run_id | The [Run Id](/workflows#run-id) of the original Workflow started. | | identity | The Id of the [Client](/self-hosted-guide/security#client-connections) or parent Workflow [Worker](/workers#worker) that requested the start of this Workflow. | | first_execution_run_id | The first [Run Id](/workflows#run-id), along the chain of [Continue-As-New](/workflows#continue-as-new) Runs and Reset. | @@ -44,7 +44,7 @@ It indicates that the Temporal Service received a request to spawn the Workflow | memo | Non-indexed information to show in the Workflow. | | search_attributes | Provides data for setting up a Workflow's [Search Attributes](/visibility#search-attribute). | | prev_auto_reset_points | | -| header | Information passed by the sender of the [Signal](/encyclopedia/workflow-message-passing#sending-signals) that is copied into the [Workflow Task](/workers#workflow-task). | +| header | Information passed by the sender of the [Signal](/encyclopedia/workflow-message-passing#sending-signals) that is copied into the [Workflow Task](/tasks#workflow-task). | ### WorkflowExecutionCompleted @@ -63,7 +63,7 @@ This [Event](/workflows#event) indicates that the [Workflow Execution](/workflow | Field | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | failure | Serialized result of a [Workflow](/workflows) failure. | -| retry_state | The reason provided for whether the [Task](/workers#task) should or shouldn't be retried. | +| retry_state | The reason provided for whether the [Task](/tasks#task) should or shouldn't be retried. | | workflow_task_completed_event_id | The [Run Id](/workflows#run-id) of the [WorkflowTaskCompleted](#workflowtaskcompleted) that the Event was reported with. | | new_execution_run_id | The [Run Id](/workflows#run-id) of the new Workflow started by Cron or [Retry](/encyclopedia/retry-policies). | @@ -73,7 +73,7 @@ This [Event](/workflows#event) type indicates that the [Workflow Execution](/wor | Field | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------- | -| retry_state | The reason provided for whether the [Task](/workers#task) should or shouldn't be retried. | +| retry_state | The reason provided for whether the [Task](/tasks#task) should or shouldn't be retried. | | new_execution_run_id | The [Run Id](/workflows#run-id) of the new Workflow started by Cron or [Retry](/encyclopedia/retry-policies). | ### WorkflowExecutionCancelRequested @@ -106,7 +106,7 @@ The Event type contains the Signal name and a Signal payload. | signal_name | The name/type of Signal to be fired. | | input | Information that is deserialized by the SDK to provide arguments to the Workflow function. | | identity | Identifies the [Worker](/workers#worker) that signaled to the Workflow. | -| header | Information passed by the sender of the Signal that is copied into the [Workflow Task](/workers#workflow-task). | +| header | Information passed by the sender of the Signal that is copied into the [Workflow Task](/tasks#workflow-task). | ### WorkflowExecutionTerminated @@ -127,7 +127,7 @@ This Event type contains last [Workflow Execution](/workflows#workflow-execution | -------------------------------- | ------------------------------------------------------------------------------------------------------------- | | new_execution_run_id | The [Run Id](/workflows#run-id) of the new Workflow started by this Continue-As-New Event. | | workflow_type | The name/type of Workflow that was started by this Event. | -| task_queue | The [Task Queue](/workers#task-queue) that this [Workflow Task](/workers#workflow-task) was enqueued in. | +| task_queue | The [Task Queue](/task-queue) that this [Workflow Task](/tasks#workflow-task) was enqueued in. | | input | Information that is deserialized by the SDK to provide arguments to the Workflow. | | workflow_run_timeout | Timeout of a single Workflow run. | | workflow_task_timeout | Timeout of a single Workflow Task. | @@ -141,18 +141,18 @@ This Event type contains last [Workflow Execution](/workflows#workflow-execution ### WorkflowTaskScheduled -This [Event](/workflows#event) type indicates that the [Workflow Task](/workers#workflow-task) has been scheduled. +This [Event](/workflows#event) type indicates that the [Workflow Task](/tasks#workflow-task) has been scheduled. The SDK client should now be able to process any new history events. | Field | Description | | ---------------------- | ------------------------------------------------------------------------------------------ | -| task_queue | The [Task Queue](/workers#task-queue) that this Workflow Task was enqueued in. | +| task_queue | The [Task Queue](/task-queue) that this Workflow Task was enqueued in. | | start_to_close_timeout | The time that the [Worker](/workers#worker) takes to process this Task once it's received. | | attempt | The number of attempts that have been made to complete this Task. | ### WorkflowTaskStarted -This [Event](/workflows#event) type indicates that the [Workflow Task](/workers#workflow-task) has started. +This [Event](/workflows#event) type indicates that the [Workflow Task](/tasks#workflow-task) has started. The SDK client has picked up the Workflow Task and is processing new history events. | Field | Description | @@ -163,7 +163,7 @@ The SDK client has picked up the Workflow Task and is processing new history eve ### WorkflowTaskCompleted -This [Event](/workflows#event) type indicates that the [Workflow Task](/workers#workflow-task) completed. +This [Event](/workflows#event) type indicates that the [Workflow Task](/tasks#workflow-task) completed. | Field | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------- | @@ -189,7 +189,7 @@ It is possible for the following events to still occur: ### WorkflowTaskTimedOut -This [Event](/workflows#event) type indicates that the [Workflow Task](/workers#workflow-task) encountered a [timeout](/encyclopedia/detecting-workflow-failures#workflow-task-timeout). +This [Event](/workflows#event) type indicates that the [Workflow Task](/tasks#workflow-task) encountered a [timeout](/encyclopedia/detecting-workflow-failures#workflow-task-timeout). Either an SDK client with a local cache was not available at the time, or it took too long for the SDK client to process the Task. | Field | Description | @@ -200,7 +200,7 @@ Either an SDK client with a local cache was not available at the time, or it too ### WorkflowTaskFailed -This [Event](/workflows#event) type indicates that the [Workflow Task](/workers#workflow-task) encountered a failure. +This [Event](/workflows#event) type indicates that the [Workflow Task](/tasks#workflow-task) encountered a failure. Usually this means that the Workflow was non-deterministic. However, the Workflow reset functionality also uses this Event. @@ -217,7 +217,7 @@ However, the Workflow reset functionality also uses this Event. ### ActivityTaskScheduled -This [Event](/workflows#event) type indicates that an [Activity Task](/workers#activity-task) was scheduled. +This [Event](/workflows#event) type indicates that an [Activity Task](/tasks#activity-task) was scheduled. The SDK client should pick up this Activity Task and execute. This Event type contains Activity inputs, as well as Activity Timeout configurations. @@ -226,8 +226,8 @@ This Event type contains Activity inputs, as well as Activity Timeout configurat | activity_id | The identifier assigned to this Activity by a [Worker](/workers#worker) or user. | | activity_type | The [type of Activity](/activities#activity-type) that was scheduled. | | namespace | Namespace of the Workflow that the [Activity](/activities) resides in. | -| task_queue | The [Task Queue](/workers#task-queue) that this Activity Task was enqueued in. | -| header | Information passed by the sender of the [Signal](/encyclopedia/workflow-message-passing#sending-signals) that is copied into the [Workflow Task](/workers#workflow-task). | +| task_queue | The [Task Queue](/task-queue) that this Activity Task was enqueued in. | +| header | Information passed by the sender of the [Signal](/encyclopedia/workflow-message-passing#sending-signals) that is copied into the [Workflow Task](/tasks#workflow-task). | | input | Information that is deserialized by the SDK to provide arguments to the [Workflow](/workflows) function. | | schedule_to_close_timeout | The amount of time that a caller will wait for Activity completion. Limits the amount of time that retries will be attempted for this Activity. | | schedule_to_start_timeout | Limits the time that an Activity Task can stay in a Task Queue. This timeout cannot be retried. | @@ -238,7 +238,7 @@ This Event type contains Activity inputs, as well as Activity Timeout configurat ### ActivityTaskStarted -This [Event](/workflows#event) type indicates that an [Activity Task Execution](/workers#activity-task-execution) was started. +This [Event](/workflows#event) type indicates that an [Activity Task Execution](/tasks#activity-task-execution) was started. The SDK Worker picked up the Activity Task and started processing the [Activity](/activities) invocation. Note, however, that this Event is not written to History until the terminal Event (like [ActivityTaskCompleted](#activitytaskcompleted) or [ActivityTaskFailed](#activitytaskfailed)) occurs. @@ -252,7 +252,7 @@ Note, however, that this Event is not written to History until the terminal Even ### ActivityTaskCompleted -This [Event](/workflows#event) type indicates that the [Activity Task](/workers#activity-task) has completed. +This [Event](/workflows#event) type indicates that the [Activity Task](/tasks#activity-task) has completed. The SDK client has picked up and successfully completed the Activity Task. This Event type contains [Activity Execution](/activities#activity-execution) results. @@ -265,7 +265,7 @@ This Event type contains [Activity Execution](/activities#activity-execution) re ### ActivityTaskFailed -This [Event](/workflows#event) type indicates that the [Activity Task](/workers#activity-task) has failed. +This [Event](/workflows#event) type indicates that the [Activity Task](/tasks#activity-task) has failed. The SDK client picked up the Activity Task but unsuccessfully completed it. This Event type contains [Activity Execution](/activities#activity-execution) errors. diff --git a/docs/tctl-v1/admin.mdx b/docs/tctl-v1/admin.mdx index 25398cd551..9bd3c6354b 100644 --- a/docs/tctl-v1/admin.mdx +++ b/docs/tctl-v1/admin.mdx @@ -1023,7 +1023,7 @@ The Id of the current run. ## refresh_tasks -The `tctl admin workflow refresh_tasks` command updates all [Tasks](/workers#task) in a [Workflow](/workflows), provided that the command can fetch new information for Tasks. +The `tctl admin workflow refresh_tasks` command updates all [Tasks](/tasks#task) in a [Workflow](/workflows), provided that the command can fetch new information for Tasks. #### --workflow_id value diff --git a/docs/tctl-v1/index.mdx b/docs/tctl-v1/index.mdx index 3cb246a088..93bb2f1bdb 100644 --- a/docs/tctl-v1/index.mdx +++ b/docs/tctl-v1/index.mdx @@ -70,7 +70,7 @@ To see help for [tctl](/tctl-v1) commands, enter the following commands. | `tctl -h` | Display help for top-level commands and global options | | `tctl namespace -h` | Display help for [Namespace](/namespaces) operations | | `tctl workflow -h` | Display help for [Workflow](/workflows) operations | -| `tctl taskqueue -h` | Display help for [Task Queue](/workers#task-queue) operations | +| `tctl taskqueue -h` | Display help for [Task Queue](/task-queue) operations | ## Global modifiers diff --git a/docs/tctl-v1/taskqueue.mdx b/docs/tctl-v1/taskqueue.mdx index 6fbefa1eb0..22c3a389ba 100644 --- a/docs/tctl-v1/taskqueue.mdx +++ b/docs/tctl-v1/taskqueue.mdx @@ -22,7 +22,7 @@ After the release of Temporal CLI v1.0, tctl will deprecate. ::: -The `tctl taskqueue` command enables [Task Queue](/workers#task-queue) operations. +The `tctl taskqueue` command enables [Task Queue](/task-queue) operations. Alias: `t` @@ -31,7 +31,7 @@ Alias: `t` ## describe -The `tctl taskqueue describe` command describes the poller information of a [Task Queue](/workers#task-queue). +The `tctl taskqueue describe` command describes the poller information of a [Task Queue](/task-queue). `tctl taskqueue describe ` @@ -41,7 +41,7 @@ The following modifiers control the behavior of the command. _Required modifier_ -Specify a [Task Queue](/workers#task-queue). +Specify a [Task Queue](/task-queue). Alias: `--t` @@ -53,7 +53,7 @@ tctl taskqueue describe --taskqueue ### --taskqueuetype -Specify the type of a [Task Queue](/workers#task-queue). +Specify the type of a [Task Queue](/task-queue). The type can be `workflow` or `activity`. The default is `workflow`. @@ -65,7 +65,7 @@ tctl taskqueue describe --taskqueue --taskqueuetype ## list-partition -The `tctl taskqueue list-partition` command lists the partitions of a [Task Queue](/workers#task-queue) and the hostname for the partitions. +The `tctl taskqueue list-partition` command lists the partitions of a [Task Queue](/task-queue) and the hostname for the partitions. `tctl taskqueue list-partition --taskqueue ` @@ -75,7 +75,7 @@ The following modifier controls the behavior of the command. _Required modifier_ -Specify a [Task Queue](/workers#task-queue) description. +Specify a [Task Queue](/task-queue) description. Alias: `--t` diff --git a/docs/tctl-v1/workflow.mdx b/docs/tctl-v1/workflow.mdx index bba4a82bf0..7b727916e1 100644 --- a/docs/tctl-v1/workflow.mdx +++ b/docs/tctl-v1/workflow.mdx @@ -50,7 +50,7 @@ The `tctl workflow` commands enable [Workflow Execution](/workflows#workflow-exe The `tctl workflow cancel --query` command cancels a [Workflow Execution](/workflows#workflow-execution). Canceling a running Workflow Execution records a `WorkflowExecutionCancelRequested` event in the History. -A new [Workflow Task](/workers#workflow-task) will be scheduled. +A new [Workflow Task](/tasks#workflow-task) will be scheduled. After cancellation, the Workflow Execution can perform cleanup work. See also [`tctl workflow terminate --query`](#terminate). @@ -1219,7 +1219,7 @@ The following modifiers control the behavior of the command. ### --taskqueue -Specify a [Task Queue](/workers#task-queue). +Specify a [Task Queue](/task-queue). Alias: `--t` @@ -1264,7 +1264,7 @@ tctl workflow run --execution_timeout ### --workflow_task_timeout -Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/workers#workflow-task) in seconds. +Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/tasks#workflow-task) in seconds. The default value is 10. **Example** @@ -1979,7 +1979,7 @@ Always include required modifiers when executing this command. ### --taskqueue -Specify a [Task Queue](/workers#task-queue). +Specify a [Task Queue](/task-queue). Alias: `--t` @@ -2035,7 +2035,7 @@ tctl workflow start --execution_timeout ### --workflow_task_timeout -Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/workers#workflow-task) in seconds. +Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/tasks#workflow-task) in seconds. The default value is 10. **Example** @@ -2183,7 +2183,7 @@ tctl workflow start --search_attr_value The `tctl workflow terminate` command terminates a [Workflow Execution](/workflows#workflow-execution). Terminating a running Workflow Execution records a `WorkflowExecutionTerminated` event as the closing event in the History. -No more [Workflow Task](/workers#workflow-task) will be scheduled. +No more [Workflow Task](/tasks#workflow-task) will be scheduled. See also [`tctl workflow cancel`](#cancel). diff --git a/docs/web-ui.mdx b/docs/web-ui.mdx index 10f6a8e6ea..8f500ff4bd 100644 --- a/docs/web-ui.mdx +++ b/docs/web-ui.mdx @@ -63,7 +63,7 @@ The top of the page lists the following execution metadata: - [Workflow Type](/workflows#workflow-type) - [Run ID](/workflows#run-id) - Start Time and Close Time -- [Task Queue](/workers#task-queue) +- [Task Queue](/task-queue) - Parent and Parent ID - [State Transitions](/workflows#state-transition) diff --git a/sidebars.js b/sidebars.js index 89844d8609..7cc8070cc6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -516,7 +516,22 @@ module.exports = { "encyclopedia/retry-policies", ], }, - "encyclopedia/workers", + { + type: "category", + label: "Workers", + collapsed: true, + link: { + type: "doc", + id: "encyclopedia/workers/workers", + }, + items: [ + "encyclopedia/workers/tasks", + "encyclopedia/workers/task-queues", + "encyclopedia/workers/task-routing-worker-sessions", + "encyclopedia/workers/sticky-execution", + "encyclopedia/workers/worker-versioning", + ], + }, "encyclopedia/workflow-message-passing", "encyclopedia/child-workflows", "encyclopedia/visibility", diff --git a/vercel.json b/vercel.json index a5eb5ba9eb..d73ebb0e88 100644 --- a/vercel.json +++ b/vercel.json @@ -1146,11 +1146,11 @@ }, { "source": "/concepts/what-is-an-activity-task", - "destination": "/workers#activity-task" + "destination": "/tasks#activity-task" }, { "source": "/concepts/what-is-an-activity-task-execution", - "destination": "/workers#activity-task-execution" + "destination": "/tasks#activity-task-execution" }, { "source": "/concepts/what-is-an-activity-type", @@ -1266,15 +1266,15 @@ }, { "source": "/concepts/what-is-a-sticky-execution", - "destination": "/workers#sticky-execution" + "destination": "/sticky-execution" }, { "source": "/concepts/what-is-a-task-queue", - "destination": "/workers#task-queue" + "destination": "/task-queue" }, { "source": "/concepts/what-is-task-routing", - "destination": "/workers#task-routing" + "destination": "/task-routing" }, { "source": "/concepts/what-is-a-task-token", @@ -1358,7 +1358,7 @@ }, { "source": "/concepts/what-is-a-workflow-task-execution", - "destination": "/workers#workflow-task-execution" + "destination": "/tasks#workflow-task-execution" }, { "source": "/concepts/what-is-a-workflow-task-timeout",