skip to content

Logs, Tail & Traces

Workers Logs, wrangler tail, Tail Workers, Logpush and automatic traces show what a deployed Worker did. Interviewers ask how to debug a production exception and what sampling drops.

on this pageshow

explore

questions

6

How do you stream a deployed Cloudflare Worker's live logs with `wrangler tail`, and which filters narrow what it shows?

level: juniorimportance: must knowfreq 45%

answer

  1. live, not stored
  2. reads the name from the Wrangler file
  3. filters are applied before events reach you
  4. --status, --search, --method, --ip self

basics

~20 s

wrangler 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 s

Run `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 lines
bash
npx 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.25

go deeper

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.
open as a page

A production Cloudflare Worker API returns intermittent 500s; how do you find the failing invocations and their cause with Workers Logs and `wrangler tail`, without redeploying?

level: seniorimportance: must knowfreq 40%

basics

~20 s

Query Workers Logs for $workers.outcome = "exception" and for a 5xx $workers.event.response.status, because a handled 500 finishes with outcome ok. Read the exception and structured console.error fields, then confirm live with wrangler tail --status error or --search.

open as a page

In Cloudflare Workers, what does the Wrangler `observability` block turn on, and what does `head_sampling_rate` keep or drop?

level: middleimportance: should knowfreq 40%

basics

~20 s

The observability block makes Cloudflare store a Worker's invocation logs, console output and uncaught exceptions in Workers Logs; traces need traces.enabled. head_sampling_rate (default 1) keeps that fraction of invocations whole and stores nothing from the rest.

open as a page

Why does a bundled Cloudflare Worker's production stack trace point at the wrong file and line, and what does `upload_source_maps` change?

level: middleimportance: should knowfreq 30%

basics

~20 s

Wrangler deploys bundled, often minified JavaScript, so runtime stack traces point into the bundle. With upload_source_maps: true the map is uploaded with the version, and Cloudflare remaps uncaught-exception traces in real-time logs, Tail Workers and Issues.

open as a page

What is a Cloudflare Tail Worker, how does a producer Worker attach one with `tail_consumers`, and what does its `tail()` handler receive?

level: middleimportance: should knowfreq 30%

basics

~20 s

A 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.

open as a page

How does Workers Trace Events Logpush send a Cloudflare Worker's logs to an outside destination, and what does it truncate?

level: middleimportance: nice to knowfreq 20%

basics

~20 s

On Workers Paid, an account-level Logpush job on the workers_trace_events dataset ships events from every Worker set to logpush: true: request metadata, console messages and uncaught exceptions. Logs and exceptions share 16,384 characters; past that they are truncated.

open as a page