Cloudflare Workers Profiling: Sampling, Overhead, Retention

Cloudflare Workers profiling via the built-in --profiling flag and the Workers Logs/Real User Monitoring (RUM) tools samples CPU usage at a low rate, adds minimal overhead (typically under 1% CPU), and retains profile data for a limited window—currently around 7 days for logs and traces, with CPU profiling snapshots available for about 1 hour after a request. This article explains exactly how sampling works, what overhead you can expect, how long data is kept, and how to interpret the results.

Background: Why Profiling Workers Is Hard

Cloudflare Workers run on the V8 JavaScript engine across a global network of edge nodes. Unlike a traditional server, you don’t have a single machine to attach a debugger to—requests are distributed, and each isolate is short-lived. Profiling is therefore done via sampling: the runtime periodically captures the call stack of a running worker, rather than instrumenting every function call. This keeps overhead low but means you get a statistical picture, not a line-by-line trace.

Cloudflare provides two main profiling paths:

• Workers Logs and Traces – structured logs with timing and error info, retained for 7 days.
• CPU profiling – triggered via the --profiling flag during wrangler dev or via the Workers observability dashboard, producing a .cpuprofile file viewable in Chrome DevTools.

How Sampling Works

When you enable profiling, V8 uses its built-in sampler, which interrupts the JavaScript execution at a fixed interval (typically 1 ms or 10 ms depending on the platform) and records the current call stack. The result is a set of samples, each representing where the worker was at that instant. The more samples you collect, the more accurate the profile.

In Cloudflare’s implementation, the profiler runs for a short duration—often the entire request—and then uploads the profile to the dashboard. For the --profiling flag in wrangler dev, the profile is written locally. On the edge, the Workers Logs product lets you enable CPU profile on a per-request basis, but only for a subset of requests due to cost and storage.

Overhead: What to Expect

Sampling overhead is generally low because the profiler does not instrument every function—it just takes periodic snapshots. In practice, the overhead is usually under 1% of CPU time for a typical worker. For CPU-bound workers with heavy loops, the overhead can rise to 2-3% because the profiler interrupts more frequently. Memory overhead is negligible (a few kilobytes for the sample buffer).

Cloudflare does not charge extra for enabling profiling, but it does count toward your CPU time usage. If you enable profiling on a high-traffic worker, you may see a small increase in CPU consumption, which could push you over the free tier’s 10ms CPU limit per request.

Data Retention: How Long Profiles Are Kept

Retention depends on the product:

• Workers Logs (including traces): 7 days. Logs are stored in Cloudflare’s log storage and are accessible via the dashboard or API.
• CPU profiles (from the dashboard): 1 hour. After that, the profile is deleted and cannot be retrieved. This is because the profile files are large and are meant for immediate debugging.
• Local profiles from --profiling: kept on your machine indefinitely until you delete them.

If you need longer retention, you can export the profile and store it in your own system (e.g., in R2 or an external log service) using the Workers Logs API.

How to Choose the Right Profiling Method

Your choice depends on what you need:

• Quick CPU bottleneck check: Use wrangler dev --profiling to get a local profile. This is free and has no retention limit.
• Production issue on a live request: Enable CPU profile in the Workers dashboard for a specific request ID. You have about an hour to inspect it.
• Long-term performance trends: Use Workers Logs with sampling enabled (e.g., log 1% of requests) and rely on the 7-day retention to spot patterns.

For most debugging, start with the local profiler—it’s easier to iterate. For production, use the dashboard’s per-request profiling, but be aware of the 1-hour window.

Common Problems and Misconceptions

A common misconception is that the profiler shows every function call. It does not—it shows a statistical sample. If a function runs quickly, it may not appear in the profile even if it’s called often. To get a reliable picture, you need enough samples (at least 1000) or a long-running request.

Another issue is that enabling profiling can change the performance of the worker due to the sampling overhead. This is rare but possible for extremely tight loops. If you see a significant slowdown when profiling is on, consider profiling a lower percentage of requests.

Also, profiles are only captured for requests that complete. If a request times out or is killed, the profile may be incomplete or missing.

Comparison with Other Platforms

Compared to AWS Lambda’s Lambda Insights or Google Cloud Functions’ profiling, Cloudflare’s approach is more lightweight but less deep. Lambda Insights gives you metrics and logs, but not full CPU profiles. Cloudflare’s CPU profiling is unique in that it gives you a Chrome DevTools-compatible profile, which is a huge advantage for debugging. However, the 1-hour retention is much shorter than AWS’s 7-day log retention.

Costs and Limits

Profiling itself is free, but it uses CPU time. On the free plan, you have 10ms of CPU per request. If profiling adds 1ms to a request that already uses 9ms, you’ll be over the limit and the request will fail. On the paid plan, you have 30s of CPU per request, so profiling overhead is rarely an issue.

Data retention is also subject to your plan: paid plans get 7 days of logs, free plans get 3 days. CPU profiles are always 1 hour regardless of plan.

Frequently Asked Questions

How do I enable profiling on a live worker?

In the Cloudflare dashboard, go to your Worker, then to the Logs tab. Under Log settings, enable CPU profile and set a sampling rate (e.g., 1%). Then, when a request is sampled, you’ll see a Profile button next to the log entry. Click it to download the .cpuprofile file. You have one hour to do this.

What does the --profiling flag do in wrangler?

It runs your Worker locally with V8’s CPU profiler enabled. After the request completes, it writes a .cpuprofile file to your current directory. You can open this in Chrome DevTools’ Performance tab to see a flame chart.

Can I profile a Worker that uses WebAssembly?

Yes, but the profile will show the JavaScript glue code, not the internal WASM functions. To profile WASM, you need to use the --prof flag with Node.js or use the DevTools’ WASM profiling features, which are not available in Cloudflare’s dashboard.

Why is my profile empty or missing?

If the request completed in under 10ms, the profiler may not have captured enough samples. Also, if the request was served from cache (no Worker execution), no profile is generated. Ensure you are profiling a request that actually runs your code.

How can I reduce sampling overhead?

Lower the sampling rate in the dashboard (e.g., 0.1% instead of 1%). This reduces the chance that a request is profiled, but also reduces the chance you’ll catch a rare bug. For local profiling, you can’t change the rate; it’s fixed by V8.

Related

• NTSC vs PAL DVD: Which Format Should You Burn?
• COUNTIFS with Variable Table Column?
• Forza Horizon 6 Tokyo Tower Photo Challenge Location