dotfiles/.agents/skills/cloudflare-deploy/references/tail-workers/configuration.md

Tail Workers Configuration

Setup Steps

1. Create Tail Worker

Create a Worker with a tail() handler:

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

2. Configure Producer Worker

In producer's wrangler.jsonc:

{
  "name": "my-producer-worker",
  "tail_consumers": [
    {
      "service": "my-tail-worker"
    }
  ]
}

3. Deploy Both Workers

# Deploy Tail Worker first
cd tail-worker
wrangler deploy

# Then deploy producer Worker
cd ../producer-worker
wrangler deploy

Wrangler Configuration

Single Tail Consumer

{
  "name": "producer-worker",
  "tail_consumers": [
    {
      "service": "logging-tail-worker"
    }
  ]
}

Multiple Tail Consumers

{
  "name": "producer-worker",
  "tail_consumers": [
    {
      "service": "logging-tail-worker"
    },
    {
      "service": "metrics-tail-worker"
    }
  ]
}

Note: Each consumer receives ALL events independently.

Remove Tail Consumer

{
  "tail_consumers": []
}

Then redeploy producer Worker.

Environment Variables

Tail Workers use same binding syntax as regular Workers:

{
  "name": "my-tail-worker",
  "vars": {
    "LOG_ENDPOINT": "https://logs.example.com/ingest"
  },
  "kv_namespaces": [
    {
      "binding": "LOGS_KV",
      "id": "abc123..."
    }
  ]
}

Testing & Development

Local Testing

Tail Workers cannot be fully tested with wrangler dev. Deploy to staging environment for testing.

Testing Strategy

1. Deploy producer Worker to staging
2. Deploy Tail Worker to staging
3. Configure tail_consumers in producer
4. Trigger producer Worker requests
5. Verify Tail Worker receives events (check destination logs/storage)

Wrangler Tail Command

# Stream logs to terminal (NOT Tail Workers)
wrangler tail my-producer-worker

This is different from Tail Workers:

• wrangler tail streams logs to your terminal
• Tail Workers are Workers that process events programmatically

Deployment Checklist

• Tail Worker has tail() handler
• Tail Worker deployed before producer
• Producer's wrangler.jsonc has correct tail_consumers
• Environment variables configured
• Tested with staging environment
• Monitoring configured for Tail Worker itself

Limits

Limit	Value	Notes
Max tail consumers per producer	10	Each receives all events independently
Events batch size	Up to 100 events per invocation	Larger batches split across invocations
Tail Worker CPU time	Same as regular Workers	10ms (free), 30ms (paid), 50ms (paid bundle)
Pricing tier	Workers Paid or Enterprise	Not available on free plan
Request body size	100 MB max	When sending to external endpoints
Event retention	None	Events not retried if tail handler fails

Workers for Platforms

For dynamic dispatch Workers, both dispatch and user Worker events sent to tail consumer:

{
  "name": "dispatch-worker",
  "tail_consumers": [
    {
      "service": "platform-tail-worker"
    }
  ]
}

Tail Worker receives TWO TraceItem elements per request:

1. Dynamic dispatch Worker event
2. User Worker event

See patterns.md for handling.