Temporal: When and how to use the local activity?

Question

The official temporal documentation talks about local activities. However it is still not very clear what are the advantages or limitations of the local activities and how to code them?

Answer 1

According to this post,

Here is a sequence of steps to execute a single activity workflow.

1. Workflow is started which adds a workflow task into a workflow task queue.
2. A workflow task is received by a workflow worker listening to the workflow task queue.
3. The workflow task is completed with ScheduleActivityTask command.
4. An activity task is added to an activity task queue.
5. The activity task is received by an activity worker.
6. The activity task is completed by the activity worker.
7. The workflow task is added to the workflow task queue.
8. The workflow task with the result of the activity is received by a workflow worker.
9. The workflow task is completed with CompleteWorkflowExecution command.

Here is a sequence of steps to execute a local activity.

1. Workflow is started which adds a workflow task into a workflow task queue.
2. A workflow task is received by a workflow worker listening to the workflow task queue.
3. A workflow schedules a local activity task into the in-process local activity task queue.
4. Local activity is executed by a local activity worker that listens to the in-process local activity task queue.
5. The local activity task is completed back to the workflow.
6. The workflow task is completed with RecordMarker and CompleteWorkflowExecution commands. The marker command contains the result of the local activity execution.

The limitations of local activities are:

1. It works only for short activities that do not exceed the workflow task timeout. It implies that heartbeating is not supported for local activities.
2. It is not efficient for long retries. Normal activities can be retried practically indefinitely.
3. Local activity has at least once semantic as a failure of a workflow task would lead to their re-execution.
4. Local activity extends workflow task execution. While the task is running it cannot react to signals. So it increases the latency for signal handling.

A caution from @maxim

We’ve seen multiple cases when use of local activities without understanding their limitations caused various production issues. So my advice is to stick to normal activities unless your use case requires very high throughput and large activity fan outs of very short activities.

Code example java-sdk:

  private final RetryOptions retryOptions = RetryOptions.newBuilder()
          .setInitialInterval(Duration.ofSeconds(1))
          .setMaximumInterval(Duration.ofSeconds(10))
          .setBackoffCoefficient(2.0)
          .setMaximumAttempts(3)
          .build();

  private final LocalActivityOptions laOptions =
          LocalActivityOptions.newBuilder()
                  .setRetryOptions(retryOptions)
                  .setStartToCloseTimeout(Duration.ofSeconds(10))
                  .build();

  private final Account acc = Workflow.newLocalActivityStub(Account.class, laOptions);