Events and Event History

This page discusses the following:

• Events
• Activity Events
• Event History
• Event Loop
• Time Constraints
• Reset
• Side Effect

The Temporal Service tracks the progress of each Workflow Execution by appending information about Events, such as when the Workflow Execution began or ended, to the Event History associated with that execution. This information not only enables developers to know what took place, but is also essential for providing Durable Execution, since it enables the Workflow Execution to recover from a crash and continue making progress. In order to maintain high performance, the Temporal Service places limits on both the number and size of items in the Event History for each Workflow Execution.

What is an Event?

Events are created by the Temporal Service in response to external occurrences and Commands generated by a Workflow Execution. Each Event corresponds to an enum that is defined in the Server API.

All Events are recorded in the Event History.

A list of all possible Events that could appear in a Workflow Execution Event History is provided in the Event reference.

Activity Events

Seven Activity-related Events are added to Event History at various points in an Activity Execution:

• After a Workflow 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 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 and ActivityTaskCompleted to Event History.
• If the Activity function throws a non-retryable Failure, the Temporal Service adds ActivityTaskStarted and ActivityTaskFailed to Event History.
• If the Activity function throws an error or retryable Failure, the Temporal Service schedules an Activity Task retry to be added to the Task Queue (unless you’ve reached the Maximum Attempts value of the Retry Policy, in which case the Temporal Service adds ActivityTaskStarted and ActivityTaskFailed to Event History).
• If the Activity’s Start-to-Close Timeout passes before the Activity function returns or throws, the Temporal Service schedules a retry.
• If the Activity’s Schedule-to-Close Timeout passes before Activity Execution is complete, or if Schedule-to-Start Timeout passes before a Worker gets the Activity Task, the Temporal Service writes ActivityTaskTimedOut to Event History.
• If the Activity is canceled, the Temporal Service writes ActivityTaskCancelRequested to Event History, and if the Activity accepts cancellation, the Temporal Service writes ActivityTaskCanceled.

note

While the Activity is running and retrying, ActivityTaskScheduled is the only Activity-related Event in History: ActivityTaskStarted is written along with a terminal Event like ActivityTaskCompleted or ActivityTaskFailed.

What is an Event History?

An append-only log of Events for your application.

• Event History is durably persisted by the Temporal service, enabling seamless recovery of your application state from crashes or failures.
• It also serves as an audit log for debugging.

Event History limits

The Temporal Service stores the complete Event History for the entire lifecycle of a Workflow Execution.

The Temporal Service logs a warning after 10Ki (10,240) Events and periodically logs additional warnings as new Events are added. If the Event History exceeds 50Ki (51,200) Events, the Workflow Execution is terminated.

Event loop

A Workflow Execution is made up of a sequence of Events called an Event History. Events are created by the Temporal Service in response to either Commands or actions requested by a Temporal Client (such as a request to spawn a Workflow Execution).

Workflow Execution

Time constraints

Is there a limit to how long Workflows can run?

No, there is no time constraint on how long a Workflow Execution can be Running.

However, Workflow Executions intended to run indefinitely should be written with some care. The Temporal Service stores the complete Event History for the entire lifecycle of a Workflow Execution. The Temporal Service logs a warning after 10Ki (10,240) Events and periodically logs additional warnings as new Events are added. If the Event History exceeds 50Ki (51,200) Events, the Workflow Execution is terminated.

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).

You can use the 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.

What is a Reset?

A Reset terminates a Workflow Execution and creates a new Workflow Execution with the same Workflow Type and Workflow ID. The Event History is copied from the original execution up to and including the reset point. The new execution continues from the reset point. Signals in the original history can be optionally copied to the new history, whether they appear after the reset point or not.

What is a Side Effect?

note

Side Effects are included in the Go, Java, and PHP SDKs. They are not included in other SDKs. Local Activities fit the same use case and are slightly less resource intensive.

A Side Effect is a way to execute a short, non-deterministic code snippet, such as generating a UUID, that executes the provided function once and records its result into the Workflow Execution Event History.

A Side Effect does not re-execute upon replay, but instead returns the recorded result.

Do not ever have a Side Effect that could fail, because failure could result in the Side Effect function executing more than once. If there is any chance that the code provided to the Side Effect could fail, use an Activity.