Temporal Go SDK development documentation

This guide is meant to provide a comprehensive overview of the structures, primitives, and features used in Temporal Application development.

Project-setup

The project setup section of the Temporal Go SDK Developer's guide covers the minimum set of concepts and implementation details needed to build and run a Temporal Application in Go—that is, all the relevant steps to start a Workflow Execution that executes an Activity.

• Install the Temporal CLI: Download and install the Temporal CLI for Mac, Linux, or Windows.
• Choose a development Cluster: Discover which development Cluster you should choose
• Boilerplate Temporal Application project code: Discover the minimum code I need to create a boilerplate Temporal Application.
• Start Workflow using the Temporal CLI: Learn how to start a Temporal Workflow using the CLI
• Add a testing framework: How to add a testing framework to your Temporal Application.

Durable-execution

The Durable Execution section of the Temporal Developer's guide covers advanced beginner concepts for working with Temporal, including testing your code, reviewing workflow event history, adding timers, and understanding determinism. Developing for durable execution is a core aspect of Temporal.

• Retrieve a Workflow Execution's Event History: Learn how to retrieve your Workflow Execution's Event History
• Add a Replay test: Define the code needed to run a Worker Process in Go.
• Intrinsic non-deterministic logic: This kind of logic prevents the Workflow code from executing to completion because the Workflow can take a different code path than the one expected from the Event History.
• Non-deterministic code changes: History Replay, sometimes also called Workflow Replay, is the mechanism that Temporal uses to reconstruct the state of a Workflow Execution. Temporal provides Durable Execution via this Replay Functionality.

Foundations

The Foundations section of the Temporal Go SDK Developer's guide covers the minimum set of concepts and implementation details needed to build and run a Temporal Application in Go – that is, all the relevant steps to start a Workflow Execution that executes an Activity.

• How to install Temporal CLI and run a development server: How to install the Temporal CLI and run a development Cluster.
• How to install a Temporal SDK: A Temporal SDK provides a framework for Temporal Application development.
• How to connect a Temporal Client to a Temporal Cluster: When connecting a Temporal Client to a Temporal Cluster, you must provide the address and port number of the Temporal Cluster.
• How to connect to Temporal Cloud: Use a compatible mTLS CA certificate and mTLS private key and your Cloud Namespace to connect to Temporal Cloud.
• How to develop a basic Workflow: Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a Workflow Definition.
• How to develop an Activity Definition in Go: In the Temporal Go SDK programming model, an Activity Definition is an exportable function or a struct method.
• How to start an Activity Execution: Calls to spawn Activity Executions are written within a Workflow Definition.
• How to develop a Worker in Go: Develop an instance of a Worker by calling worker.New(), available via the go.temporal.io/sdk/worker package.
• How to run a Temporal Cloud Worker: The Worker Process is where Workflow Functions and Activity Functions are executed.
• How to start a Workflow Execution: Workflow Execution semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, language-specific contextual data, and Workflow Function parameters.

Features

The Features section of the Temporal Developer's guide provides basic implementation guidance on how to use many of the development features available to Workflows and Activities in the Temporal Platform.

