Temporal Activities with Go: a roadmap
Why this matters, in 30 seconds
Distributed code fails all the time: timeouts, crashed processes, flaky APIs, rate limits, jobs that die at 80%. Without Temporal you would build retries, backoff, progress tracking, liveness checks and job queues yourself, for every side effect.
An Activity is a plain Go function that performs one side effect (call an API, write to a DB, send an email, transcode a file). Temporal wraps every call in a durable Activity Execution that retries it, times it out, tracks its heartbeats and checkpoints, records its result, and lets operators pause, reset or cancel it. You write the business logic. Temporal provides the reliability.
The roadmap
Read in order. Each stage builds on the previous one.
Stage 1: Foundations (core concepts, must-know)
| # | Chapter | You'll be able to… |
|---|---|---|
| 01 | What is an Activity, and why does it exist? | Explain the problem Activities solve, Workflow vs Activity, the three ways to run one, and the vocabulary. Run a first end-to-end example. |
| 02 | Defining Activities in Go | Write function and struct Activities, choose parameters and results, register and name them, design for idempotency and the right granularity. |
Stage 2: Running Activities from Workflows (core concepts, daily use)
| # | Chapter | You'll be able to… |
|---|---|---|
| 03 | Calling Activities from a Workflow | Use workflow.ExecuteActivity, futures, parallel fan-out, Task Queue routing, Activity IDs, saga compensation. Understand what goes into the Event History. |
| 04 | Timeouts, Retry Policies & Heartbeats | Choose the 4 timeouts, tune or stop retries (NonRetryable, NextRetryDelay), heartbeat and resume from checkpoints. |
| 05 | Failures, Cancellation & Benign errors | Inspect ActivityError causes, mute expected errors, implement cooperative cancellation and cleanup. |
Stage 3: Other ways to run an Activity (execution modes)
| # | Chapter | You'll be able to… |
|---|---|---|
| 06 | Standalone Activities | Use Temporal as a durable job queue with client.ExecuteActivity: ID dedup policies, Start Delay, handles, list and count. |
| 07 | Local Activities | Decide when the latency optimization is worth the reduced durability, and implement it safely. |
Stage 4: Advanced patterns (sub-features)
| # | Chapter | You'll be able to… |
|---|---|---|
| 08 | Asynchronous Activity Completion | Let an external system or a human complete an Activity with Task Tokens or IDs, and choose between async completion and Signals. |
| 09 | Dynamic Activities | Handle Activity Types that aren't known at compile time (plugins, connectors). |
Stage 5: Operating Activities in production
| # | Chapter | You'll be able to… |
|---|---|---|
| 10 | Activity Operations | Pause, Unpause, Reset, Update Options, Request Cancel, Terminate and Delete Activities from the CLI. Know what each one really guarantees, and write Activities that cooperate with them. |
Core concepts vs. implementation details
| Core concepts: understand these first | Implementation details, options & sub-features: learn when needed |
|---|---|
| Activity Definition / Activity Type (02) | Custom Activity Type names, registration aliasing (02) |
| Activity Execution & its lifecycle (03) | IsReady, parallel futures, per-call options (03) |
| Worker + Task Queue (01, 03) | Task Queue routing to specialized Worker pools (03) |
| Idempotency (02) | Idempotency key = Run ID + Activity ID (02) |
| Timeouts & Retry Policy (04) | NonRetryableErrorTypes, NextRetryDelay, MaximumAttempts: 1 (04) |
| Heartbeats (04) | Checkpoint details, external heartbeats (04) |
| Failure model (05) | Benign errors, WaitForCancellation, disconnected cleanup contexts (05) |
| Three invocation modes: Workflow / Standalone / Local (01) | ID Conflict and Reuse policies, Start Delay, retention (06); Workflow Task heartbeating (07) |
| — | Async completion (08), Dynamic Activities (09), Activity Operations (10) |
Which way should I run this Activity?
text
Do several steps depend on each other (sequence, branching, compensation, waiting for Signals/Timers)?
├── Yes → Workflow Activity (workflow.ExecuteActivity) → chapter 03
│ └── Is this step tiny (< a few seconds), local, idempotent, and latency-critical
│ in a high-throughput Workflow?
│ ├── Yes → Local Activity (workflow.ExecuteLocalActivity) → chapter 07
│ └── No → stay with a regular Workflow Activity
└── No, it's one job → Standalone Activity (client.ExecuteActivity) → chapter 06
Does an external system or a human produce the final result?
├── It must heartbeat / receive cancellation, or may fail to call back → Async completion → chapter 08
└── It reliably calls back and the wait is long → short Activity + SignalGo API cheat sheet
| I want to… | Go API | Chapter |
|---|---|---|
| Define an Activity | func (a *X) DoThing(ctx context.Context, in Input) (Output, error) | 02 |
| Register it | w.RegisterActivity(&X{deps}), w.RegisterActivityWithOptions(fn, activity.RegisterOptions{Name: …}) | 02 |
| Log / inspect inside it | activity.GetLogger(ctx), activity.GetInfo(ctx) | 02 |
| Call it from a Workflow | workflow.ExecuteActivity(workflow.WithActivityOptions(ctx, ao), a.DoThing, in).Get(ctx, &out) | 03 |
| Set timeouts and retries | workflow.ActivityOptions{StartToCloseTimeout, ScheduleToCloseTimeout, HeartbeatTimeout, RetryPolicy: &temporal.RetryPolicy{…}} | 04 |
| Fail without retry | temporal.NewNonRetryableApplicationError(msg, "Type", cause, details...) | 04 |
| Choose the next backoff | temporal.NewApplicationErrorWithOptions(msg, "Type", temporal.ApplicationErrorOptions{NextRetryDelay: d}) | 04 |
| Heartbeat and checkpoint | activity.RecordHeartbeat(ctx, progress), activity.HasHeartbeatDetails, activity.GetHeartbeatDetails(ctx, &p) | 04 |
| Mark an error as expected | temporal.ApplicationErrorOptions{Category: temporal.ApplicationErrorCategoryBenign} | 05 |
| Inspect a failure | errors.As(err, &*temporal.ApplicationError / TimeoutError / CanceledError / ActivityError) | 05 |
| Cancel from a Workflow | ctx, cancel := workflow.WithCancel(ctx) + WaitForCancellation | 05 |
| Handle cancellation in the Activity | <-ctx.Done(), context.Cause(ctx) (activity.ErrActivityPaused, activity.ErrActivityReset) | 05, 10 |
| Start a job without a Workflow | c.ExecuteActivity(ctx, client.StartActivityOptions{ID, TaskQueue, …}, fn, args...) | 06 |
| Get back to a job | c.GetActivityHandle(client.GetActivityHandleOptions{ActivityID}) → Get, Describe, Cancel, Terminate | 06 |
| List / count jobs | c.ListActivities, c.CountActivities | 06 |
| Run it locally in the Workflow Worker | workflow.WithLocalActivityOptions + workflow.ExecuteLocalActivity | 07 |
| Complete it from elsewhere | return …, activity.ErrResultPending + c.CompleteActivity / CompleteActivityByID / CompleteActivityByActivityID | 08 |
| Catch unknown Activity Types | w.RegisterDynamicActivity(fn, activity.DynamicRegisterOptions{}) | 09 |
| Pause / reset / extend from ops | temporal activity pause / unpause / reset / update-options / cancel / terminate / delete | 10 |
About the code samples
- Each chapter is a self-contained module named
github.com/acme/shop. Every Go block starts with// file: <path>so you can paste it into that path. - All samples were compiled and
go vet-checked against Go SDK v1.50.0 (go.temporal.io/sdk) andgo.temporal.io/sdk/contrib/envconfigv1.0.2. Standalone Activities need SDK ≥ v1.49.0, CLI ≥ 1.9.1 and Server ≥ 1.32.0. - External systems (payment gateways, printers, marketplaces) are interfaces or fakes. Swap in your real clients.
- Run everything locally with
temporal server start-dev(UI at http://localhost:8233).
Notes from checking the docs against the SDK
- The Reset page shows Go detection as
activity.GetCancellationDetails(ctx).Cause(). That helper doesn't exist in SDK v1.50.0. The SDK documentscontext.Cause(ctx), which returnsactivity.ErrActivityPausedoractivity.ErrActivityReset. The chapters use that. - The Encyclopedia says Activity Operations are CLI, UI and gRPC only. SDK v1.50.0 also has experimental
Pause,Unpause,UpdateOptionsandRestoreOriginalOptionsmethods on a StandaloneActivityHandle(see chapter 10). CompleteActivityByIDis for Workflow Activities. Standalone Activities useCompleteActivityByActivityID(chapter 08).
Sources
Encyclopedia: Activities · Activity Definition · Activity Execution · Workflow Activity · Standalone Activity · Local Activity · Activity Operations (Pause, Unpause, Reset, Update Options, Request Cancel, Terminate, Delete)
Go SDK: Activities · Basics · Execution · Standalone quickstart · Standalone feature guide · Timeouts · Async completion · Dynamic Activity · Benign exceptions