Missing HeartbeatTimeout pitfall
Without a HeartbeatTimeout, Temporal cannot detect a stuck or crashed Worker until the StartToCloseTimeout expires. Always set HeartbeatTimeout shorter than StartToCloseTimeout.
activities
85 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
Activity Heartbeat pattern overview
The Activity Heartbeat pattern enables long-running Activities to report progress, handle cancellation gracefully, and resume from the last checkpoint after failures. Heartbeats inform Temporal that the Activity is still alive and allow storing progress details that survive Worker restarts.
Benefits of heartbeats over long timeouts
Without heartbeats, you must set very long Activity timeouts that delay failure detection, reprocess entire batches from the beginning on failures, accept no visibility into Activity progress, risk zombie Activities that appear alive but are stuck, and implement custom checkpointing and recovery logic.
How heartbeats enable resumption after failure
Activity heartbeats periodically report progress to the Temporal Service. The heartbeat details are persisted and available to retry attempts, enabling resumption from the last checkpoint. Heartbeat timeouts detect stuck Activities faster than execution timeouts.
Activity must distinguish permanent from transient failures
The Activity should throw a non-retryable ApplicationFailure for permanent input errors (such as an invalid account number) so the Workflow catches the ActivityError immediately and transitions to AWAITING_CORRECTION instead of exhausting all retry attempts first. Let all other exceptions propagate so the RetryPolicy handles transient failures.
TypeScript Activity non-retryable error for Resumable Activity
import { ApplicationFailure } from '@temporalio/activity'; import type { TransferInput } from './workflows'; export async function executeTransfer(transfer: TransferInput): Promise<string> { const accountExists = await accountService.exists(transfer.toAccount); if (!accountExists) { throw ApplicationFailure.nonRetryable( `Account ${transfer.toAccount} not found`, 'AccountNotFoundError', ); } return paymentService.transfer(transfer.fromAccount, transfer.toAccount, transfer.amount); }
Python Activity non-retryable error for Resumable Activity
from temporalio import activity from temporalio.exceptions import ApplicationError @activity.defn async def execute_transfer(transfer: TransferInput) -> str: if not await account_service.exists(transfer.to_account): raise ApplicationError( f"Account {transfer.to_account} not found", type="AccountNotFoundError", non_retryable=True, ) return await payment_service.transfer( transfer.from_account, transfer.to_account, transfer.amount )
Dynamic Activity method signature .NET
The Activity Definition for a Dynamic Activity must accept a single argument of type Temporalio.Converters.IRawValue[].
Dynamic Activity definition in .NET SDK
A Dynamic Activity in Temporal is an Activity that is invoked dynamically at runtime if no other Activity with the same name is registered. An Activity is made dynamic by setting Dynamic as true on the [Activity] attribute.
Dynamic Activity registration requirement
A Dynamic Activity must be registered with the Worker before it can be invoked. Only one Dynamic Activity can be present on a Worker.
Converting IRawValue in Dynamic Activity .NET
The PayloadConverter property on the ActivityExecutionContext is used to convert an IRawValue object to the desired type using extension methods in the Temporalio.Converters namespace.
Dynamic Activity .NET code example
public class MyActivities { [Activity(Dynamic = true)] public string DynamicActivity(IRawValue[] args) { var input = ActivityExecutionContext.Current.PayloadConverter.ToValue<MyActivityParams>(args.Single()); return $"{input.Greeting}, {input.Name}!"; } } This example shows how to define a dynamic activity that accepts variable arguments, converts them using the PayloadConverter, and returns a formatted string.
Identifying information for external activity completion
To complete an Activity asynchronously, the external system needs identifying information which can be either a Task Token or a combination of Namespace, Workflow Id, and Activity Id.
CompleteActivity function parameters in Go
The CompleteActivity function in the Temporal Client takes the following parameters: taskToken (the binary TaskToken field from ActivityInfo), result (the return value to record, must match the Activity function's declared return type), and err (the error code to return if the Activity terminates with an error). If err is not null, the result field value is ignored.
Create Temporal Client for asynchronous activity completion
Instantiate a Temporal service client using client.Dial(client.Options{}). The same client can be used to complete or fail any number of Activities. The client is a heavyweight object that should be created once per process.
Complete Activity asynchronously in Go example
activityInfo := activity.GetInfo(ctx) taskToken := activityInfo.TaskToken // Send the taskToken to the external service // In Activity function, return: return "", activity.ErrResultPending // In external system, complete the Activity: temporalClient, err := client.Dial(client.Options{}) temporalClient.CompleteActivity(context.Background(), taskToken, result, nil)
Fail Activity asynchronously in Go
To fail an Activity during asynchronous completion, call client.CompleteActivity(context.Background(), taskToken, nil, err) with a nil result and a non-nil error value.
Asynchronous Activity Completion overview
Asynchronous Activity Completion enables the Activity Function to return without the Activity Execution completing. The Activity provides identifying information to an external system, returns to indicate it is waiting for external completion, and the Temporal Client is used to heartbeat and complete the Activity externally.
Get Task Token in Go Activity
To retrieve the Task Token and other Activity information needed for asynchronous completion, use the activity.GetInfo(ctx) API from the go.temporal.io/sdk/activity package. The taskToken is accessed via activityInfo.TaskToken and must be sent to the external service that will complete the Activity.
Return activity.ErrResultPending to indicate asynchronous completion
An Activity Function that will complete asynchronously must return an error of type activity.ErrResultPending to indicate to the Temporal system that the Activity is waiting to be completed by an external system.
Dynamic Activity definition in Go SDK
A Dynamic Activity in Temporal is an Activity that is invoked dynamically at runtime if no other Activity with the same name is registered. The Activity Definition must accept a single argument of type converter.EncodedValues.
Only one Dynamic Activity per Worker
Only one Dynamic Activity can be present on a Worker.
Dynamic Activity registration is required
Dynamic Activity registration is required in the Go SDK when you need to handle Activities invoked dynamically at runtime with names that are not pre-registered. Without registration, dynamically named Activities cannot be invoked.
Go SDK Dynamic Activity example
func DynamicActivity(ctx context.Context, args converter.EncodedValues) (string, error) { var arg1, arg2 string err := args.Get(&arg1, &arg2) if err != nil { return "", fmt.Errorf("failed to decode arguments: %w", err) } info := activity.GetInfo(ctx) result := fmt.Sprintf("%s - %s - %s", info.WorkflowType.Name, arg1, arg2) return result, nil } This example shows how to define a Dynamic Activity that receives encoded values as arguments, decodes them, retrieves activity info, and returns a formatted result.
Register Dynamic Activity with worker.RegisterDynamicActivity()
An Activity can be registered as dynamic by using worker.RegisterDynamicActivity(). You must register the Activity with the Worker before it can be invoked.