Clarify Priority and Fairness dispatch order and add weight override CLI example#4625
Merged
Conversation
…CLI example - Spell out the strict tie-break order (priority -> fairness weight -> FIFO) so customers don't have to infer it from scattered sentences. - Add a "Choosing between Priority, Fairness, and both" subsection covering when each mode is the right tool. - Add a CLI example for setting per-key fairness weight overrides (temporal task-queue config set --fairness-key-weight key=weight), which was previously only mentioned as "the config API" with no example.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
thearcticwatch
approved these changes
May 27, 2026
|
|
||
| 1. **Priority tier (strict).** Tasks at a higher priority always dispatch before tasks at lower priorities, regardless of fairness keys or weights. | ||
| 2. **Fairness key within a tier (weighted).** Within a priority tier, each fairness key is a virtual queue. Keys are dispatched proportional to their weights - a key with weight 2.0 is dispatched twice as often as one with weight 1.0. | ||
| 3. **FIFO within a key.** Tasks that share a priority tier _and_ fairness key dispatch in the order they were enqueued. |
There was a problem hiding this comment.
We can mention here (or at least in the call) that this is strictly true per partition.
Contributor
Author
There was a problem hiding this comment.
added after rule 3: "These rules apply within a Task Queue partition. See Limitations of Fairness for how partitioning can affect ordering."
jsundai
reviewed
May 28, 2026
| Set overrides with `temporal task-queue config set`: | ||
|
|
||
| ``` | ||
| temporal task-queue config set \ |
Contributor
There was a problem hiding this comment.
One small thing! It looks like --namespace might be missing here after task-queue-type activity. I noticed the rate limits example just above includes it. But super easy fix 🙂
Contributor
Author
There was a problem hiding this comment.
added --namespace my-namespace \ to the weight-overrides snippet to match the rate-limits example above.
jsundai
approved these changes
May 28, 2026
Contributor
|
Once the edits are made, I'll give this a merge! |
- Add --namespace to weight overrides CLI example to match the rate limits example above. - Note that the three dispatch rules apply within a Task Queue partition, linking to the existing Limitations section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
chaptersix
added a commit
to temporalio/cli
that referenced
this pull request
May 29, 2026
…1056) The `temporal task-queue config set` help text referenced three flags that don't exist: - `--fairness-key-weight-set <key>=<weight>` - `--fairness-key-weight-unset <key>` - `--fairness-key-weight-unset-all` The real flags, defined a few lines below in the same YAML block, are: - `--fairness-key-weight <key>=<weight>` (with `<key>=default` to unset a single key) - `--fairness-key-weight-clear-all` This PR updates the example block and the unset instructions in `commands.yaml` to match, and regenerates `commands.gen.go`. Verified locally with `go run ./cmd/temporal task-queue config set --help`. This bug also surfaces in the auto-generated docs site at [docs/cli/task-queue.mdx](https://docs.temporal.io/cli/task-queue#set), which a customer hit in [this Slack thread](https://temporaltechnologies.slack.com/archives/C0748KDH2DD/p1779899719317389?thread_ts=1779898503.202859&cid=C0748KDH2DD). The docs PR over in `temporalio/documentation#4625` works around it by referencing the real flag names directly. Co-authored-by: Alex Stanfield <13949480+chaptersix@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three changes to docs/develop/task-queue-priority-fairness.mdx:
Dispatch order made explicit. Replaced the "Using Priority and Fairness together" section with "Choosing between Priority, Fairness, and both" - covers when each mode fits and spells out the three-rule dispatch order (priority tier, then fairness weight, then FIFO within a key).
Rate limits section tightened. Removed throat-clearing intro, restructured into bolded "Whole queue rate limits" and "Fairness key rate limits" labels, linked Worker Options to the worker-tuning-reference page.
Weight override CLI example added. The "Fairness weight overrides" section previously said overrides are set "through the config API" without showing how. Added a
temporal task-queue config set --fairness-key-weightexample.Motivated by this customer Slack thread asking five clarifying questions about this page.