Cloudflare Tail Workers

Specialized Workers that consume execution events from producer Workers for logging, debugging, analytics, and observability.

When to Use This Reference

Implementing observability/logging for Cloudflare Workers
Processing Worker execution events, logs, exceptions
Building custom analytics or error tracking
Configuring real-time event streaming
Working with tail handlers or tail consumers

Core Concepts

What Are Tail Workers?

Tail Workers automatically process events from producer Workers (the Workers being monitored). They receive:

HTTP request/response info
Console logs (console.log/error/warn/debug)
Uncaught exceptions
Execution outcomes (ok, exception, exceededCpu, etc.)
Diagnostic channel events

Key characteristics:

Invoked AFTER producer finishes executing
Capture entire request lifecycle including Service Bindings and Dynamic Dispatch sub-requests
Billed by CPU time, not request count
Available on Workers Paid and Enterprise tiers

Alternative: OpenTelemetry Export

Before using Tail Workers, consider OpenTelemetry:

For batch exports to observability tools (Sentry, Grafana, Honeycomb):

OTEL export sends logs/traces in batches (more efficient)
Built-in integrations with popular platforms
Lower overhead than Tail Workers
Use Tail Workers only for custom real-time processing

Decision Tree

Need observability for Workers?
├─ Batch export to known tools (Sentry/Grafana/Honeycomb)?
│  └─ Use OpenTelemetry export (not Tail Workers)
├─ Custom real-time processing needed?
│  ├─ Aggregated metrics?
│  │  └─ Use Tail Worker + Analytics Engine
│  ├─ Error tracking?
│  │  └─ Use Tail Worker + external service
│  ├─ Custom logging/debugging?
│  │  └─ Use Tail Worker + KV/HTTP endpoint
│  └─ Complex event processing?
│     └─ Use Tail Worker + Durable Objects
└─ Quick debugging?
   └─ Use `wrangler tail` (different from Tail Workers)

Reading Order

configuration.md - Set up Tail Workers
api.md - Handler signature, types, redaction
patterns.md - Common use cases and integrations
gotchas.md - Pitfalls and debugging tips

Quick Example

export default {
  async tail(events, env, ctx) {
    // Process events from producer Worker
    ctx.waitUntil(
      fetch(env.LOG_ENDPOINT, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(events),
      })
    );
  }
};

observability - General Workers observability patterns, OTEL export
analytics-engine - Aggregated metrics storage for tail event data
durable-objects - Stateful event processing, batching tail events
logpush - Alternative for batch log export (non-real-time)
workers-for-platforms - Dynamic dispatch with tail consumers

README.md