Skip to content

Commit 93c8eeb

Browse files
jsundaigithub-actions[bot]brianmacdonald-temporal
authored
task queue naming best practices (#3543)
* first pg add * go and python * typescript and dotnet * removing old links * CI: Automatic .md and .mdx formatting * Update docs/encyclopedia/workers/task-queue-naming.mdx Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io> * Update task-queue-naming.mdx * CI: Automatic .md and .mdx formatting --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
1 parent 74e2d48 commit 93c8eeb

2 files changed

Lines changed: 335 additions & 0 deletions

File tree

‎docs/encyclopedia/workers/task-queue-naming.mdx‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
---
2+
id: task-queue-naming
3+
title: Task Queues and Naming Best Practices
4+
sidebar_label: Task Queue Naming
5+
description: A mismatch in Task Queue names creates separate queues, preventing the Worker from receiving tasks and stalling Workflow Execution.
6+
slug: /task-queue/naming
7+
toc_max_heading_level: 4
8+
keywords:
9+
- task queues
10+
- naming conventions
11+
12+
tags:
13+
- Workers
14+
- Task Queues
15+
---
16+
17+
# Task Queue Names
18+
19+
The Temporal Service maintains a set of Task Queues, which Workers poll to see
20+
what work needs to be done. Each Task Queue is identified by a name, which is
21+
provided to the Temporal Service when launching a Workflow Execution.
22+
23+
<Tabs groupId="start-workflow-configure-worker-by-sdk" queryString>
24+
25+
<TabItem value="python" label="Python">
26+
27+
**Excerpt of code used to start the Workflow in Python**
28+
29+
```python
30+
client = await Client.connect("localhost:7233", namespace="default")
31+
32+
# Execute a workflow
33+
result = await client.execute_workflow(
34+
GreetingWorkflow.run,
35+
name,
36+
id="my-workflow",
37+
task_queue="my-task-queue-name",
38+
)
39+
```
40+
41+
**Excerpt of code used to configure the Worker in Python**
42+
43+
```python
44+
worker = Worker(
45+
client,
46+
task_queue="my-task-queue-name",
47+
workflows=[GreetingWorkflow],
48+
activities=[activities.say_hello],
49+
)
50+
```
51+
52+
</TabItem>
53+
<TabItem value="go" label="Go">
54+
55+
**Excerpt of code used to start the Workflow in Go**
56+
57+
```go
58+
options := client.StartWorkflowOptions{
59+
ID: "my-workflow",
60+
TaskQueue: "my-task-queue-name",
61+
}
62+
63+
run, err := c.ExecuteWorkflow(ctx, options, ProcessOrderWorkflow, input)
64+
```
65+
66+
**Excerpt of code used to configure the Worker in Go**
67+
68+
```go
69+
w := worker.New(c, "my-task-queue-name", worker.Options{})
70+
```
71+
72+
</TabItem>
73+
<TabItem value="java" label="Java">
74+
75+
**Excerpt of code used to start the Workflow in Java**
76+
77+
```java
78+
WorkflowOptions options = WorkflowOptions.newBuilder()
79+
.setWorkflowId("my-workflow")
80+
.setTaskQueue("my-task-queue-name")
81+
.build();
82+
83+
MyWorkflow workflow = client.newWorkflowStub(MyWorkflow.class, options);
84+
```
85+
86+
**Excerpt of code used to configure the Worker in Java**
87+
88+
```java
89+
Worker worker = factory.newWorker("my-task-queue-name");
90+
```
91+
92+
</TabItem>
93+
<TabItem value="typescript" label="Typescript">
94+
95+
**Excerpt of code used to start the Workflow in TypeScript**
96+
97+
```typescript
98+
await client.workflow.start(OrderProcessingWorkflow, {
99+
args: [order],
100+
taskQueue: 'my-task-queue',
101+
workflowId: `workflow-order-${order.id},`,
102+
});
103+
```
104+
105+
**Excerpt of code used to configure the Worker in TypeScript**
106+
107+
```typescript
108+
const worker = await Worker.create({
109+
taskQueue: 'my-task-queue',
110+
connection,
111+
workflowsPath: require.resolve('./workflows'),
112+
activities,
113+
});
114+
```
115+
116+
</TabItem>
117+
<TabItem value="dotnet" label=".NET">
118+
119+
**Excerpt of code used to start the Workflow in C# and .NET**
120+
121+
```csharp
122+
var options = new WorkflowOptions(
123+
id: "translation-workflow",
124+
taskQueue: "my-task-queue");
125+
126+
// Run workflow
127+
var result = await client.ExecuteWorkflowAsync(
128+
(TranslationWorkflow wf) => wf.RunAsync(input),
129+
options);
130+
```
131+
132+
**Excerpt of code used to configure the Worker in C# and .NET**
133+
134+
```csharp
135+
using var worker = new TemporalWorker(
136+
client,
137+
new TemporalWorkerOptions("my-task-queue")
138+
.AddAllActivities(activities)
139+
.AddWorkflow<TestWorkflow>());
140+
```
141+
142+
</TabItem>
143+
144+
</Tabs>
145+
146+
Since Task Queues are created dynamically when they are first used, a mismatch
147+
between these two values does not result in an error. Instead, it will result
148+
in the creation of two different Task Queues. Consequently, the Worker will
149+
not receive any tasks from the Temporal Service and the Workflow Execution
150+
will not progress. Therefore, we recommend that you define the Task Queue name
151+
in a constant that is referenced by the Client and Worker if possible, as this
152+
will ensure that they always use the same value.
153+
154+
<Tabs groupId="start-workflow-configure-worker-by-sdk" queryString>
155+
156+
<TabItem value="python" label="Python">
157+
158+
**Excerpt of code used to define a constant with the Task Queue name in Python (in a shared.py file)**
159+
160+
```python
161+
TASK_QUEUE_NAME = "my-task-queue-name"
162+
```
163+
164+
**Excerpt of code used to start the Workflow, referencing the constant
165+
defined with the Task Queue name in Python**
166+
167+
```python
168+
from shared import TASK_QUEUE_NAME
169+
170+
...
171+
172+
client = await Client.connect("localhost:7233", namespace="default")
173+
174+
# Execute a workflow
175+
result = await client.execute_workflow(
176+
GreetingWorkflow.run,
177+
name,
178+
id="my-workflow",
179+
task_queue=TASK_QUEUE_NAME,
180+
)
181+
```
182+
183+
**Excerpt of code used to configure the Worker, referencing the constant
184+
defined with the Task Queue name in Python**
185+
186+
```python
187+
worker = Worker(
188+
client,
189+
task_queue=TASK_QUEUE_NAME,
190+
workflows=[GreetingWorkflow],
191+
activities=[activities.say_hello],
192+
)
193+
```
194+
195+
</TabItem>
196+
<TabItem value="go" label="Go">
197+
198+
**Excerpt of code used to define a constant with the Task Queue name in Go**
199+
200+
```go
201+
package app
202+
203+
const TaskQueueName = "my-taskqueue-name"
204+
```
205+
206+
**Excerpt of code used to start the Workflow, referencing the constant defined with the Task Queue name in Go**
207+
208+
```go
209+
options := client.StartWorkflowOptions{
210+
ID: "my-workflow",
211+
TaskQueue: app.TaskQueueName,
212+
}
213+
214+
run, err := c.ExecuteWorkflow(ctx, options, ProcessOrderWorkflow, input)
215+
```
216+
217+
**Excerpt of code used to configure the Worker, referencing the constant defined with the Task Queue name in Go**
218+
219+
```go
220+
w := worker.New(c, app.TaskQueueName, worker.Options{})
221+
```
222+
223+
</TabItem>
224+
<TabItem value="java" label="Java">
225+
226+
**Excerpt of code used to define a constant with the Task Queue name in Java**
227+
228+
```java
229+
package app;
230+
231+
public class Constants {
232+
233+
public static final String taskQueueName = "my-task-queue-name";
234+
235+
}
236+
```
237+
238+
**Excerpt of code used to start the Workflow, referencing the constant defined with the Task Queue name in Java**
239+
240+
```java
241+
WorkflowOptions options = WorkflowOptions.newBuilder()
242+
.setWorkflowId("my-workflow")
243+
.setTaskQueue(Constants.taskQueueName)
244+
.build();
245+
246+
MyWorkflow workflow = client.newWorkflowStub(MyWorkflow.class, options);
247+
```
248+
249+
**Excerpt of code used to configure the Worker, referencing the constant defined with the Task Queue name in Java**
250+
251+
```java
252+
Worker worker = factory.newWorker(Constants.taskQueueName);
253+
```
254+
255+
</TabItem>
256+
<TabItem value="typescript" label="Typescript">
257+
258+
**Excerpt of code used to define a constant with the Task Queue name in TypeScript**
259+
260+
```typescript
261+
const TASK_QUEUE_NAME = 'my-taskqueue-name';
262+
```
263+
264+
**Excerpt of code used to start the Workflow, referencing the constant defined with the Task Queue name in TypeScript**
265+
266+
```typescript
267+
import { TASK_QUEUE_NAME } from './shared';
268+
269+
// additional code would follow
270+
271+
await client.workflow.start(OrderProcessingWorkflow, {
272+
args: [order],
273+
taskQueue: TASK_QUEUE_NAME,
274+
workflowId: `workflow-order-${order.id},`,
275+
});
276+
```
277+
278+
**Excerpt of code used to configure the Worker, referencing the constant defined with the Task Queue name in TypeScript**
279+
280+
```typescript
281+
import { TASK_QUEUE_NAME } from './shared';
282+
283+
// additional code would follow
284+
285+
const worker = await Worker.create({
286+
taskQueue: TASK_QUEUE_NAME,
287+
connection,
288+
workflowsPath: require.resolve('./workflows'),
289+
activities,
290+
});
291+
```
292+
293+
</TabItem>
294+
<TabItem value="dotnet" label=".NET">
295+
296+
**Excerpt of code used to define a constant with the Task Queue name in C# and .NET**
297+
298+
```csharp
299+
public static class WorkflowConstants
300+
{
301+
public const string TaskQueueName = "translation-tasks";
302+
}
303+
```
304+
305+
**Excerpt of code used to start the Workflow, referencing the constant defined with the Task Queue name in C# and .NET**
306+
307+
```csharp
308+
var options = new WorkflowOptions(
309+
id: "translation-workflow",
310+
taskQueue: WorkflowConstants.TaskQueueName);
311+
312+
// Run workflow
313+
var result = await client.ExecuteWorkflowAsync(
314+
(TranslationWorkflow wf) => wf.RunAsync(input),
315+
options);
316+
```
317+
318+
**Excerpt of code used to configure the Worker, referencing the constant defined with the Task Queue name in C# and .NET**
319+
320+
```csharp
321+
using var worker = new TemporalWorker(
322+
client,
323+
new TemporalWorkerOptions(WorkflowConstants.TaskQueueName)
324+
.AddAllActivities(activities)
325+
.AddWorkflow<TranslationWorkflow>());
326+
```
327+
328+
</TabItem>
329+
330+
</Tabs>
331+
332+
However, it’s not always possible to do define the Task Queue name in a constant, such as when the Client used
333+
to start the Workflow is running on another system or is implemented in a
334+
different programming language.

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -620,6 +620,7 @@ module.exports = {
620620
items: [
621621
"encyclopedia/workers/tasks",
622622
"encyclopedia/workers/task-queues",
623+
"encyclopedia/workers/task-queue-naming",
623624
"encyclopedia/workers/task-routing-worker-sessions",
624625
"encyclopedia/workers/sticky-execution",
625626
"encyclopedia/workers/worker-deployments",

0 commit comments

Comments
 (0)