Cloud Profiler in GCP: What It Is, When to Use It, and How to Read Flame Graphs

What Cloud Profiler is

Cloud Profiler is a managed service that continuously collects performance profiles from your running application and stores them in Google Cloud. A profile is a statistical snapshot of where your program is spending its time or allocating memory. Cloud Profiler builds these profiles by periodically sampling your application’s call stack in production and uploading those samples to the Cloud Console for you to examine.

It works with Go, Java, Node.js, and Python applications. The agent is a library you initialize inside your application at startup. There is no separate process to manage and no infrastructure changes required. Once initialized, it runs in the background and collects profiles continuously.

The main output is a flame graph: a visual representation of your call stack that makes it straightforward to see which functions are consuming the most resources. Once you understand how to read one, Cloud Profiler becomes a fast way to find code-level performance problems in a running production system.

A simple explanation

This approach is called statistical sampling, and it is what makes Cloud Profiler safe for production. Because it only samples at intervals rather than tracking every function call, the CPU overhead is low enough to leave it running all the time, typically under 1%.

When to use Cloud Profiler

Cloud Profiler is most useful when you already have a signal that something is wrong with application code performance, but you do not yet know which function is responsible. Typical triggers include:

• High CPU utilization with no clear cause. Your Cloud Monitoring dashboards show elevated CPU, but there is no obvious spike in request volume or background job activity to explain it.
• Slow application spans in traces. Cloud Trace identifies a span as slow, but the time is not being spent in a database query or external API call. The time is inside your own application code.
• Unexpected memory growth. Your service is using more memory over time and you want to identify which code path is allocating objects that are not being released.
• Performance regression after a deployment. Latency increased after a recent deploy and you want to compare CPU profiles before and after to isolate what changed.
• Suspected allocation hotspots driving garbage collection. High GC pressure is causing latency spikes and you want to find which functions are creating the most short-lived objects.

Cloud Profiler is less useful for diagnosing problems caused by external dependencies such as a slow database query or a network call to a third-party API. Those are better investigated with distributed tracing and the dependency’s own metrics.

Cloud Profiler vs Cloud Trace

Cloud Trace and Cloud Profiler answer different questions and are designed to be used together, not instead of each other.

• Cloud Trace tells you which request or span is slow. It records timing information across services and shows you the sequence of operations that made up a request. Use it to identify that a particular endpoint is slow and to see which step in its execution is taking the most time.
• Cloud Profiler tells you which function inside your code is consuming CPU or time. It does not track individual requests. Instead, it samples the entire running process and shows you aggregate function-level cost across all traffic.

A common workflow: use distributed tracing to identify a slow service or span, then switch to Cloud Profiler to find the specific function or loop inside that service that is responsible. Trace gives you the where in your system. Profiler gives you the what inside the code.

How Cloud Profiler works

Cloud Profiler uses statistical sampling. The agent periodically interrupts the application and records which function is currently executing (for CPU profiles) or which objects are allocated in the heap (for memory profiles). By collecting thousands of samples over time, it builds a statistical picture of where time is spent without tracking every individual function call.

Profile collection happens in roughly 10-second windows, approximately once per minute per instance. When you have multiple instances of the same service running, Cloud Profiler coordinates across them so they do not all profile at the same time. This distributes the small overhead across your fleet rather than concentrating it on a single instance.

The agent uploads profile data to the Cloud Profiler backend, which aggregates samples into a flame graph visible in the Cloud Console. Because sampling only briefly interrupts the application at intervals, the CPU overhead is typically under 1%.

Supported profile types and language caveats

Cloud Profiler collects different profile types depending on what you are investigating. Not all profile types are available in all languages. The table below reflects the current supported combinations. Check the official documentation for the latest state, as support does expand over time.

Example setup: Python

Each supported language has its own agent and initialization path. The example below shows Python. Go, Java, and Node.js each have their own libraries and setup guides. See the Cloud Profiler documentation for language-specific instructions.

Install the Python agent:

Initialize it at application startup, before your web framework or main logic runs:

The service name groups profiles together in the console. Call googlecloudprofiler.start() once at startup; it runs in the background from that point forward and requires no further interaction.

IAM and permissions

The service identity used by your workload needs permission to upload profiles to Cloud Profiler. The required role is roles/cloudprofiler.agent. Grant this role to the specific service account your workload runs as, not a broad project-level role.

For example, if you are deploying to Cloud Run, identify the service account attached to that Cloud Run service and grant it roles/cloudprofiler.agent on the project. For GKE workloads using Workload Identity, ensure the Kubernetes service account is mapped to a Google service account that has this role.

How to read flame graphs

Cloud Profiler displays profiles as flame graphs. Two rules cover most of what you need to know:

To locate a bottleneck:

• Find wide bars that sit near the top of their call subtree. A wide bar with only narrow bars above it means that function itself is consuming resources, not something it called.
• A wide bar that spans many tall, narrow bars above it is a common ancestor. The expensive work is happening in a callee, not in the function itself.
• Do not focus on the deepest functions in the stack. Depth does not indicate cost. Width does.

You can click any bar in the Cloud Console flame graph to zoom into that subtree and examine its callees in more detail.

Comparing profiles across deployments

Cloud Profiler lets you compare two profiles side by side. Set service_version to a meaningful value such as your image tag or commit SHA so profiles are correctly labeled per deployment.

After deploying a new version, select two profiles in the console: one from before the deployment and one from after. Functions that grew wider in the new version are consuming more resources than before. Functions that shrank were improved.

This comparison mode is how you verify that a performance optimization actually worked at the code level. Aggregate latency metrics may show overall improvement but they do not isolate which specific function changed. The profile comparison does.

When this is not the right tool

Cloud Profiler answers one specific question: which function inside your application code is consuming resources? For other types of production problems, different tools are more appropriate:

• The bottleneck is an external dependency. Cloud Profiler samples your application code, not external services. If the slow path is a database query or a network call to a downstream API, use distributed tracing and the external system’s own metrics instead.
• You need to understand request-level latency across services. Cloud Profiler aggregates samples across all requests. It does not record individual request timings. Use Cloud Trace to analyze individual requests and identify which step in a multi-service call chain is consuming time.
• You need to investigate an error or exception. Cloud Profiler does not record errors or exceptions. Use Logs Explorer to search for errors and structured logging to capture request context around them.
• You need to understand resource utilization trends over time. Use Cloud Monitoring metrics and dashboards for historical trends in CPU, memory, and request rates.
• You are debugging a production crash or panic. Cloud Profiler does not capture crash data. Use logs and any crash reporting tooling available for your runtime.

For a broader view of how these tools fit together during a production investigation, see Debugging Production Systems.