Consolidate event history docs and modernize Continue as New encyclopedia #3573

drewhoskins-temporal · 2025-05-08T22:39:22Z

What does this PR do?

Removes duplicate explanations of event history limits.
Removes extraneous other documentation that is better addressed in other places.
Adds advice about versioning long-running workflows.
Modernizes continue-as-new overview to harmonize with the new per-SDK docs.
Tweaks python continue-as-new docs to give better advice.

Notes to reviewers

Test plan

yarn start
http://localhost:3000/workflow-execution/continue-as-new
Click on things
http://localhost:3000/workflow-execution/event#event-history-limits
Click on things

drewhoskins-temporal · 2025-05-08T22:40:25Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx

- [How to Continue-As-New using the Python SDK](/develop/python/continue-as-new)
- [How to Continue-As-New using the TypeScript SDK](/develop/typescript/continue-as-new)
- [How to Continue-As-New using the .NET SDK](/develop/dotnet/continue-as-new)
+- [Determine when to Continue-As-New using the Go SDK](/develop/go/continue-as-new#when)


Note: Other than python, these #when links don't exist yet, so they will link to the top of those pages until we finish those docs.

dandavison

Nice improvement. Made a few suggestions.

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx

dandavison · 2025-05-18T12:42:14Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx

+Pass your latest relevant state into Continue-As-New.
+This checkpoints it and passes it to a new Execution in the [Execution Chain](/workflow-execution#workflow-execution-chain).
+This state is passed in through your Workflow's parameters.
+The parameters are typically optional and left unset by the original caller of the Workflow.


I'd probably get rid of "This checkpoints it" because as a reader that would make me think that Temporal had a thing called "checkpointing" that I didn't know about.

I'm also tempted to add a sentence saying something like

The end result is that you've created a new workflow with a fresh history that picks up where your last one left off.

dandavison · 2025-05-18T12:43:58Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx

-All values passed to a Workflow Execution through parameters or returned through a result value are recorded into the Event History.
-The Temporal Service stores the full Event History of a Workflow Execution for the duration of a Namespace's retention period.
-A Workflow Execution that periodically executes many Activities has the potential of hitting the size limit.
+You can repeat Continue-As-New as often as needed, which means that your Workflow can run in perpetuity.


Channeling the docs team I wonder if "can run forever" will be more widely understood without losing much in accuracy.

dandavison · 2025-05-18T12:45:54Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx


-In the case of [Temporal Cron Jobs](/cron-job), Continue-As-New is actually used internally for the same effect.
+To help prevent versioning problems for long-running Workflows, you may also want to Continue-as-New after a certain amount of time has elapsed. This will make sure every Workflow began on a recent version of your source code.


Not a versioning expert but this sounds a bit vague to me. After how much time? How do I know that a versioning error won't occur if the CAN is not issued at a precise point w.r.t. workflow code deploys?

Heh, we're working on a better answer here--Trampolining. So yeah, we don't have a satisfying answer ATM. Some users have used signals.

This really is the most practical advice for now, since very few users have chosen to use signals. My goal in this doc is to limit it to a few versions rather than one version.

Wordsmithed.

dandavison · 2025-05-18T12:48:20Z

docs/encyclopedia/workflow/workflow-execution/event.mdx


-To prevent _runaway_ Workflow Executions, you can use the Workflow Execution Timeout, the Workflow Run Timeout, or both.
-A Workflow Execution Timeout can be used to limit the duration of Workflow Execution Chain, and a Workflow Run Timeout can be used to limit the duration an individual Workflow Execution (Run).
+However, Workflow Executions intended to run indefinitely should be written with some care as they can run into [Event History limits](#event-history-limits).


Could make this a bit more concrete:

Suggested change

However, Workflow Executions intended to run indefinitely should be written with some care as they can run into [Event History limits](#event-history-limits).

However, if your Workflow will perform many actions, or will receive many messages, then you should use Continue-As-New to avoid hitting [Event History limits](#event-history-limits) and performance degradation.

brianmacdonald-temporal

Looking good! I did some wordsmithing, but no major surgery.

docs/develop/python/continue-as-new.mdx

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx

brianmacdonald-temporal · 2025-05-21T00:42:58Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx


-The Continue-As-New feature enables developers to complete the current Workflow Execution and start a new one atomically.
+## When is it right to Continue-As-New? {#when}


How about "When should you use Continue-As-New?" Seems more to-the-point, but I could be missing something.

I wanted it to be clear that the question was at what point in the execution to continue as new rather than whether to use it. And "when should you" is fairly ambiguous.

brianmacdonald-temporal · 2025-05-21T00:45:06Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx


-The new Workflow Execution has the same Workflow Id, but a different Run Id, and has its own Event History.
+To prevent scalability problems, periodically check Continue As New Suggested in your Workflow.\


Suggested change

To prevent scalability problems, periodically check Continue As New Suggested in your Workflow.\

To prevent scalability problems, periodically check Continue As New Suggested in your Workflow.

Where would the user see the "Continue As New Suggested" message? I'm trying to describe this something like "periodically check for the Continue As New Suggested message in the CLI" or however it works.

brianmacdonald-temporal · 2025-05-21T00:46:04Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx


-The new Workflow Execution has the same Workflow Id, but a different Run Id, and has its own Event History.
+To prevent scalability problems, periodically check Continue As New Suggested in your Workflow.\
+Temporal will tell your Workflow when it's approaching performance or scalability problems.


I suggest swapping lines 48 and 49. Tell the reader about this cool thing Temporal does, then tell them what to look for specifically.

brianmacdonald-temporal · 2025-05-21T00:47:15Z

docs/encyclopedia/workflow/workflow-execution/continue-as-new.mdx


-In the case of [Temporal Cron Jobs](/cron-job), Continue-As-New is actually used internally for the same effect.
+To prevent long-running Workflows from running on stale versions of code, you may also want to Continue-as-New periodically. This makes sure you're running only a couple of versions, which avoids some backwards compatibility problems.


Can we define "periodically," or at least give some kind of guidelines? Weekly, monthly, every X number of executions?

There's no concrete time frame because it depends on how frequently they deploy, which varies widely. Clarified.

brianmacdonald-temporal · 2025-05-21T00:48:31Z

docs/encyclopedia/workflow/workflow-execution/event.mdx

-You can use the [Continue-As-New](/workflow-execution/continue-as-new) feature to close the current Workflow Execution and create a new Workflow Execution in a single atomic operation.
-The Workflow Execution spawned from Continue-As-New has the same Workflow Id, a new Run Id, and a fresh Event History and is passed all the appropriate parameters.
-For example, it may be reasonable to use Continue-As-New once per day for a long-running Workflow Execution that is generating a large Event History.
+For these reasons, it can be a good idea to [Continue-As-New](/workflow-execution/continue-as-new) periodically.


Same comment as above; if we could elaborate on "periodically," that might help user confidence.

Co-authored-by: Brian MacDonald <[email protected]>

drewhoskins-temporal requested a review from a team as a code owner May 8, 2025 22:39

vercel bot had a problem deploying to Preview May 8, 2025 22:39 Failure

drewhoskins-temporal commented May 8, 2025

View reviewed changes

drewhoskins-temporal assigned dandavison May 8, 2025

dandavison approved these changes May 18, 2025

View reviewed changes

drewhoskins-temporal added 4 commits May 20, 2025 16:51

Consolidate event history docs

ee2e43e

Modernize Continue-As-New encyclopedia entry

c606fbd

Fix links, tweaks

b32c207

Dan feedback

f905c45

drewhoskins-temporal force-pushed the drewhoskins_CaN_2 branch from 052f1df to f905c45 Compare May 20, 2025 23:52

vercel bot had a problem deploying to Preview May 20, 2025 23:52 Failure

brianmacdonald-temporal reviewed May 21, 2025

View reviewed changes

Brian feedback

d376c9f

vercel bot had a problem deploying to Preview May 21, 2025 01:15 Failure

Apply suggestions from code review

65b726a

Co-authored-by: Brian MacDonald <[email protected]>

vercel bot had a problem deploying to Preview May 21, 2025 01:16 Failure

drewhoskins-temporal requested a review from brianmacdonald-temporal May 21, 2025 01:16

Merge branch 'main' into drewhoskins_CaN_2

e30938c

vercel bot had a problem deploying to Preview May 29, 2025 19:53 Failure

fixing broken anchors for a successful build

0a24775

vercel bot deployed to Preview May 30, 2025 13:41 View deployment

jsundai self-requested a review May 30, 2025 13:58

capitalization

a85c145

jsundai approved these changes May 30, 2025

View reviewed changes

vercel bot deployed to Preview May 30, 2025 14:08 View deployment

Merge branch 'main' into drewhoskins_CaN_2

86f9fde

brianmacdonald-temporal approved these changes Jun 12, 2025

View reviewed changes

vercel bot deployed to Preview June 12, 2025 22:51 View deployment

brianmacdonald-temporal merged commit 74e6612 into main Jun 12, 2025
6 checks passed

brianmacdonald-temporal deleted the drewhoskins_CaN_2 branch June 12, 2025 22:52


		In the case of [Temporal Cron Jobs](/cron-job), Continue-As-New is actually used internally for the same effect.
		To help prevent versioning problems for long-running Workflows, you may also want to Continue-as-New after a certain amount of time has elapsed. This will make sure every Workflow began on a recent version of your source code.

	However, Workflow Executions intended to run indefinitely should be written with some care as they can run into [Event History limits](#event-history-limits).
	However, if your Workflow will perform many actions, or will receive many messages, then you should use Continue-As-New to avoid hitting [Event History limits](#event-history-limits) and performance degradation.


		The Continue-As-New feature enables developers to complete the current Workflow Execution and start a new one atomically.
		## When is it right to Continue-As-New? {#when}


		The new Workflow Execution has the same Workflow Id, but a different Run Id, and has its own Event History.
		To prevent scalability problems, periodically check Continue As New Suggested in your Workflow.\


		In the case of [Temporal Cron Jobs](/cron-job), Continue-As-New is actually used internally for the same effect.
		To prevent long-running Workflows from running on stale versions of code, you may also want to Continue-as-New periodically. This makes sure you're running only a couple of versions, which avoids some backwards compatibility problems.

Consolidate event history docs and modernize Continue as New encyclopedia #3573

Consolidate event history docs and modernize Continue as New encyclopedia #3573

Uh oh!

Conversation

drewhoskins-temporal commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Notes to reviewers

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dandavison left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dandavison May 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dandavison May 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brianmacdonald-temporal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

drewhoskins-temporal May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

drewhoskins-temporal commented May 8, 2025 •

edited

Loading

dandavison May 18, 2025 •

edited

Loading

dandavison May 18, 2025 •

edited

Loading

drewhoskins-temporal May 21, 2025 •

edited

Loading