Tail Workers Configuration

Setup Steps

1. Create Tail Worker

Create a Worker with a tail() handler:

  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

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.