For the complete documentation index, see /llms.txt. This page is also available as raw Markdown at /design-patterns/fairness.md. Append .md to any page URL to fetch its Markdown.

Fairness

View Markdown

TLDR

Assign a fairness key and weight to Workflows and Activities so each tenant or group receives a proportional share of Task dispatches on a shared Task Queue. Use this when a high-volume caller would otherwise starve other tenants.

Overview

The Fairness pattern distributes Task dispatches across tenants or user groups within a shared Task Queue. Each group has a fairness key and an optional weight. The Temporal matching service uses weighted fair dispatch to select the next Task within a priority level.

Fairness applies only to Task dispatch. It does not account for Task duration or resource use.

Problem

When multiple tenants share a Task Queue, a high-volume tenant can fill the backlog and dominate dispatch. Tasks from other tenants can wait behind that backlog, which makes their latency unpredictable under load.

Using one Task Queue per tenant avoids a shared backlog, but adds Task Queue, Worker, and routing configuration for every tenant.

Solution

Assign a fairness key to each tenant or group and, when needed, a fairness weight. Tasks with the same fairness key compete for dispatch as a group. A single Worker pool can serve all keys.

For example, assigning weights of 5.0, 3.0, and 2.0 causes approximately 50% of dispatched Tasks to come from premium, 30% from basic, and 20% from free when all three groups have backlogged Tasks. Within a fairness key, Tasks at the same priority are dispatched in first-in-first-out (FIFO) order.

The following describes each step in the diagram:

1. Workflows start with a fairness key that identifies their tenant or group.
2. Tasks with the same fairness key form a fairness group within the Task Queue.
3. When more than one group has backlogged Tasks, the matching service dispatches Tasks according to their weights.
4. A group can use all available dispatches when the other groups have no backlogged Tasks.

Implementation

Fairness must be enabled for the Namespace. Set fairness keys and weights on Workflows, Activities, or Child Workflows. Activities and Child Workflows inherit these values unless you override them.

See Task Queue Priority and Fairness for setup, SDK examples, inheritance, Task Queue configuration, and limitations.

When to use

Use this pattern when multiple tenants or workload groups share a Task Queue and need weighted dispatch under load. It works well when tenants are added often because fairness keys do not require separate Task Queues or Worker configuration.

Fairness does not provide exact dispatch ratios, concurrency limits, or compute isolation. Use Activity Task Queue rate limits for throughput caps. Use separate Task Queues with dedicated Worker pools and compute resources for hard isolation. Use Priority Task Queues to order urgent work ahead of less urgent work.

Benefits and trade-offs

Fairness is work-conserving. A group can use all available dispatches when no other group has a backlog. New groups can start using the same Task Queue without changes to the Worker deployment.

Fairness is best effort. Dispatch ratios can vary across Task Queue partitions, Worker Versioning, and short time windows. Tasks with different runtimes can consume different amounts of Worker capacity even when their dispatch shares match their weights.

Comparison with alternatives

Approach	Backlog dispatch	Worker capacity isolation	Tenant onboarding
Fairness on a shared Task Queue	Weighted across backlogged groups	None	Assign a fairness key
Task Queue per tenant with shared compute	Separate tenant backlogs	None	Add Task Queue and Worker configuration
Task Queue per tenant with dedicated compute	Separate tenant backlogs	Yes	Deploy and configure dedicated Workers
Shared Task Queue without Fairness	No tenant-aware ordering	None	No additional configuration

Best practices

• Use stable fairness keys. Use account identifiers or tenant slugs instead of display names.
• Use one weight for each key. Conflicting weights for the same key have unspecified behavior.
• Combine Priority and Fairness for mixed workloads. Use Priority for urgency classes and Fairness for tenants within each class.
• Measure results by tenant. Track submitted, started, and completed Tasks and latency in application telemetry.

Common pitfalls

• Expecting exact ratios. Weights control dispatch proportions over time when multiple groups have backlogged Tasks. Results vary across partitions and short time windows.
• Treating Fairness as Worker capacity control. Fairness does not account for running Tasks or their resource use. A group with longer Tasks can consume more Worker time than its dispatch share suggests.
• Using Fairness as a hard rate limiter. Fairness does not cap absolute throughput. Use whole-queue or per-fairness-key RPS limits on Activity Task Queues for dispatch-rate caps.
• Expecting every Task to pass through fair dispatch. A Task can dispatch immediately when it synchronously matches an idle poller. Eagerly dispatched Tasks bypass matching.

See Limitations of Fairness for partitioning, Worker Versioning, backlog migration, and Task Queue reload behavior.

Related

Patterns

• Priority Task Queues: Order Tasks by urgency within the same Task Queue using PriorityKey.
• Downstream Rate Limiting: Cap dispatch throughput to a downstream service with a Task Queue RPS setting.
• Worker-Specific Task Queues: Route Activities to a specific Worker host for resource or data affinity.