Cloud Profiler

Cloud Profiler allows you to continuously profile CPU and heap usages to help identify performance bottlenecks and critical paths in your application. It'll be able to produce flame graph on which parts of your application uses the most CPU and/or Heap.

Enable API

gcloud services enable

CPU Time

The CPU time for a function tells you how long the CPU was busy executing instructions. It doesn't include the time the CPU was waiting or processing instructions for something else.

Wall Time

The wall-clock time for a function measures the time elapsed between entering and exiting a function. Wall-clock time includes all wait time, including that for locks and thread synchronization. If the wall-clock time is significantly longer than the CPU time, then that is an indication the code spends a lot of time waiting. This might be an indication of a resource bottleneck.


The heap consumption is the amount of memory allocated in the Java program's heap - this can help you find potential inefficiencies and memory leaks in your application.

Java Agent

Cloud Profiler works by adding a Java agent to your JVM startup argument, and the agent can communicate with the Cloud Profiler service in the Cloud. Through the Cloud Console, you can then see the collected profile data.

Agent Files

A Cloud Profiler agent can work both within Google Cloud environments using the Machine Credentials, and outside of Google Cloud environments (e.g., on-premises, and in another cloud) using a Service Account key file.

Unfortunately, the list of versions are not available on GitHub. The only way to see the list of available versions is listing the Google Cloud Storage bucket that contains all the binaries:

gsutil ls gs://cloud-profiler/java/cloud-profiler-*

See Profiling Java Applications for more information.

Agent Configurations

Agent Path

To use the agent, you'll need to configure the JVM command line using the standard -agentpath , e.g.:

java -agentpath:/opt/cprof/ \
  -jar ...

Rather than hard coding the startup command line, you can also configure it with the JAVA_TOOL_OPTIONS environmental variable:

java -jar ...

Agent Configurations

You can specify additional Agent configurations within the same agentpath argument, in the form of java -agentpath:/opt/cprof/,FLAG2=VALUE2.

Heap sampling is only available in Java 11 and higher. To turn on both CPU and Heap profiling for a Java 11 application:

java -agentpath:/opt/cprof/ \
  -jar ...

See Profiling Java applications Agent Configuration document for all the possible agent configuration flags.


By default the Cloud Profiler does not output any logs. You can turn on logging by using -logtostderrflag, and configure the log level using ‑minloglevelflag.

java -agentpath:/opt/cprof/,-minloglevel=2 \
  -jar ...

See Profiling Java applications Agent Logging document for all the possible log levels.

Runtime Configuration

Follow App Engine Hello World! instructions to deploy an application to App Engine.

Cloud Profiler agent is already present in your App Engine application. However, it is not on by default. You can turn it on by using the JAVA_TOOL_OPTIONS environmental variable in an app.yaml file:

runtime: java11
  JAVA_TOOL_OPTIONS: "-agentpath:/opt/cprof/,-cprof_enable_heap_sampling=true"

Redeploy the application with the app.yaml file:

gcloud app deploy target/helloworld.jar \
  --appyaml app.yaml

It'll take a couple of minutes before Cloud Profiler can display the information. In Cloud Profiler console, you can find the Default service in the drop down:

Last updated