1# Tail Workers Common Patterns
2 
3## Community Libraries
4 
5While most tail Worker implementations are custom, these libraries may help:
6 
7**Logging/Observability:**
8- **Axiom** - `axiom-cloudflare-workers` (npm) - Direct Axiom integration
9- **Baselime** - SDK for Baselime observability platform
10- **LogFlare** - Structured log aggregation
11 
12**Type Definitions:**
13- **@cloudflare/workers-types** - Official TypeScript types (use `TraceItem`)
14 
15**Note:** Most integrations require custom tail handler implementation. See integration examples below.
16 
17## Basic Patterns
18 
19### HTTP Endpoint Logging
20 
21```typescript
22export default {
23  async tail(events, env, ctx) {
24    const payload = events.map(event => ({
25      script: event.scriptName,
26      timestamp: event.eventTimestamp,
27      outcome: event.outcome,
28      url: event.event?.request?.url,
29      status: event.event?.response?.status,
30      logs: event.logs,
31      exceptions: event.exceptions,
32    }));
33    
34    ctx.waitUntil(
35      fetch(env.LOG_ENDPOINT, {
36        method: "POST",
37        body: JSON.stringify(payload),
38      })
39    );
40  }
41};
42```
43 
44### Error Tracking Only
45 
46```typescript
47export default {
48  async tail(events, env, ctx) {
49    const errors = events.filter(e => 
50      e.outcome === 'exception' || e.exceptions.length > 0
51    );
52    
53    if (errors.length === 0) return;
54    
55    ctx.waitUntil(
56      fetch(env.ERROR_ENDPOINT, {
57        method: "POST",
58        body: JSON.stringify(errors),
59      })
60    );
61  }
62};
63```
64 
65## Storage Integration
66 
67### KV Storage with TTL
68 
69```typescript
70export default {
71  async tail(events, env, ctx) {
72    ctx.waitUntil(
73      Promise.all(events.map(event =>
74        env.LOGS_KV.put(
75          `log:${event.scriptName}:${event.eventTimestamp}`,
76          JSON.stringify(event),
77          { expirationTtl: 86400 }  // 24 hours
78        )
79      ))
80    );
81  }
82};
83```
84 
85### Analytics Engine Metrics
86 
87```typescript
88export default {
89  async tail(events, env, ctx) {
90    ctx.waitUntil(
91      Promise.all(events.map(event =>
92        env.ANALYTICS.writeDataPoint({
93          blobs: [event.scriptName, event.outcome],
94          doubles: [1, event.event?.response?.status ?? 0],
95          indexes: [event.event?.request?.cf?.colo ?? 'unknown'],
96        })
97      ))
98    );
99  }
100};
101```
102 
103## Filtering & Routing
104 
105Filter by route, outcome, or other criteria:
106 
107```typescript
108export default {
109  async tail(events, env, ctx) {
110    // Route filtering
111    const apiEvents = events.filter(e => 
112      e.event?.request?.url?.includes('/api/')
113    );
114    
115    // Multi-destination routing
116    const errors = events.filter(e => e.outcome === 'exception');
117    const success = events.filter(e => e.outcome === 'ok');
118    
119    const tasks = [];
120    if (errors.length > 0) {
121      tasks.push(fetch(env.ERROR_ENDPOINT, {
122        method: "POST",
123        body: JSON.stringify(errors),
124      }));
125    }
126    if (success.length > 0) {
127      tasks.push(fetch(env.SUCCESS_ENDPOINT, {
128        method: "POST",
129        body: JSON.stringify(success),
130      }));
131    }
132    
133    ctx.waitUntil(Promise.all(tasks));
134  }
135};
136```
137 
138## Sampling
139 
140Reduce costs by processing only a percentage of events:
141 
142```typescript
143export default {
144  async tail(events, env, ctx) {
145    if (Math.random() > 0.1) return;  // 10% sample rate
146    ctx.waitUntil(fetch(env.LOG_ENDPOINT, {
147      method: "POST",
148      body: JSON.stringify(events),
149    }));
150  }
151};
152```
153 
154## Advanced Patterns
155 
156### Batching with Durable Objects
157 
158Accumulate events before sending:
159 
160```typescript
161export default {
162  async tail(events, env, ctx) {
163    const batch = env.BATCH_DO.get(env.BATCH_DO.idFromName("batch"));
164    ctx.waitUntil(batch.fetch("https://batch/add", {
165      method: "POST",
166      body: JSON.stringify(events),
167    }));
168  }
169};
170```
171 
172See durable-objects skill for full implementation.
173 
174### Workers for Platforms
175 
176Dynamic dispatch sends TWO events per request. Filter by `scriptName` to distinguish dispatch vs user Worker events.
177 
178### Error Handling
179 
180Always wrap external calls. See gotchas.md for fallback storage pattern.
181