In Cloudflare Workers, what does the Wrangler `observability` block turn on, and what does `head_sampling_rate` keep or drop?
answer
- logs and traces are separate switches
- enabled is shorthand for logs.enabled
- decided once, at the start of an invocation
- default 1, valid range 0 to 1
basics
~20 sThe 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.
solid answer
~40 sSetting `observability.enabled` (shorthand for `observability.logs.enabled`) in the Wrangler file makes Cloudflare store each invocation's log, every `console` line and uncaught exceptions in Workers Logs, queryable in the dashboard for 3 days on Workers Free and 7 days on Workers Paid. Automatic tracing is a separate switch, `observability.traces.enabled`; while tracing is in beta, `enabled: true` alone still turns on logs only. `head_sampling_rate` is a number from 0 to 1 with a default of 1. The decision is made at the start of each invocation, so a sampled request keeps all of its logs and an unsampled one stores nothing in Workers Logs, however it ends. Logs and traces can carry their own rates (`logs.head_sampling_rate`, `traces.head_sampling_rate`), and `logs.invocation_logs: false` drops the per-invocation log while keeping `console` output.
code
json · 17 lines{
"name": "orders-api",
"main": "src/index.js",
"compatibility_date": "2026-10-10",
"observability": {
"enabled": true,
"redact_query_string": true,
"logs": {
"head_sampling_rate": 0.25,
"invocation_logs": true
},
"traces": {
"enabled": true,
"head_sampling_rate": 0.05
}
}
}go deeper
Recall that the observability block in the Wrangler file turns on Workers Logs, and that head_sampling_rate is a fraction from 0 to 1 with a default of 1.
Explain head-based sampling: one decision at the start of each invocation, all logs kept for a sampled one, nothing stored for the rest, and traces switched on and sampled separately.
Show that sampling drops failures as readily as successes, and pair a low rate with a Tail Worker that sees every invocation, plus a filtered wrangler tail while investigating.
Weigh log and trace volume against cost and retention per Worker, and make the observability block a reviewed part of every Worker's configuration rather than a dashboard toggle.
## What the block controls A Cloudflare Worker's **observability** settings live in its Wrangler file (`wrangler.jsonc` or `wrangler.toml`) under one `observability` object. They decide what Cloudflare records about each **invocation** (one run of a handler, such as one HTTP request reaching `fetch`) and how much of it is kept. Wrangler 3.78.6 or later is needed for Workers Logs. | Key | Default | What it does | |---|---|---| | `enabled` | on for newly created Workers | Shorthand for `logs.enabled`: store logs in Workers Logs | | `head_sampling_rate` | `1` | Fraction of invocations whose logs are stored, 0 to 1 | | `logs.head_sampling_rate` | `1` | The same rate, set for logs only | | `logs.invocation_logs` | on | `false` drops the per-invocation request log | | `traces.enabled` | off | Turns on automatic tracing | | `traces.head_sampling_rate` | `1` | Fraction of invocations that are traced | | `redact_query_string` | `false` | Removes query strings from request URLs in logs and traces | ## What one invocation writes With logs on, a sampled invocation produces three kinds of records in **Workers Logs**, the store behind the dashboard's Observability tab: - **The invocation log**: one per invocation, marked `$cloudflare.$metadata.type = "cf-worker-event"`, carrying the request, the response, the outcome and timing such as `$workers.cpuTimeMs`. Its message depends on the handler: `<Method> <URL>` for `fetch`, the cron schedule for a Cron Trigger, the queue name for a queue consumer. - **Custom logs**: every `console.log()`, `console.warn()` and `console.error()` call. Logging an object, such as `console.log({ orderId, route })`, lets Workers Logs extract each key as a field you can filter and group by; a concatenated string can only be found by text match. - **Errors and uncaught exceptions**, with their stack traces. Retention is 3 days on Workers Free and 7 days on Workers Paid. One account may write up to 5 billion logs a day; past that, Cloudflare applies a 1% head-based sample for the rest of the day. ## How head-based sampling decides **Head-based** means the keep-or-drop decision is taken once, at the head of the invocation, before any code runs. With `head_sampling_rate: 0.01`, roughly one invocation in a hundred is chosen, and for a chosen one every log inside it is collected. The consequences an interviewer listens for: 1. **Failures are sampled at the same rate as successes.** The outcome is unknown when the decision is made, so there is no head-sampling setting that keeps every error. 2. **An unsampled invocation stores nothing in Workers Logs**: no invocation log, no `console.error`, no exception. 3. **Changing the rate is a configuration change.** It goes in the Wrangler file and takes a deploy. The setting is inheritable, so a named environment without its own `observability` block uses the top-level one. 4. **Cost follows the rate.** Workers Paid includes 20 million log events a month, then $0.60 per additional million, until the move to Cloudflare Observability pricing on 2026-12-01. To catch the failures sampling drops, pair it with a Tail Worker, which is invoked for every producer invocation and can filter on outcome and status, and use a live `wrangler tail --status error` session while you investigate. ## Querying what was kept Every field of a stored event can be filtered and grouped in the dashboard's Query Builder. A filter such as `$workers.cpuTimeMs > 100` finds the expensive invocations, and keys from logged objects, such as `orderId`, become fields of their own. Because the rate is set per Worker and inherited by environments, a team can give a `staging` environment its own `observability` block with `head_sampling_rate: 1` while production samples, and deploy each with `wrangler deploy -e staging` or without the flag. ## Traces are a separate switch **Workers tracing** instruments a Worker without code changes: outbound `fetch` calls, binding calls such as KV reads and R2 writes, RPC calls, and the handler invocation itself become **spans** on one trace. It is turned on with `observability.traces.enabled: true` and sampled by its own `traces.head_sampling_rate` (default `1`). Tracing is in beta: Cloudflare plans to make `observability.enabled` turn on traces too, but today it enables logs only. Traces are kept for seven days. Some spans report `0 ms` because the runtime only advances its clock on I/O, a defence against timing attacks. ## A sensible setup for a busy Worker - Keep `logs.head_sampling_rate` high enough that a rare failure still lands in the store, and lower `traces.head_sampling_rate` separately, since traces are heavier. - Log objects, not concatenated strings, so fields such as `orderId` can be queried. - Set `redact_query_string: true` when query strings can carry tokens or personal data. - Keep the block in the Wrangler file rather than only in the dashboard, so the next `wrangler deploy` does not overwrite it.
- Can `head_sampling_rate` keep every failed invocation of a Cloudflare Worker while sampling the successful ones?No. The decision is made at the start of an invocation, before its outcome is known, so failures are dropped at the same rate as successes. To catch the failures sampling drops, keep the rate higher, attach a Tail Worker that filters on `outcome` and response status, or stream live with `wrangler tail --status error` while investigating.
- Why do some spans in a Cloudflare Workers trace show 0 ms when the work clearly took longer?As a defence against Spectre-style timing attacks, the Workers runtime advances its clock only when I/O happens. CPU-only work between two I/O events therefore reports 0 ms. Spans around `fetch` and binding calls are meaningful; for computation, read CPU time from the invocation log instead.
- What happens to Workers Logs when an account writes more than 5 billion logs in one day?Logging does not stop. For the rest of that day Cloudflare applies a 1% head-based sample, on top of the rates you configured, so a failure is less likely to be stored until the daily limit resets.
Head sampling is like a museum handing an audio recorder to some visitors at the entrance: a chosen visitor's whole visit is recorded, and an unchosen visitor leaves no recording, however eventful the visit turns out to be.
- Setting observability.enabled to true also turns on automatic tracing.
- head_sampling_rate is a percentage, so 10 means ten percent of requests.
- Head sampling keeps every error and only samples the successful requests.
- A request that was not sampled still keeps its console.error lines in Workers Logs.
- Workers Logs keeps a Worker's logs for 30 days on every plan.
Assumes the platform as of 2026-10-10: Workers tracing is in beta and observability.enabled turns on logs only, redact_query_string needs Wrangler 4.128.0 or later, and Workers Logs moves to Cloudflare Observability pricing on 2026-12-01.