How do you stream a deployed Cloudflare Worker's live logs with `wrangler tail`, and which filters narrow what it shows?
answer
- live, not stored
- reads the name from the Wrangler file
- filters are applied before events reach you
- --status, --search, --method, --ip self
basics
~20 swrangler tail streams a deployed Worker's invocations live to the terminal: request, outcome, console output and exceptions. Filters such as --status error, --search, --method, --header, --ip self and --version-id narrow the stream, and nothing is stored.
solid answer
~50 sRun `npx wrangler tail` in the project, where it reads the Worker's name from the Wrangler file, or `wrangler tail <name>`. Each event carries the request, the invocation `outcome`, `console` lines and uncaught exceptions; output is pretty in a terminal and JSON when piped, or chosen with `--format json` or `--format pretty`. Filters are sent to Cloudflare and applied before events reach you: `--status ok|error|canceled` (where `error` covers the `exception`, `exceededCpu`, `exceededMemory` and `unknown` outcomes), `--method`, `--header`, `--search` for text in console messages, `--ip self`, `--version-id`, and `--sampling-rate` between 0 and 1. A busy Worker can push the session into sampling mode, which drops messages with a warning; filtering helps and can take up to a minute to take effect. At most 10 clients can view one Worker's live logs at once, and nothing streamed is stored.
code
bash · 4 linesnpx wrangler tail orders-api --status error
npx wrangler tail orders-api --search "order_lookup_failed" --method POST
npx wrangler tail orders-api --ip self --format pretty
npx wrangler tail orders-api --format json --sampling-rate 0.25go deeper
Recall that wrangler tail streams a deployed Worker's live invocations, console output and exceptions, that it stores nothing, and the common filters such as --status and --search.
Explain that filters run on Cloudflare's side, what --status error expands to, and why a busy Worker's session enters sampling mode and drops messages.
Use tail deliberately in production: start with narrow filters, isolate your own traffic with --ip self, and confirm a fix by filtering on the new version id.
Treat live tailing as an incident tool, not a logging strategy; anything a team must see later belongs in Workers Logs, a Tail Worker or an export.
## What `wrangler tail` is **Real-time logs** are Cloudflare's live view of a deployed Worker: its invocations, from anywhere in the world, streamed to you a moment after they happen, with busy Workers subject to sampling. `wrangler tail` is the command-line way to open that stream; the dashboard's **Live** view under a Worker's **Logs** is the other. It shows the same data Workers Logs records (the request, the invocation outcome, `console` output, errors and uncaught exceptions), but it **stores nothing**. Close the session and the events are gone; for history you query Workers Logs. It always watches the deployed Worker on Cloudflare's network. It does not show a `wrangler dev` session, which prints its logs in its own terminal. ## Starting a session 1. Change into the Worker's project directory, so Wrangler reads `name` from the Wrangler file, or pass the name: `npx wrangler tail orders-api`. A route such as `example.com/*` also works in place of the name. 2. Be authenticated to the Cloudflare account that owns the Worker. 3. Send traffic and watch. In a terminal the output is **pretty**, one readable block per invocation; when the output is piped, Wrangler switches to **JSON**, one object per event with fields such as `outcome`, `logs`, `exceptions`, `eventTimestamp` and `event.request`. `--format` overrides the choice. ## Reading one event Each event describes one invocation. In JSON form the fields to read first are: - `outcome`: how the invocation ended, such as `ok`, `exception` or `canceled`. It is the run's exit status, not the HTTP status. - `exceptions`: each uncaught exception with its name and message; with source maps uploaded, the stack points at your original files. - `logs`: every `console` call with its level, so `console.error` output stands out from `console.log`. - `event.request`: the URL, method, headers and the `cf` object for a fetch invocation. - `eventTimestamp`: when it ran, in epoch milliseconds. The pretty format prints the same events in a layout meant for reading, which is easier to scan but harder to process with other tools. ## The filters Filters are sent to Cloudflare with the session and applied before events are sent to you, so they cut the volume on the wire, not just on screen. | Flag | Keeps events where | |---|---| | `--status ok`, `error` or `canceled` | the outcome matches; `error` expands to `exception`, `exceededCpu`, `exceededMemory` and `unknown` | | `--method POST` | the request used that HTTP method | | `--header x-debug:1` | the request carried that header, optionally with that value | | `--search order_lookup_failed` | a `console` message contains the text | | `--ip self` | the request came from your own IP address (or a listed one) | | `--version-id <id>` | the invocation ran that Worker version | | `--sampling-rate 0.25` | a fraction of events, strictly between 0 and 1 | `--status`, `--method` and `--ip` accept several values. `--status error` does **not** match a request your code handled and answered with a 500: that invocation finished normally, so its outcome is `ok`. Find those with `--search` on the message your error path logs. ## Sampling mode and other limits - **Sampling mode.** When a Worker produces more events than the stream can carry, the session drops some messages and prints a warning. Adding filters is the fix; after a filter is added, the session can take up to 60 seconds to leave sampling mode. - **Ten viewers.** At most 10 clients, counting dashboard Live sessions and `wrangler tail` processes together, can view one Worker's live logs at once. - **WebSocket handlers.** `console.log` output from WebSocket event handlers is held back until the client closes the connection, then printed all at once. - **Durable Objects.** Logs from Durable Objects the Worker uses appear in the dashboard's live view. - **Region.** Real-time logs are not available for zones on the Cloudflare China Network. ## Where it fits in a debugging loop `wrangler tail` answers "what is happening right now?". A typical loop: - Reproduce the problem while tailing with `--ip self`, so only your own requests appear. - On a busy production Worker, start narrow (`--status error`, `--search` on an error event name) and widen only if nothing shows. - After shipping a fix, keep tailing with `--version-id` set to the new version to confirm the failures stopped. - For anything that happened before the session opened, query Workers Logs; for continuous processing of every event, attach a Tail Worker instead.
- Which invocations does `wrangler tail --status error` actually ask Cloudflare for?Wrangler expands `error` into the outcomes `exception`, `exceededCpu`, `exceededMemory` and `unknown`. A request your code caught and answered with a 500 finished normally, so its outcome is `ok` and it is not shown. Log a distinctive event name on your error path and filter with `--search` to catch those.
- Why does `wrangler tail --sampling-rate 1` fail instead of showing every event?Wrangler rejects a rate of 0 or below and of 1 or above, with "A sampling rate must be between 0 and 1 in order to have any effect." The flag only ever reduces the stream, so to see everything you leave it out.
- Why might `console.log` output from a Worker's WebSocket handlers appear in `wrangler tail` only much later?In real-time logs, messages logged inside WebSocket event handlers are hidden until the client closes the connection; on close they are flushed and printed together. For a long-lived socket, log to Workers Logs or emit on close if you need timely output.
- wrangler tail shows the logs of the wrangler dev session running on my machine.
- wrangler tail keeps history, so I can scroll back to this morning's errors.
- wrangler tail --status error also shows requests where my code returned a 500.
- Any number of engineers can tail the same Worker at the same time.
- The tail filters only hide lines locally after every event has been downloaded.