You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/develop/python/continue-as-new.mdx
+83-20Lines changed: 83 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,36 +17,99 @@ tags:
17
17
- Temporal SDKs
18
18
---
19
19
20
-
**How to Continue-As-New using the Temporal Python SDK.**
20
+
This page answers the following questions for Python developers:
21
21
22
-
[Continue-As-New](/workflow-execution/continue-as-new) enables a Workflow Execution to close successfully and create a new Workflow Execution in a single atomic operation if the number of Events in the Event History is becoming too large.
23
-
The Workflow Execution spawned from the use of Continue-As-New has the same Workflow Id, a new Run Id, and a fresh Event History and is passed all the appropriate parameters.
22
+
-[What is Continue-As-New?](#what)
23
+
-[How to Continue-As-New?](#how)
24
+
-[When is it right to Continue-as-New?](#when)
25
+
-[How to test Continue-as-New?](#how-to-test)
24
26
25
-
To Continue-As-New in Python, call the [`continue_as_new()`](https://python.temporal.io/temporalio.workflow.html#continue_as_new) function from inside your Workflow, which will stop the Workflow immediately and Continue-As-New.
27
+
## What is Continue-As-New? {#what}
28
+
29
+
[Continue-As-New](/workflow-execution/continue-as-new) lets a Workflow Execution close successfully and creates a new Workflow Execution.
30
+
You can think of it as a checkpoint when your Workflow gets too long or approaches certain scaling limits.
31
+
32
+
The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History.
33
+
It also receives your Workflow's usual parameters.
34
+
35
+
## How to Continue-As-New using the Python SDK {#how}
36
+
37
+
First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run.
38
+
This state is typically set to `None` for the original caller of the Workflow.
in the context of the rest of the application code.
66
+
</div>
34
67
```python
35
-
# ...
36
-
@workflow.defn
37
-
classLoopingWorkflow:
38
-
@workflow.run
39
-
asyncdefrun(self, iteration: int) -> None:
40
-
if iteration ==5:
41
-
return
42
-
await asyncio.sleep(10)
43
-
workflow.continue_as_new(iteration +1)
44
-
```
68
+
workflow.continue_as_new(
69
+
ClusterManagerInput(
70
+
state=self.state,
71
+
test_continue_as_new=input.test_continue_as_new,
72
+
)
73
+
)
74
+
````
45
75
46
-
:::warning Using Continue-as-New and Updates
76
+
### Considerations for Workflows with Message Handlers {#with-message-handlers}
47
77
48
-
- Temporal _does not_ support Continue-as-New functionality within Update handlers.
49
-
- Complete all handlers _before_ using Continue-as-New.
50
-
- Use Continue-as-New from your main Workflow Definition method, just as you would complete or fail a Workflow Execution.
78
+
If you use Updates or Signals, don't call Continue-as-New from the handlers.
79
+
Instead, wait for your handlers to finish in your main Workflow before you run `continue_as_new`.
80
+
See the [`all_handlers_finished`](message-passing#wait-for-message-handlers) example for guidance.
51
81
52
-
:::
82
+
## When is it right to Continue-as-New using the Python SDK? {#when}
83
+
84
+
Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history).
85
+
86
+
Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New.
87
+
Call `workflow.info().is_continue_as_new_suggested()` to check if it's time.
88
+
89
+
## How to test Continue-as-New using the Python SDK {#how-to-test}
90
+
91
+
Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive.
92
+
Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests.
93
+
94
+
For example, when `test_continue_as_new ==True`, this sample creates a test-only variable called `self.max_history_length`and sets it to a small value.
95
+
A helper method in the Workflow checks it each time it considers using Continue-as-New:
Copy file name to clipboardExpand all lines: docs/develop/worker-performance.mdx
+56-38Lines changed: 56 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,7 +35,7 @@ They're used for both Workflow and Activity Tasks.
35
35
When a Worker starts processing a Task, it occupies one slot.
36
36
The number of available slots directly affects how many tasks a Worker can handle simultaneously.
37
37
38
-
### Slot suppliers
38
+
### Slot suppliers{#slot-suppliers}
39
39
40
40
A **Slot Supplier** defines a strategy to provide slots for a Worker, increasing or decreasing the Worker's slot count.
41
41
The supplier determines when it's acceptable to begin a new Task.
@@ -81,6 +81,8 @@ Available slot suppliers include:
81
81
**Worker tuning** lets you manage and customize a Worker's runtime performance characteristics.
82
82
They use special types called **Worker tuners** that assign slot suppliers to various Task Types, including Worker, Activity, Nexus, and Local Activity Tasks.
83
83
84
+
For more on how to configure and use Worker tuners, see [Worker runtime performance tuning](#worker-performance-tuning) below.
85
+
84
86
:::caution
85
87
86
88
- Worker tuners supersede the existing `maxConcurrentXXXTask` style Worker options.
@@ -90,12 +92,13 @@ They use special types called **Worker tuners** that assign slot suppliers to va
90
92
91
93
### Task pollers {#task-poller}
92
94
93
-
A Worker's **Task pollers** play a crucial role in the Temporal architecture by efficiently distributing work to Workers to support scalable, resilient Workflow Execution.
94
-
It actively polls a Task Queue for Tasks to process.
95
+
A Worker's **Task pollers** play a crucial role in the Temporal architecture by efficiently
96
+
distributing work to Workers to support scalable, resilient Workflow Execution.
97
+
They actively poll a Task Queue for Tasks to process.
95
98
Pollers create long-polling connections to the Temporal Service, allowing the service to dispatch Tasks to Workers.
96
-
When a Task Poller receives a Task, it delivers it to the appropriate Executor Slot for processing.
99
+
When a Task Poller receives a Task, it delivers to the appropriate Executor Slot for processing.
97
100
98
-
Task Pollers enable efficient load balancing across multiple Worker processes and support server-side throttling.
101
+
Task Pollers enable efficient load balancing across multiple Worker processes.
99
102
The number of Task Pollers can be configured using `WorkerOptions` when creating a new Worker instance.
100
103
101
104
## Performance metrics for tuning {#metrics}
@@ -125,10 +128,6 @@ For more information about `schedule_to_start` timeout and latency, see [Schedul
125
128
126
129
The [`sticky_cache_size`](/references/sdk-metrics#sticky_cache_size) and [`workflow_active_thread_count`](/references/sdk-metrics#workflow_active_thread_count) metrics report the size of the Workflow cache and the number of cached Workflow threads.
127
130
128
-
:::note
129
-
Server version ≥ 1.8.0 is required for access to these performance metrics for the JavaSDK.
130
-
:::
131
-
132
131
## Worker performance options {#configuration}
133
132
134
133
Each Worker can be configured by providing custom Worker options (`WorkerOptions`) at instantiation.
@@ -150,13 +149,18 @@ The `maxConcurrentWorkflowTaskExecutionSize` and `maxConcurrentActivityExecution
150
149
`maxConcurrentWorkflowTaskPollers` (JavaSDK: `workflowPollThreadCount`) and `maxConcurrentActivityTaskPollers` (JavaSDK: `activityPollThreadCount`) define the maximum count of pollers performing poll requests on Workflow and Activity Task Queues.
151
150
The Worker's requests deliver Tasks to the related executor slots.
152
151
152
+
Some SDKs (currently Python) have enabled experimental support for automated poller tuning.
153
+
This feature can be enabled by setting the `*_task_poller_behavior` options to `PollerBehaviorAutoscaling`.
154
+
Names may vary slightly depending on the SDK.
155
+
There are options within to configure minimum, maximum, and initial poller counts, but it is unlikely that you will need to adjust them.
156
+
153
157
### Cache options
154
158
155
159
A Workflow Cache is created and shared between all Workers on a single host.
156
160
It's designed to limit the resources used by the cache for each host/process.
157
161
These options are defined on `WorkerFactoryOptions` in JavaSDK and in `worker` package in GoSDK:
158
162
159
-
-`worker.setStickyWorkflowCacheSize` (JavaSDK: WorkerFactoryOptions#workflowCacheSize`) defines the maximum number of cached Workflows Executions.
163
+
-`worker.setStickyWorkflowCacheSize` (JavaSDK: `WorkerFactoryOptions#workflowCacheSize`) defines the maximum number of cached Workflows Executions.
160
164
Each cached Workflow contains at least one Workflow thread and its resources.
161
165
Resources include memory, etc.
162
166
-`maxWorkflowThreadCount` defines the maximum number of Workflow threads that may exist concurrently at any time.
@@ -265,9 +269,10 @@ If a just-started worker were to have no throttle, and there was a backlog of Ta
265
269
If each Task allocated 1GB of RAM, the Worker would likely run out of memory and crash.
266
270
The throttle enforces a wait before handing out new slots (after a minimum number of slots have been occupied) so you can measure newly consumed resources.
267
271
268
-
## Worker tuner examples {#examples}
272
+
## Performance tuning examples {#examples}
269
273
270
-
The following examples show how to create and provision composite Worker tuners.
274
+
The following examples show how to create and provision composite Worker tuners and set other
275
+
performance related options.
271
276
Each tuner provides slot suppliers for various Task types.
272
277
These examples focus on Activities and Local Activities, since Workflow Tasks normally do not need resource-based tuning.
273
278
@@ -386,13 +391,19 @@ const workerOptions = {
386
391
### Python SDK
387
392
388
393
```python
389
-
# Just resource based
394
+
# Just a resource based tuner, with poller autoscaling
Determine if your task processing rate is within an acceptable range for your needs using the per-Worker demand (how many Tasks each Worker has yet to process), the backlog consumption rate (`TasksDispatchRate`, the rate at which Workers are processing Tasks), and the dispatch latency (`ApproximateBacklogAge`, the time the oldest Task has been waiting to be assigned to a Worker).
598
615
599
616
- The backlog increase rate (`BacklogIncreaseRate`) shows the changing demand on your Workers over time.
600
617
As this rate increases, you may need to add more Workers until demand and capacity are balanced.
@@ -635,13 +652,14 @@ Increase the maximum number of working slots by adjusting `maxConcurrentWorkflow
635
652
1. The Worker hosts are underutilized (no bottlenecks on CPU, load average, etc.).
636
653
2. The `worker_task_slots_available` metric from the corresponding Worker type frequently shows a depleted number of available Worker slots.
637
654
655
+
Alternatively, consider using a resource-based slot supplier as described [here](#slot-suppliers).
656
+
638
657
### Poller count
639
658
640
-
:::note
641
-
Adjustmentstopollersarerarelyneededandrarelymakeadifference. PleaseconsiderthissteponlyafteradjustingWorkerslotsinthepreviousstep. Theonlyscenarioinwhichthepollers' adjustment makes sense is when there is a significant network latency between the Workers and Temporal Server.
642
-
:::
659
+
Sometimes, it can be appropriate to increase the number of task pollers.
660
+
This is usually more common in situations where your Workers have somewhat high latency when communicating with the server.
643
661
644
-
If:
662
+
You can use automated poller tuning, or consider adjustment if:
645
663
646
664
1. the `schedule_to_start` metric is abnormally long, and
647
665
2. the Worker hosts are underutilized (there are no bottlenecks on CPU, load average, etc), and
Copy file name to clipboardExpand all lines: docs/encyclopedia/workflow/workflow-execution/event.mdx
+8-3Lines changed: 8 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -65,12 +65,17 @@ An append-only log of [Events](#event) for your application.
65
65
- Event History is durably persisted by the Temporal service, enabling seamless recovery of your application state from crashes or failures.
66
66
- It also serves as an audit log for debugging.
67
67
68
-
**Event History limits**
68
+
### Event History limits{#event-history-limits}
69
69
70
70
The Temporal Service stores the complete Event History for the entire lifecycle of a Workflow Execution.
71
71
72
-
The Temporal Service logs a [warning after 10Ki (10,240) Events](/workflow-execution/limits) and periodically logs additional warnings as new Events are added.
73
-
If the Event History exceeds 50Ki (51,200) Events, the Workflow Execution is terminated.
72
+
The Temporal Service logs a [warning after 10,240 Events](/workflow-execution/limits) and periodically logs additional warnings as new Events are added.
73
+
74
+
The Workflow Execution is terminated when the Event History:
0 commit comments