This page describes setting up Stackdriver Profiler for profiling Java code. For Java, the Profiler offers CPU and wall-time profiling; see Profiling Concepts for more information.
You must use version 7, 8, or 9 of either the OpenJDK or the Oracle JDK.
Setting up Stackdriver Profiler typically involves installing the profiling agent and loading it when you start Java, providing configuration values for the agent as arguments. If you are using Java, you can use the profiling agent on Linux in the following environments:
- Compute Engine
- Kubernetes Engine
- App Engine flexible environment.
You can also profile Java code on non-Google Cloud Platform systems. See Profiling Outside Google Cloud Platform for more information.
Enabling the Profiler API
Before you use the profiling agent, ensure that the underlying
Profiler API is enabled. You can check the status of the API and enable
it if necessary by using either the Cloud SDK
gcloud command-line tool or
the Cloud Console:
If you have not already installed the Cloud SDK on your workstation, see Google Cloud SDK.
To see if the Profiler API is enabled, run the following command on your workstation:
gcloud services list
cloudprofiler.googleapis.comappears in the output, the API is enabled.
If the API is not enabled, run the following command to enable it:
gcloud services enable cloudprofiler.googleapis.com
For more information, see
- Select the project you will use to access the API.
- Click the Enable APIs and Service button.
- Search for “Stackdriver”.
- In the search results, click through to “Profiler API”.
- If “API enabled” is displayed, then the API is already enabled. If not, click the Enable button.
Installing the Profiler agent
Create a directory, for example,
/opt/cprof, in which to
install Stackdriver Profiler:
sudo mkdir -p /opt/cprof
Download the agent archive from the
repository and extract it into the installation directory:
wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \ | sudo tar xzv -C /opt/cprof
Modify the service container Dockerfile to create a directory in which to install Stackdriver Profiler, download the agent archive, and extract it into the installation directory:
RUN mkdir -p /opt/cprof && \ wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \ | tar xzv -C /opt/cprof
App Engine flexible environment
The Stackdriver Profiler agent is included in the base Java images for Java 8 and Java 9, so there is nothing to install.
Loading the Profiler agent
To profile your code, start Java as you normally would to run your program, but specify the agent-configuration options. You specify the path to the agent library, and you can pass options to the library.
-agentpath option to specify the path to the agent library in the
installation directory, and pass additional configuration to the library.
The syntax looks like this:
The most common options include:
-cprof_service: A name for the service being profiled
-cprof_service_version: (optional) The version of the service being profiled
To profile your code, add the
-agentpath configuration to your regular Java
invocation. For example, to run
myApp.jar and profile it, a minimal invocation
java -agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myApp -jar myApp.jar
Service name and version arguments
When you load the Profiler agent, you specify a service-name argument and an optional service-version argument to configure it.
The service name lets Profiler collect profiling data for all replicas of that service. The profiler service ensures a collection rate of one profile per minute, on average, for each service name across each combination service versions and zones.
For example, if you have a service with two versions running across replicas in three zones, the profiler will create an average of 6 profiles per minute for that service.
If you use different service names for your replicas, then your service will be profiled more often than necessary, with a correspondingly higher overhead.
When selecting a service name:
Choose a name that clearly represents the service in your application architecture. The choice of service name is less important if you only run a single service or application. It is more important if your application runs as a set of micro-services, for example.
Make sure to not use any process-specific values, like a process ID, in the service-name string.
The service-name string must match this regular expression:
A good guideline is to use a static string like
imageproc-service as the
The service version is optional. If you specify the service version, Profiler can aggregate profiling information from multiple instances and display it correctly. It can be used to mark different versions of your services as they get deployed. The Profiler UI lets you filter the data by service version; this way, you can compare the performance of older and newer versions of the code.
The value of the service-version argument is a free-form string, but values
for this argument typically look like version numbers, for example,
Starting your program
Start Java as you normally would to run your program, and add the the agent-configuration options:
java \ -agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myservice,-cprof_service_version=1.0.0 \ [JAVA OPTIONS] -jar PATH/TO/YOUR/JARFILE [PROGRAM OPTIONS]
Modify the service container Dockerfile to start Java as you normally would to run your program, and add the agent-configuration options:
RUN java \ -agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myservice,-cprof_service_version=1.0.0 \ [JAVA OPTIONS] -jar PATH/TO/YOUR/JARFILE [PROGRAM OPTIONS]
App Engine flexible environment
app.yaml configuration file to
PROFILER_ENABLE environment variable. Then just start
your program as usual:
env_variables: PROFILER_ENABLE: true
See Defining environment variables for more information.
The profiling agent can report debug information in its logs. To enable this
logging in the profiling agent, append the
-logtostderr flag to the
-agentpath configuration. This instructs the agent to log output to the
standard-error stream. For example:
java -agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myApp,-logtostderr -jar myApp.jar