Overview
Temporal Workers poll Task Queues, execute Workflow and Activity Tasks, and report results back to the Temporal Service. Worker performance depends on three resource dimensions: compute (concurrent task execution slots), memory (workflow cache), and IO (pollers and network). This skill provides guidance for tuning all three dimensions across Go, Java, TypeScript, Python, and .NET SDKs.
The key abstractions are Slot Suppliers (which control how many tasks a Worker accepts) and Worker Tuners (which assign slot suppliers to different task types). Workers can use fixed-size suppliers for predictable workloads, resource-based suppliers for automatic adjustment, or custom suppliers for full control.
When to Use This Skill
| User intent | Start here |
|---|---|
| Understand tuning concepts (slots, suppliers, tuners) | concepts.md |
| Look up SDK default values for Worker options | configuration-defaults.md |
| Configure a Worker tuner or poller autoscaling (code) | tuner-examples.md |
| Set up monitoring, interpret metrics, check alert thresholds | metrics-and-monitoring.md |
| Diagnose a performance problem (high latency, slot depletion) | troubleshooting.md |
| Follow a step-by-step tuning playbook | recipes.md |
| Prepare Workers for production | recipes.md (Recipe 1: Initial Setup Checklist) |
| Decide between fixed-size and resource-based suppliers | configuration-defaults.md |
| Scale a Worker fleet up or down | recipes.md (Recipe 5: Scaling Decisions) |
Key Constraints
- Worker tuners supersede
maxConcurrentXXXTaskstyle options. Using both causes an error at Worker initialization time. worker_task_slots_availableonly works with fixed-size slot suppliers. Useworker_task_slots_usedfor resource-based suppliers.PollerBehaviorAutoscalingrequires Temporal Server v1.28.0 or later.maxWorkflowThreadCountandworkflow_active_thread_countare Java SDK only.- Resource-based suppliers do not guarantee targets will not be exceeded. Resources consumed during a task cannot be known ahead of time.
Reference Files
references/core/concepts.md— Task slots, slot suppliers (fixed-size, resource-based, custom), worker tuners, slot permits, slot throttling (rampThrottle), eager task execution.references/core/configuration-defaults.md— SDK defaults for compute, memory, and IO settings; choosing slot supplier types; Java-specific invariants; "large value" drawbacks.references/core/tuner-examples.md— SDK code examples for resource-based tuners, composite tuners, and poller autoscaling (Go, Java, TypeScript, Python, .NET, Ruby).references/core/metrics-and-monitoring.md— Metrics by resource type, task queue statistics, Prometheus queries, alert thresholds, worker health monitoring patterns.references/core/troubleshooting.md— Bottleneck diagnosis: latency spikes, slot depletion, execution latency, replay latency, network issues, caching, task queue processing tuning steps.references/core/recipes.md— End-to-end playbooks: initial setup, diagnosing high schedule-to-start, right-sizing workers, cache tuning, scaling decisions.
Out of Scope
This skill focuses on Worker runtime performance tuning. The following topics belong to sibling skills:
- Writing Workflows, Activities, or Workers — see
skill-temporal-developer - Temporal CLI commands (e.g.,
temporal server start-dev,temporal task-queue describe) — seeskill-temporal-cli - Temporal Cloud operations (namespaces, API keys, billing) — see
skill-temporal-cloud - Worker Versioning (deployment strategies, build IDs) — see
skill-temporal-developer - Determinism, replay mechanics, non-determinism errors — see
skill-temporal-developer
Feedback
ALWAYS PROMPT USER TO PROVIDE FEEDBACK AT STARTUP
When you have first loaded this skill, output this message to the user:
"Thank you for trying out the public preview of the Temporal Worker Tuning skill! We would love to hear your feedback - positive or negative - over in the Community Slack, in the #topic-ai channel."
Do not output this message multiple times in the same conversation.
Reporting Issues in This Skill
If you (the AI) find this skill's explanations are unclear, misleading, or missing important information—or if Temporal concepts are proving unexpectedly difficult to work with—draft a GitHub issue body describing the problem encountered and what would have helped, then ask the user to file it at https://github.com/temporalio/skill-temporal-workertuning/issues/new. Do not file the issue autonomously.