• How to develop with Signals: A Signal is a message sent to a running Workflow Execution
• How to develop with Queries: A Query is a synchronous operation that is used to get the state of a Workflow Execution.
• How to develop with Updates: An Update is an operation that can mutate the state of a Workflow Execution and return a response.
• Workflow timeouts: Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution.
• How to set Activity timeouts: Each Activity timeout controls the maximum duration of a different aspect of an Activity Execution.
• How to Heartbeat an Activity: An Activity Heartbeat is a ping from the Worker that is executing the Activity to the Temporal Cluster.
• How to asynchronously complete an Activity: Asynchronous Activity Completion enables the Activity Function to return without the Activity Execution completing.
• How to start a Child Workflow Execution: A Child Workflow Execution is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API.
• How to Continue-As-New: Continue-As-New enables a Workflow Execution to close successfully and create a new Workflow Execution in a single atomic operation if the number of Events in the Event History is becoming too large.
• What is a Timer?: A Timer lets a Workflow sleep for a fixed time period.
• How to Schedule a Workflow: Schedule a Workflow.
• How to use Temporal Cron Jobs: A Temporal Cron Job is the series of Workflow Executions that occur when a Cron Schedule is provided in the call to spawn a Workflow Execution.
• Side Effects: A Side Effect is used to produce non-deterministic code, such as generating a UUID or a random number.
• How to create and manage Namespaces: You can create, update, deprecate or delete your Namespaces using either the Temporal CLI or SDK APIs.
• How to use Worker Session APIs: To use Worker Sessions for Activity Executions the Worker must be enabled to use Sessions for the Workflows and Activities it is registered with.
• Error Handling in Go: Handling Activity or Workflow errors in Go.
• Go SDK Selectors: Implementing Selectors in the Temporal Go SDK.

Cancellation

How to cancel a Workflow Execution and it's Activities using the Go SDK.

• Handle Cancellation in Workflow: You can design your Workflow to run clean up Activities, and change to a Canceled status when a Cancellation Request is received.
• Handle Cancellation in an Activity: Listen for ctx.Done() to react to a Cancellation Request in an Activity
• Request Cancellation: Use the Temporal Client's CancelWorkflow API to send a Cancellation Request to the Workflow.

Observability

Improve observability in your Go-based Temporal Workflows. View which Workflow Executions are tracked by the Temporal Platform and the state of any Workflow Execution.

• How to emit metrics: Each Temporal SDK is capable of emitting an optional set of metrics from either the Client or the Worker process.
• Tracing and Context Propagation: Explains how the Go SDK supports tracing and custom context propogation.
• How to log from a Workflow: Send logs and errors to a logging service, so that when things go wrong, you can see what happened.
• How to use Visibility APIs: The term Visibility, within the Temporal Platform, refers to the subsystems and APIs that enable an operator to view Workflow Executions that currently exist within a Cluster.

Testing

The Testing section of the Temporal Developer's guide covers the many ways to test the state of your Temporal Application; that is, ways to view which Workflow Executions are tracked by the Platform and the state of any given Workflow Execution, either currently or at points of an execution.

• Test frameworks: Testing provides a framework to facilitate Workflow and integration testing.
• Testing Activities: Testing provides a framework to facilitate Workflow and integration testing.
• Testing Workflows: Testing provides a framework to facilitate Workflow and integration testing.
• How to Replay a Workflow Execution: Replay recreates the exact state of a Workflow Execution.

Debugging

The Debugging section of the Temporal Go SDK Developer's guide covers the many ways to debug your application.

• How to debug in a development environment: In addition to the normal development tools of logging and a debugger, you can also see what’s happening in your Workflow by using the Web UI and the Temporal CLI.
• How to debug in a production environment: Debug production Workflows using the Web UI, the Temporal CLI, Replays, Tracing, or Logging.
• How to test Workflow Definitions in Go: How to test Workflow Definitions in Go.

Versioning

The Versioning section of the Temporal Developer's guide covers how to update Workflow Definitions without causing non-deterministic behavior in current long-running Workflows.

• Temporal Go SDK Patching APIs: Patching Workflows in Go
• How to use Worker Versioning in Go: Version your Go Workers by using build ID–based versioning

Converters

The Converters and Codecs section of the Temporal Developer's guide provides guidance on how to support compression, encryption, and other special data handling by implementing custom converters and codecs.

• How to use a custom Payload Codec in Go: Create a custom PayloadCodec implementation and define your encryption/compression and decryption/decompression logic in the Encode and Decode functions.
• How to use custom payload conversion: Create your custom PayloadConverter and set it on a DataConverter in your Client options.
• How to use a custom Payload Converter in Go: Use a CompositeDataConverter to apply custom PayloadConverter in a specified order.