1# Cloudflare Tail Workers
2 
3Specialized Workers that consume execution events from producer Workers for logging, debugging, analytics, and observability.
4 
5## When to Use This Reference
6 
7- Implementing observability/logging for Cloudflare Workers
8- Processing Worker execution events, logs, exceptions
9- Building custom analytics or error tracking
10- Configuring real-time event streaming
11- Working with tail handlers or tail consumers
12 
13## Core Concepts
14 
15### What Are Tail Workers?
16 
17Tail Workers automatically process events from producer Workers (the Workers being monitored). They receive:
18- HTTP request/response info
19- Console logs (`console.log/error/warn/debug`)
20- Uncaught exceptions
21- Execution outcomes (`ok`, `exception`, `exceededCpu`, etc.)
22- Diagnostic channel events
23 
24**Key characteristics:**
25- Invoked AFTER producer finishes executing
26- Capture entire request lifecycle including Service Bindings and Dynamic Dispatch sub-requests
27- Billed by CPU time, not request count
28- Available on Workers Paid and Enterprise tiers
29 
30### Alternative: OpenTelemetry Export
31 
32**Before using Tail Workers, consider OpenTelemetry:**
33 
34For batch exports to observability tools (Sentry, Grafana, Honeycomb):
35- OTEL export sends logs/traces in batches (more efficient)
36- Built-in integrations with popular platforms
37- Lower overhead than Tail Workers
38- **Use Tail Workers only for custom real-time processing**
39 
40## Decision Tree
41 
42```
43Need observability for Workers?
44├─ Batch export to known tools (Sentry/Grafana/Honeycomb)?
45│  └─ Use OpenTelemetry export (not Tail Workers)
46├─ Custom real-time processing needed?
47│  ├─ Aggregated metrics?
48│  │  └─ Use Tail Worker + Analytics Engine
49│  ├─ Error tracking?
50│  │  └─ Use Tail Worker + external service
51│  ├─ Custom logging/debugging?
52│  │  └─ Use Tail Worker + KV/HTTP endpoint
53│  └─ Complex event processing?
54│     └─ Use Tail Worker + Durable Objects
55└─ Quick debugging?
56   └─ Use `wrangler tail` (different from Tail Workers)
57```
58 
59## Reading Order
60 
611. **[configuration.md](configuration.md)** - Set up Tail Workers
622. **[api.md](api.md)** - Handler signature, types, redaction
633. **[patterns.md](patterns.md)** - Common use cases and integrations
644. **[gotchas.md](gotchas.md)** - Pitfalls and debugging tips
65 
66## Quick Example
67 
68```typescript
69export default {
70  async tail(events, env, ctx) {
71    // Process events from producer Worker
72    ctx.waitUntil(
73      fetch(env.LOG_ENDPOINT, {
74        method: "POST",
75        headers: { "Content-Type": "application/json" },
76        body: JSON.stringify(events),
77      })
78    );
79  }
80};
81```
82 
83## Related Skills
84 
85- **observability** - General Workers observability patterns, OTEL export
86- **analytics-engine** - Aggregated metrics storage for tail event data
87- **durable-objects** - Stateful event processing, batching tail events
88- **logpush** - Alternative for batch log export (non-real-time)
89- **workers-for-platforms** - Dynamic dispatch with tail consumers
90