Server

May 31, 2024

v1.24.0

Deprecation Announcements

Standard Visibility

As planned, standard visibility is no longer supported in this version. Please, upgrade to advanced visibility as well as the config keys to setup visibility before upgrading to this version. Refer to [v1.20.0 release notes](https://github.com/temporalio/temporal/releases/tag/v1.20.0) for upgrade instructions, and also check the [v1.21.0 release notes](https://github.com/temporalio/temporal/releases/tag/v1.21.0) for config key changes.

Worker Versioning APIs [Experimental]

The following changes were made to Worker Versioning APIs:

  • Deprecated

    UpdateWorkerBuildIdCompatibility

    in favor of the new

    UpdateWorkerVersioningRules

    API.

  • Deprecated

    GetWorkerBuildIdCompatibility

    in favor of the new

    GetWorkerVersioningRules

    API.

  • Deprecated

    GetWorkerTaskReachability

    in favor of

    DescribeTaskQueue

    enhanced mode (

    api_mode=ENHANCED

    )

Together with the old APIs, the Version Set concept is also deprecated and replaced with “versioning rules” which are more powerful and flexible. More details can be found in “https://github.com/temporalio/api/blob/master/temporal/api/taskqueue/v1/message.proto#L153”

For using these experimental APIs you need to enable the following configs:

  • frontend.workerVersioningRuleAPIs

  • frontend.workerVersioningWorkflowAPIs

Release Highlights

Namespace Burst Ratio

Removing frontend.namespaceBurstand adding frontend.namespaceBurstRatioconfig. Similarly replacing frontend.namespaceBurst.visibilityand frontend.namespaceBurst.namespaceReplicationInducingAPIswith frontend.namespaceBurstRatio.visibilityand frontend.namespaceBurstRatio.namespaceReplicationInducingAPIs.

The old values are used to specify the burst rate as number of requests per second. New values will specify burst as a ratio of their respective RPS limit. This ratio will be applied to calculated RPS limit from global and per-instance rate limits.

Visibility: Parent workflow execution

We added two new system search attributes: RootWorkflowIdand RootRunId. If you have previously created custom search attributes with one of these names, attempts to set them will start to fail. We suggest updating your workflows to not set those search attributes, delete those search attributes and then upgrade Temporal to this version. Alternatively, you can also set the dynamic config system.supressErrorSetSystemSearchAttribute: true. When this dynamic config is set to true, your workflow will not fail when trying to set a value on a system search attribute, and it will ignore your input for those system search attributes.

OpenAPI HTTP API Documentation

OpenAPI v2 docs are served at /api/v1/swagger.jsonwhile v3 is at /api/v1/openapi.yamlwhen our HTTP API is enabled.

Shard Info Update Optimizations

Operators can now configure how often we update shard info (tracking how many tasks have been acked, etc). This improves recovery speed by persisting shard data more frequently.

This can be configured through the following dynamic config values:

  • history.shardUpdateMinTasksCompleted

    - the minimum number of tasks which must be completed (across all queues) before the shard info can be updated

  • history.shardUpdateMinInterval

    - the minimum amount of time between shard info updates

    unless

    shardUpdateMinTasksCompleted

    tasks have been acked

Note that once history.shardUpdateMinInterval amountof time has passed we'll update the shard info regardless of the number of tasks completed

Interpolate MySQL query parameters by default (#5428)

We now interpolate parameters into queries client-side for MySQL main databases but not visibility.

When interpolateParamsis false (the default) the driver will prepare parameterized statements before executing them, meaning we need two round-trips to the database for each query. By setting interpolateParamsto true the DB driver will handle interpolation and send the query just once to the database, halving the number of round trips necessary. This should improve the performance of all Temporal deploys using MySQL.

OpenTelemetry env variables

Support for enabling OpenTelemetry for tracing gRPC requests via environment variables. See develop/docs/tracing.mdfor details.

Matching task queue handover

Various improvements were made to task queue handover when adding/removing/restarting matching nodes. This should improve tail latency for task dispatch during those situations. To enable the improvements, operators should set the dynamic config matching.alignMembershipChangeto a value like 10safter fully deploying v1.24 to the entire cluster. This may become the default in future versions.

UTF-8 validation in protobuf messages

When we migrated Temporal from the deprecated gogoproto fork of Google’s protobuf library to the official version in v1.23, we disabled protobuf’s default utf-8 validation to ensure a smooth deployment, since gogoproto did not validate fields for utf-8, and turning on validation immediately would have broken applications that accidentally used invalid utf-8.

This was a temporary measure and we will eventually re-enable validation. As the first step, we’ve added tools to detect and warn about invalid utf-8 without breaking applications. There are two sets of dynamic config settings to use.

The samplesettings are set to a floating point value between 0.0 and 1.0 (default 0.0), and control what proportion of either RPC requests, responses, or data read from persistence, is validated for utf-8 in strings. If invalid utf-8 is found, warnings will be sent to logs, and the counter metric utf8_validation_errorswill be incremented.

The failsettings (boolean, default false) control whether a validation error will be turned into a RPC failure or data corruption error.

  • system.validateUTF8.sample.rpcRequest

  • system.validateUTF8.sample.rpcResponse

  • system.validateUTF8.sample.persistence

  • system.validateUTF8.fail.rpcRequest

  • system.validateUTF8.fail.rpcResponse

  • system.validateUTF8.fail.persistence

If you think your application may be using invalid utf-8, we suggesting turning on the sample settings without the fail settings and running for a while. In a future version, validation and errors will be turned on by default (effectively sample set to 1.0 and fail set to true).

Helpful links to get you started with Temporal

Temporal Docs Server Docker Compose Helm Chart

Docker images for this release (use the tag 1.24.0)

Server Server With Auto Setup (what is Auto-Setup?) Admin-Tools

Full Changelog: v1.23.1...v1.24.0

Documentation icon

Release notes