Guide: CPU and Memory Profiling for Cloudflare Workers in Production

How to capture CPU and memory profiles of a Worker or Durable Object in production, read the flamegraph, and avoid common interpretation errors.

Software engineering

When a Worker consumes too much CPU or approaches the memory limit, logs and aggregated metrics tell us that something is wrong, but not where. Cloudflare has launched on-demand CPU and memory profiling for Workers and Durable Objects, which generates interactive flamegraphs for code already running in production.

In this guide, we summarize how to approach a profiling session, what to expect from the results, and the limitations of the technique. We build on InfoQ's coverage and Cloudflare's documentation, so it's a good idea to cross-reference interface details with those sources.

What you need

• A Worker or Durable Object already deployed and receiving real traffic during the capture.
• Access to the Workers Observability dashboard or the cf command-line tool (refer to the installation reference).
• Source maps enabled if you're working with TypeScript, to ensure function names are readable.
• Optional: pprof or Chrome DevTools to analyze downloaded profiles offline.

In a flamegraph, the wider the block, the larger the proportion of CPU time or sampled allocations.

Steps to capture a profile

1. Identify the symptom: high latency, elevated CPU, or memory near the 128 MB limit, based on your metrics and logs.
2. Choose the profile type. CPU if you suspect redundant computation; memory (heap) if you suspect excessive objects or allocations.
3. Select the deployed Worker version. If it's a Durable Object, specify the particular instance by name.
4. Launch the capture from the Workers Observability dashboard or the CLI while the target receives sufficient traffic.
5. Open the flamegraph, locate the widest blocks, and if necessary, download the profile for analysis with pprof.

How it works internally

Profiling targets an isolate that is already running, not a new one, so you see the code under real traffic. For CPU, the runtime starts the V8 profiler with sampling every millisecond, releases the isolate lock while requests continue, and reacquires it only to stop the capture and collect results.

Since a script can have isolates in multiple data centers, the request must locate an active one of the requested version. For Durable Objects, which are stateful and can change location, the request is routed to the machine hosting that specific object.

# Illustrative outline; exact subcommands are in Cloudflare documentation
# 1. Choose the Worker and its deployed version
# 2. Request a CPU or heap profile
# 3. Download the result for analysis with pprof

We haven't invented specific commands: the CLI syntax should be copied from the official documentation. What's important is the workflow order: symptom, profile type, target, capture, and analysis.

Profiling complements logs, metrics, and traces: these tell you when, the profile tells you where.

What to expect from the results

CPU and memory answer different questions. A function can consume a lot of CPU without allocating much memory, and another can generate many allocations without dominating execution time. Therefore, it's advisable to capture both profiles before deciding where to optimize.

Cloudflare shares internal cases: a recursive JSON replacer that traversed nested data repeatedly, whose correction made it, according to the company, 2.7 times faster; a duplicated metrics call that accounted for about 1% of CPU; and partially disabled Prometheus code that reduced memory usage at the 99.9th percentile from 133 MB to 118 MB when removed. These figures are declared by the provider.

Tip If the capture is almost empty, the problem is usually insufficient traffic during the window. Launch the profile during a period of load and don't forget source maps in TypeScript: without them, flamegraph names will be difficult to read.

Keep the limitations in mind. On-demand capture is not continuous monitoring: a short window might miss intermittent problems. Additionally, a heap profile records allocations during capture, not a complete snapshot of retained memory. Cloudflare says it's working towards continuous profiling, but for now, you need to anticipate when to capture.

Opinion · My 12-month prediction

I believe that in the next twelve months, on-demand profiling will go from a curiosity to a habit for teams using Workers. The reason is practical: you no longer need to reproduce real traffic locally to find out which function is consuming CPU or memory.

Cloudflare says they are working on continuous profiling, and I bet that will be the next step. In the meantime, the value lies in combining logs, metrics, and profiles. Those who do so will detect intermittent problems that are currently overlooked much sooner.

Related articles from LaRebelión

How to Save Memory in a Consistent Hash Ring, Cloudflare StyleGuide to Migrating to Final Structured Concurrency in JDK 28How to Scale Git: Reference Quorums and Object Storage

• Software engineering
• Cloudflare's tsrs: A Guide to Evaluating the TypeScript to Rust Port
• Integrate DuckDB into Amazon Aurora PostgreSQL with This Technical Guide

Original source: infoq.com

Article generated with AI.larebelion

Kernel · Head of Technology · Spain

«Going from knowing something is slow to seeing which function causes it, without reproducing it locally, is the real game-changer of this new feature.»