What is a Cloudflare Tail Worker, how does a producer Worker attach one with `tail_consumers`, and what does its `tail()` handler receive?
answer
- runs after the producer finishes
- a list of services in the producer's config
- one item per invocation, with outcome
- headers and ID-like URL parts redacted
basics
~20 sA Tail Worker is a Worker with a tail() handler that Cloudflare invokes after each invocation of a producer Worker listing it in tail_consumers. It receives items with the outcome, request, response status, console logs and exceptions.
solid answer
~40 sA Tail Worker is an ordinary Worker that exports a `tail(events, env, ctx)` handler. A producer attaches it with `"tail_consumers": [{ "service": "orders-tail" }]` in its Wrangler file; every Worker listed there must define `tail()`. Cloudflare invokes it after each producer invocation has finished, so it adds no latency to the producer's response. `events` is an array of items carrying `scriptName`, `outcome`, `eventTimestamp`, `event.request` (url, method, headers, `cf`), `event.response.status` for fetch events, `logs` with level and message, and `exceptions` with name and message. Sensitive headers such as `authorization` and `cookie`, and ID-like segments of the URL, arrive as `REDACTED` unless the code calls `getUnredacted()`. Do asynchronous work through `ctx.waitUntil()`. `tail_consumers` is not inherited by Wrangler environments. Tail Workers need Workers Paid or Enterprise and are billed by CPU time.
code
json · 11 lines{
"name": "orders-api",
"main": "src/index.js",
"compatibility_date": "2026-10-10",
"tail_consumers": [{ "service": "orders-tail" }],
"env": {
"staging": {
"tail_consumers": [{ "service": "orders-tail" }]
}
}
}go deeper
Recall that a Tail Worker exports a tail() handler and that a producer attaches it by listing it in tail_consumers in its Wrangler file.
Explain what each event item carries, that the Tail Worker runs after the producer finishes, and why outcome and HTTP status must be read separately.
Show the production details: redacted headers and URLs, ctx.waitUntil for forwarding, tail_consumers missing from an environment, and CPU-time cost per invocation.
Decide when custom tail processing earns its upkeep versus built-in export, and who owns the Tail Worker, its alert routing and its own failures.
## What a Tail Worker is A **Tail Worker** is a Cloudflare Worker that receives telemetry about other Workers, called **producer Workers**. After each producer invocation finishes, Cloudflare calls the Tail Worker's `tail()` handler with what happened: the request, the outcome, the `console` output and any uncaught exceptions. The Tail Worker can then filter, reshape, count or forward that data, to an HTTP endpoint, a KV namespace, a database or an analytics store. Two properties set it apart from the other log paths: - It runs **after** the producer has finished, so it adds no latency to the producer's response. - It sees **every** invocation, including subrequests the producer made through service bindings and dynamic dispatch, rather than a stored sample. Tail Workers are available on the Workers Paid and Enterprise plans and are billed by **CPU time**, not by the number of events. Cloudflare describes them as the advanced option; for shipping logs and traces to a standard backend, OpenTelemetry export sends batches without code. ## Attaching one 1. Create a Worker that exports a `tail()` handler. A Worker listed as a consumer must define it. 2. Deploy it, for example as `orders-tail`. 3. In the producer's Wrangler file, add `"tail_consumers": [{ "service": "orders-tail" }]` and deploy the producer. `tail_consumers` is **non-inheritable**: a named Wrangler environment such as `staging` does not pick it up from the top level. Wrangler warns when the top level has it and an environment does not; each environment that should be tailed lists it again. ## What `tail(events, env, ctx)` receives `env` holds the Tail Worker's own bindings and `ctx` provides `waitUntil()`. `events` is an array of items, normally one per producer invocation: | Field | Contents | |---|---| | `scriptName` | Name of the producer Worker | | `outcome` | How the invocation ended, for example `ok`, `exception`, `exceededCpu`, `exceededMemory`, `canceled`, `responseStreamDisconnected`, `scriptNotFound` or `unknown` | | `eventTimestamp` | Epoch milliseconds | | `event.request` | `url`, `method`, `headers` and the `cf` object | | `event.response.status` | HTTP status of a fetch invocation | | `logs` | Each `console` call as `{ level, message, timestamp }` | | `exceptions` | Each unhandled exception as `{ name, message, timestamp }` | An invocation can record several exceptions, because a Worker can register several asynchronous tasks. ## Redaction by default To make accidental capture of credentials harder, `event.request` is **redacted** heuristically: - Header values become `REDACTED` when the header is `cookie` or `set-cookie`, or its name contains `auth`, `key`, `secret`, `token` or `jwt`. - ID-like runs in the URL (32 or more hex digits, or base-64-looking runs of 21 or more characters) become `REDACTED`. - `getUnredacted()` returns the original values. Calling it means you now decide what is kept, and where. The rules are heuristics, so they miss some sensitive values and redact some harmless ones. ## Outcome is not the HTTP status The `outcome` field is the invocation's exit status, whether it ran to completion, and it can disagree with the response code in both directions: - A producer that catches an error and returns a `500` ran to completion, so its outcome is `ok`. - A producer that returns a `200` and then has work registered with `ctx.waitUntil()` exceed a CPU or memory limit ends with a failure outcome the client never saw. A Tail Worker that alerts on failures therefore reads both `outcome` and `event.response.status`. ## When a Tail Worker is the right tool - **Custom filtering or sampling** that the built-in settings cannot express, such as keeping every failure but one success in a thousand. - **Aggregation**, such as counting errors per route or per customer and writing the totals to an analytics store. - **Routing**, such as sending one team's failures to that team's alert endpoint. For plain shipping of logs and traces to an external backend, Cloudflare's OpenTelemetry export needs no code and sends batches instead of one call per invocation. ## Writing a useful Tail Worker - **Check both outcome and status.** `outcome` is the exit status of the invocation, not the HTTP code. A producer that catches an error and returns a 500 has outcome `ok`, so an alert on `outcome !== "ok"` alone misses it. - **Use `ctx.waitUntil()`** for the outbound `fetch`, so the work is tracked to completion. - **Keep it cheap.** It runs once per producer invocation; filter early and send only what someone will read. - **Watch the watcher.** A Tail Worker runs after the producer has responded, so its own failures are easy to miss; give it observability too.
- Why does a Tail Worker that alerts on `outcome !== "ok"` miss a producer's handled 500 responses?The outcome is the invocation's exit status, not its HTTP status. If the producer catches an error and returns a 500, the invocation completed normally and its outcome is `ok`. Check `event.response.status` as well, as the example does.
- What does a Tail Worker see in the `authorization` header of a producer's request?The string `REDACTED`, because header values are redacted when the name contains `auth`, `key`, `secret`, `token` or `jwt`, or is `cookie` or `set-cookie`. `getUnredacted()` returns the original request data; use it only when you need the raw value and have decided how it is stored.
- A Tail Worker runs inline and delays the producer's response until it finishes.
- Listing tail_consumers at the top level also covers the staging and production environments.
- A Tail Worker's outcome field is the HTTP status code of the producer's response.
- Tail Workers receive raw cookies and Authorization headers by default.
- Any Worker can be listed in tail_consumers, whatever handlers it exports.