Priority key for workflow task queue ordering
The --priority-key flag sets priority key (1-5, lower numbers = higher priority). Tasks in a queue should be processed in close-to-priority-order. Default is 3 when not specified.
Temporal · Develop · all subjects
workers
109 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Fairness key and weight for proportional task dispatch
The --fairness-key flag (max 64 bytes) is used for proportional task dispatch where tasks with the same key share capacity based on their weight. The --fairness-weight flag specifies weight in the range [0.001-1000] with keys dispatched proportionally to their weights. Default priority-key is 3 when not specified (range 1-5, lower numbers = higher priority).
TOML profile configuration structure
Configuration profiles are defined in TOML using [profile.profile_name] sections. The 'default' profile is used unless another is specified via TEMPORAL_PROFILE environment variable or SDK load options. Required fields include: address (host:port), namespace. Optional fields include: api_key, tls configuration block, grpc_meta custom headers block.
TLS auto-enablement in TOML configuration
TLS is automatically enabled when a TLS config block is present or when an API key is specified in a profile. TLS settings can include: client_cert_path, client_key_path (for file-based mTLS), client_cert_data, client_key_data (for inline PEM/base64 format), server_name, ca_cert_path (for custom CA certificates).
Custom gRPC headers in TOML configuration
Custom gRPC metadata headers are defined in a TOML profile using the [profile.profile_name.grpc_meta] section. Headers are specified as key-value pairs, for example: my-custom-header = "value", trace-id = "trace-123".
Temporal Cloud profile address format
For Temporal Cloud profiles, the address field should use the format: your-namespace.account-id.tmprl.cloud:7233. The namespace field should include the account suffix when required by tooling: your-namespace.account-id.
Temporal Cloud login writes to TOML configuration
Running 'temporal cloud login --profile prod' automatically writes the OAuth token to the specified profile in the TOML configuration file. Subsequent commands using that profile read the token from the file to authenticate with Temporal Cloud.
CLI configuration commands
The Temporal CLI provides the following configuration commands: 'temporal config get <property>' (reads a value from current profile), 'temporal config set <property> <value>' (sets a property in current profile), 'temporal config delete <property>' (deletes a property from current profile), 'temporal config list' (lists all profiles). Use --profile flag to select a profile for CLI commands.
Environment variables always take precedence in SDKs
When using SDK environment configuration packages to load Temporal Client connection options, environment variables are always loaded and always take precedence over TOML file settings in the profiles, regardless of which profile is chosen.
Python SDK load default profile
In Python, use ClientConfigProfile.load() from temporalio.envconfig package to load the default profile and environment variables. Convert to client connect config using profile.to_client_connect_config() before passing to Client.connect().
Go SDK load default profile
In Go, use envconfig.MustLoadDefaultClientOptions() from go.temporal.io/sdk/contrib/envconfig package to load the default profile and environment variables. Pass the result directly to client.Dial().
Ruby SDK load default profile
In Ruby, use EnvConfig::ClientConfig.load_client_connect_options() from temporalio.env_config package to load the default profile and environment variables. By default loads the 'default' profile. Returns args and kwargs for unpacking into Client.connect().
.NET SDK load default profile
In .NET C#, use ClientEnvConfig.LoadClientConnectOptions() from Temporalio.Client.EnvConfig package to load the default profile and environment variables. By default loads the 'default' profile. Returns TemporalClientConnectOptions to pass to TemporalClient.ConnectAsync().
TypeScript SDK load default profile
In TypeScript, use loadClientConnectConfig helper from @temporalio/envconfig package to load the default profile and environment variables. Returns config object with connectionOptions (for Connection.connect) and namespace properties.
Java SDK load default profile
In Java, use ClientConfigProfile.load(LoadClientConfigProfileOptions.newBuilder().build()) from io.temporal.envconfig package to load the default profile. Use profile.toWorkflowServiceStubsOptions() and profile.toWorkflowClientOptions() to convert to appropriate options for WorkflowClient.newInstance().
Python SDK load custom profile from path
In Python, use ClientConfig.load_client_connect_config(profile='profile_name', config_file='/path/to/config.toml') to load a specific profile from a custom path. The result can be programmatically overridden before passing to Client.connect().
Go SDK load custom profile from path
In Go, use envconfig.LoadClientOptions(envconfig.LoadClientOptionsRequest{ConfigFileProfile: 'profile_name', ConfigFilePath: '/path/to/config.toml'}) to load a specific profile from a custom path. Result can be programmatically modified before passing to client.Dial().
Ruby SDK load custom profile from path
In Ruby, use EnvConfig::ClientConfig.load_client_connect_options(profile: 'profile_name', config_source: Pathname.new('/path/to/config.toml')) to load a specific profile from a custom path. Result can be programmatically modified before passing to Client.connect().
.NET SDK load custom profile from path
In .NET C#, use ClientEnvConfig.LoadClientConnectOptions(new ClientEnvConfig.ProfileLoadOptions{Profile='profile_name', ConfigSource=DataSource.FromPath('/path/to/config.toml')}) to load a specific profile from a custom path. Result can be programmatically modified before passing to TemporalClient.ConnectAsync().
TypeScript SDK load custom profile from path
In TypeScript, use loadClientConnectConfig({profile: 'profile_name', configSource: {path: '/path/to/config.toml'}}) to load a specific profile from a custom path. Returns config object that can be used with Connection.connect() and Client.
Java SDK load custom profile from path
In Java, use ClientConfigProfile.load(LoadClientConfigProfileOptions.newBuilder().setConfigFilePath('/path/to/config.toml').build()) to load a profile from a custom path. Environment variables take precedence over configuration file settings.
SDK environment configuration packages are read-only
SDKs only read from the TOML configuration file and environment at runtime to establish client connection. They do not write to the file. Only the Temporal CLI's 'temporal config' commands can directly manipulate the temporal.toml file.
Configuration precedence order
Configuration precedence is: (1) Command-line flags (CLI only), (2) Environment variables, (3) TOML configuration file. Environment variables always override TOML file settings when using SDK environment configuration packages.
CLI command-line flags override all configuration
For the Temporal CLI, command-line flags (such as --address, --namespace, --api-key) take precedence over both environment variables and TOML configuration file settings. For example, 'temporal workflow list --address localhost:7233' uses that address even if other configuration sources specify a different address.
TOML configuration file default locations
The TOML configuration file is located by checking sources in order: (1) Path specified by TEMPORAL_CONFIG_FILE environment variable, (2) Default OS paths: Linux ~/.config/temporalio/temporal.toml, macOS $HOME/Library/Application Support/temporalio/temporal.toml, Windows %AppData%\temporalio\temporal.toml.
Temporal Cloud connection requirements in Go SDK
To connect to Temporal Cloud, provide: credentials (API key or mTLS certificate and private key), Namespace and Account ID combination in format <namespace_id>.<account_id>, and the gRPC endpoint <namespace>.<account>.tmprl.cloud:7233.
Temporal Client in Go SDK - create with Dial()
Use the Dial() API from the go.temporal.io/sdk/client package to create a Client. The Dial() API expects connection options such as Temporal Server address, Namespace, and TLS configuration. These options can be specified in the function call, via environment variables, or a configuration file. A Temporal Client should be created once per process.
Go SDK default Temporal Service connection address
If HostPort is not provided when creating a Client, it defaults to 127.0.0.1:7233, which is the port of the development Temporal Service.
Go SDK environment variable and configuration file support
Environment variable and configuration file support were added in Go SDK v1.28.0.
TEMPORAL_CONFIG_FILE environment variable and default config location
Use TEMPORAL_CONFIG_FILE environment variable to specify the location of a TOML configuration file, or the SDK looks for it at the default path ~/.config/temporalio/temporal.toml.
Configuration file precedence over environment variables in Go SDK
Connection options set in configuration files have lower precedence than environment variables. If the same option is set in both the configuration file and as an environment variable, the environment variable value overrides the configuration file option.
Load Temporal Client options from config profile in Go SDK
Use envconfig.LoadClientOptions() with ConfigFileProfile parameter to load a specific profile from the TOML config file. Example: envconfig.LoadClientOptions(envconfig.LoadClientOptionsRequest{ConfigFileProfile: "prod"})
Load default Temporal Client options in Go SDK
Use client.Dial(envconfig.MustLoadDefaultClientOptions()) to load environment variables and the default profile from the configuration file. Any options set via environment variables will take precedence over configuration file options.
Required environment variables for Temporal Cloud in Go SDK
TEMPORAL_NAMESPACE: Namespace and Account ID in format <namespace_id>.<account_id>. TEMPORAL_ADDRESS: gRPC endpoint for Temporal Cloud Namespace. TEMPORAL_API_KEY: API key value for API key authentication. TEMPORAL_TLS_CLIENT_CERT_DATA or TEMPORAL_TLS_CLIENT_CERT_PATH: mTLS client certificate. TEMPORAL_TLS_CLIENT_KEY_DATA or TEMPORAL_TLS_CLIENT_KEY_PATH: mTLS client private key.
Create Temporal Cloud connection with API key in Go SDK
clientOptions := client.Options{ HostPort: <endpoint>, Namespace: <namespace_id>.<account_id>, ConnectionOptions: client.ConnectionOptions{TLS: &tls.Config{}}, Credentials: client.NewAPIKeyStaticCredentials(apiKey), } c, err := client.Dial(clientOptions)
Update API key dynamically in Go SDK
Use client.NewAPIKeyDynamicCredentials() with a function that returns the current API key. The function is called on each request, allowing updates without restarting: var myKey string creds := client.NewAPIKeyDynamicCredentials( func(context.Context) (string, error) { return myKey, nil }) myKey = myKeyUpdated
Rotate mTLS certificate without restarting Worker in Go SDK
Set GetClientCertificate on tls.Config instead of setting Certificates directly. Go's crypto/tls package calls this function on every new connection, always picking up the current certificate. This allows rotating certificates by overwriting files without restarting.
GetClientCertificate for mTLS rotation example in Go SDK
clientOptions := client.Options{ HostPort: <endpoint>, Namespace: <namespace_id>.<account_id>, ConnectionOptions: client.ConnectionOptions{ TLS: &tls.Config{ GetClientCertificate: func(*tls.CertificateRequestInfo) (*tls.Certificate, error) { cert, err := tls.LoadX509KeyPair(clientCertPath, clientKeyPath) if err != nil { return nil, err } return &cert, nil }, }, }, } c, err := client.Dial(clientOptions)
Override Temporal Client connection options programmatically in Go SDK
Load base configuration from environment variables or config file, then override specific options: opts := envconfig.MustLoadDefaultClientOptions(); opts.HostPort = "localhost:7233"; opts.Namespace = "test-namespace"; c, err := client.Dial(opts)
Create Temporal Client for local development
Use WorkflowServiceStubs.newLocalServiceStubs() to create a stub pointing to the local Temporal Service, then pass it to WorkflowClient.newInstance(serviceStub) to create the client. The client connects to the default local port 7233 and the default Namespace by default.
Set custom Namespace in Temporal Client
To connect to a custom Namespace, use WorkflowClientOptions.Builder.setNamespace(namespace) to set the Namespace, then pass the clientOptions to WorkflowClient.newInstance(serviceStub, clientOptions).
TOML configuration file format for Temporal Client
Configuration files use TOML format with profile sections like [profile.default] and [profile.prod]. Each profile can specify address, namespace, api_key, and tls configuration. The SDK looks for the configuration file at ~/.config/temporalio/temporal.toml by default, or at the path specified by the TEMPORAL_CONFIG_FILE environment variable.
Load configuration profile in Java
Use ClientConfigProfile.load(LoadClientConfigProfileOptions.newBuilder().setConfigFilePath(path).setConfigFileProfile(profileName).build()) to load a specific profile from a TOML configuration file. Then call profile.toWorkflowServiceStubsOptions() and profile.toWorkflowClientOptions() to convert the profile to the appropriate options, and pass them to WorkflowClient.newInstance().
Connect to Temporal Cloud with API key
To connect to Temporal Cloud using an API key, provide the API key with WorkflowServiceStubsOptions.newBuilder().addApiKey(() -> apiKeyValue).setTarget(endpoint).setEnableHttps(true).build(), then pass the options to WorkflowClient.newInstance(). The endpoint format is <namespace>.<account>.tmprl.cloud:7233. The Namespace format is <namespace_id>.<account_id>.
Connect to Temporal Cloud with mTLS
To connect to Temporal Cloud using mTLS, create an SSL context from the client certificate and private key using SimpleSslContextBuilder.forPKCS8(clientCertInputStream, clientKeyInputStream).build(), then set it in WorkflowServiceStubsOptions.newBuilder().setSslContext(sslContext).setTarget(endpoint).build(). Pass this to WorkflowClient.newInstance() with the Namespace set in WorkflowClientOptions.
Rotate mTLS certificate without restart
To rotate an mTLS client certificate without restarting the Worker, use AdvancedTlsX509KeyManager instead of SimpleSslContextBuilder. Call keyManager.updateIdentityCredentialsFromFile(File tlsKeyPath, File tlsCertPath, 5, TimeUnit.MINUTES, Executors.newSingleThreadScheduledExecutor()) to schedule periodic rereads of the certificate and key files. The same SslContext keeps serving fresh credentials for the life of the process.
PHP default Task Queue name
In the PHP SDK, the Task Queue name defaults to 'default'. This is different from most other SDKs which require an explicit Task Queue name. While setting a meaningful Task Queue name is recommended for better observability, Workflows can run without setting this option.
Set Workflow Task Queue in PHP client
Set the Workflow Task Queue using WorkflowOptions::withTaskQueue() when creating the Workflow stub: $stub = $workflowClient->newWorkflowStub(WorkflowClass::class, WorkflowOptions::new()->withTaskQueue('queue-name'));
Set Task Queue for Workflow Execution in Python
Specify the task_queue argument when executing a Workflow with either start_workflow() or execute_workflow() methods. The Task Queue is the only Workflow Option that must be set in most SDKs. For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name.
Ruby Activity default executor
By default, activities run in the thread pool executor (Temporalio::Worker::ActivityExecutor::ThreadPool). This default is shared across all workers and continually makes threads as needed when none are idle. If a thread sits idle long enough, it will be killed.
Ruby Activity max concurrent activities default
The maximum number of concurrent activities a worker will run at a time is configured via its tuner option. The default is Temporalio::Worker::Tuner.create_fixed which defaults to 100 activities at a time for that worker.
Ruby Activity fiber executor
In addition to the thread pool executor, there is a fiber executor in the default executor set. To use fibers, call the activity_executor :fiber class method at the top of the activity class (the default value is :default which is the thread pool executor). Activities can only choose the fiber executor if the worker has been created and run in a fiber, but the thread pool executor is always available. Due to an issue, workers can only run in a fiber on Ruby versions 3.3 and newer.
Resolve lazy loading errors by eagerly loading or explicit requires
To resolve lazy loading errors in Temporal Rails applications, either always eagerly load (for example, by setting `config.eager_load = true`) or explicitly require what is used by a workflow at the top of the file. This issue only affects non-production environments.
Lazy loading in Rails causes workflow IO errors with zeitwerk and bootsnap
By default, Rails eagerly loads all application code on startup in production, but lazily loads it in non-production environments. Temporal Workflows disallow IO during the Workflow run. With lazy loading enabled in dev/test environments, when an Activity class is referenced in a Workflow before being explicitly required, it can produce an error: 'Cannot access File path from inside a workflow.' This error originates from bootsnap via zeitwerk lazily loading a class/module at Workflow runtime.
Workflows and their referenced classes should be eagerly loaded
It is not good to lazily load code during a Workflow run because it can be side effecting. Workflows and the classes they reference should be eagerly loaded to prevent issues.
NativeConnection class for Worker connections
When connecting from a Worker, create a NativeConnection object instead of a Connection object. The NativeConnection class is imported from @temporalio/worker instead of @temporalio/client. After creating the NativeConnection object, pass it to Worker.create() when creating the Worker.
Connection vs Client distinction
A Connection object is a lower-level and expensive object that represents a direct connection to the Temporal Service. A Client object is a high-level, lightweight abstraction that internally manages a Connection object. Since Connection is expensive to create, create a single Connection object and reuse it across your application whenever possible. When instantiating a Connection, specify connection options except for the Namespace (endpoint, TLS settings, credentials). When instantiating a Client, provide the Connection object and the Namespace along with other client options.
TOML configuration file defaults
If a configuration file path is not provided, the SDK looks for it at ~/.config/temporalio/temporal.toml or the equivalent on your OS. Connection options set in configuration files have lower precedence than environment variables, so environment variable values override configuration file options.
Environment variable precedence over configuration files
Environment variables have higher precedence than configuration file settings. If the same option is set in both the configuration file and as an environment variable, the environment variable value overrides the option set in the configuration file.
Temporal Cloud connection requirements
Connection to Temporal Cloud requires: (1) credentials for authentication (API key or mTLS CA certificate and private key), (2) Namespace Id and Account Id combination in format <namespace_id>.<account_id>, and (3) the recommended gRPC Namespace endpoint format <namespace>.<account>.tmprl.cloud:7233 which automatically directs traffic to the active region for High Availability Namespaces.