1# Tail Workers Configuration
2 
3## Setup Steps
4 
5### 1. Create Tail Worker
6 
7Create a Worker with a `tail()` handler:
8 
9```typescript
10export default {
11  async tail(events, env, ctx) {
12    // Process events from producer Worker
13    ctx.waitUntil(
14      fetch(env.LOG_ENDPOINT, {
15        method: "POST",
16        body: JSON.stringify(events),
17      })
18    );
19  }
20};
21```
22 
23### 2. Configure Producer Worker
24 
25In producer's `wrangler.jsonc`:
26 
27```jsonc
28{
29  "name": "my-producer-worker",
30  "tail_consumers": [
31    {
32      "service": "my-tail-worker"
33    }
34  ]
35}
36```
37 
38### 3. Deploy Both Workers
39 
40```bash
41# Deploy Tail Worker first
42cd tail-worker
43wrangler deploy
44 
45# Then deploy producer Worker
46cd ../producer-worker
47wrangler deploy
48```
49 
50## Wrangler Configuration
51 
52### Single Tail Consumer
53 
54```jsonc
55{
56  "name": "producer-worker",
57  "tail_consumers": [
58    {
59      "service": "logging-tail-worker"
60    }
61  ]
62}
63```
64 
65### Multiple Tail Consumers
66 
67```jsonc
68{
69  "name": "producer-worker",
70  "tail_consumers": [
71    {
72      "service": "logging-tail-worker"
73    },
74    {
75      "service": "metrics-tail-worker"
76    }
77  ]
78}
79```
80 
81**Note:** Each consumer receives ALL events independently.
82 
83### Remove Tail Consumer
84 
85```jsonc
86{
87  "tail_consumers": []
88}
89```
90 
91Then redeploy producer Worker.
92 
93## Environment Variables
94 
95Tail Workers use same binding syntax as regular Workers:
96 
97```jsonc
98{
99  "name": "my-tail-worker",
100  "vars": {
101    "LOG_ENDPOINT": "https://logs.example.com/ingest"
102  },
103  "kv_namespaces": [
104    {
105      "binding": "LOGS_KV",
106      "id": "abc123..."
107    }
108  ]
109}
110```
111 
112## Testing & Development
113 
114### Local Testing
115 
116**Tail Workers cannot be fully tested with `wrangler dev`.** Deploy to staging environment for testing.
117 
118### Testing Strategy
119 
1201. Deploy producer Worker to staging
1212. Deploy Tail Worker to staging
1223. Configure `tail_consumers` in producer
1234. Trigger producer Worker requests
1245. Verify Tail Worker receives events (check destination logs/storage)
125 
126### Wrangler Tail Command
127 
128```bash
129# Stream logs to terminal (NOT Tail Workers)
130wrangler tail my-producer-worker
131```
132 
133**This is different from Tail Workers:**
134- `wrangler tail` streams logs to your terminal
135- Tail Workers are Workers that process events programmatically
136 
137## Deployment Checklist
138 
139- [ ] Tail Worker has `tail()` handler
140- [ ] Tail Worker deployed before producer
141- [ ] Producer's `wrangler.jsonc` has correct `tail_consumers`
142- [ ] Environment variables configured
143- [ ] Tested with staging environment
144- [ ] Monitoring configured for Tail Worker itself
145 
146## Limits
147 
148| Limit | Value | Notes |
149|-------|-------|-------|
150| Max tail consumers per producer | 10 | Each receives all events independently |
151| Events batch size | Up to 100 events per invocation | Larger batches split across invocations |
152| Tail Worker CPU time | Same as regular Workers | 10ms (free), 30s default / 5min max (paid) |
153| Pricing tier | Workers Paid or Enterprise | Not available on free plan |
154| Request body size | 100 MB max | When sending to external endpoints |
155| Event retention | None | Events not retried if tail handler fails |
156 
157## Workers for Platforms
158 
159For dynamic dispatch Workers, both dispatch and user Worker events sent to tail consumer:
160 
161```jsonc
162{
163  "name": "dispatch-worker",
164  "tail_consumers": [
165    {
166      "service": "platform-tail-worker"
167    }
168  ]
169}
170```
171 
172Tail Worker receives TWO `TraceItem` elements per request:
1731. Dynamic dispatch Worker event
1742. User Worker event
175 
176See [patterns.md](patterns.md) for handling.
177