Fairness
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. A useful mental model is one virtual queue per Fairness key, with weighted round-robin dispatch across the queues. Temporal approximates this model with stride scheduling and a count-min sketch for larger key sets. 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:
- Workflows start with a Fairness key that identifies their tenant or group.
- Tasks with the same Fairness key enter the same virtual queue.
- When multiple virtual queues have backlogged Tasks, the Matching Service uses weighted round robin to choose between them.
- One virtual queue can use all available dispatches when the others 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 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.
- Combine Priority and Fairness for mixed workloads. Use Priority for urgency classes and Fairness for tenants within each class.
Common pitfalls
- Expecting exact ratios. Weights shape dispatch proportions over time when multiple groups have backlogs. Results vary across partitions and short time windows.
- Expecting Fairness to reorder the backlog. Temporal records each Task's Fairness weight when the Task is scheduled. Enabling Fairness or changing weights affects only newly scheduled Tasks.
- Expecting Tasks without a Fairness key to bypass Fairness. These Tasks share an implicit empty-string key with a weight of 1.0.
- Expecting Fairness across Task Queue partitions. Each partition calculates Fairness independently. Imbalanced partitions can change overall dispatch proportions.
- Expecting Fairness across Worker Deployment Versions. Each version has a separate backlog. Fairness applies within each version's backlog.
- Expecting Fairness state to be fully restored after a server restart. By default, Temporal restores state for up to 100 Fairness keys. Other keys rebuild state as Tasks arrive.
- Treating Fairness as Worker capacity control. Fairness considers only dispatch. A group with longer-running Tasks can consume more Worker time than its dispatch share suggests.
- Using Fairness as a hard rate limiter. Fairness does not cap throughput. Use rate limits for dispatch caps.
- Expecting every Task to pass through fair dispatch. Synchronous matching can send a Task directly to an idle poller. Eager Task Execution bypasses matching.
Related
Patterns
- Priority: Order Task dispatches by urgency within the same Task Queue using a Priority key.
- 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.