Setting Up Stackdriver Debugger for Java

App Engine

Stackdriver Debugger is enabled automatically for Java applications running in both the Google App Engine standard and flexible environments.

Build, push and deploy your application

For both standard and flexible environment:

  1. Make sure you have version 1.9.20 or later of the Google App Engine SDK installed on your local workstation.

  2. Commit and push your source code to your Git repository:

    $ git commit -m 'Commit message.'
    $ git push google master
  3. Build and test your application using Maven or another build tool.

  4. Deploy your application using the appcfg command:

    $ update [WAR_LOCATION]

    For example:

    $ update ./target/myapp

The appcfg command generates a file named WEB-INF/classes/source-context.json and uploads it with your application. This file contains information about the version of the source code used to build the application. When you open Stackdriver Debugger in the Google Cloud Platform Console, it uses the information in this file to display the correct version of the source.

Compute Engine

You can use Stackdriver Debugger with any Java application running on a Google Compute Engine instance. We recommend that you enable it on all running instances of your application.

This page covers the setup steps required for most developers. Additional details and setup options (such as building from source and using a service account) are covered at


Stackdriver Debugger works with Compute Engine instances running:

  • A 64-bit Debian Linux image
  • Java JDK version 7 or 8

For instructions on creating a Compute Engine instance, refer to Creating and Starting an Instance in the Google Compute Engine documentation.

Download the agent

The Stackdriver Debugger agent is a lightweight binary that starts with your application and communicates with the Stackdriver Debugger backend while the application is running.

Once you've built and deployed your Compute Engine application, download the pre-built agent package:

mkdir /opt/cdbg
wget -qO- | \
    tar xvz -C /opt/cdbg

Set up the agent

The Stackdriver Debugger agent is a JVMTI agent that needs to be enabled when JVM starts, using the -agentpath option of the Java launcher. Most Debugger options are configured through system properties.

For example:

java -agentpath:/opt/cdbg/ \ \ \


  • PATH_TO_JAR_FILE is the relative path to the application's JAR file. For example: ~/myapp.jar.

  • MODULE is the name of your application or service. This, along with the version, is used to identify your application in the GCP Console. Examples: MyApp, Backend, or Frontend.

  • VERSION is the app version (e.g. the build ID). The GCP Console displays the running version as MODULE - VERSION. Example values: v1.0, build_147, or v20160520.

Web Servers

Java web servers usually start through a bootstrap process, and each web server has its own way of customizing Java options.


Add this line to /etc/default/tomcat7 or /etc/default/tomcat8:

JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/ \ \"

If you run Tomcat in a Docker container, add this line to Dockerfile instead:

ENV JAVA_OPTS -agentpath:/opt/cdbg/ \


Add these lines to /var/lib/jetty/start.d:


Generate the source context file

The source context file contains information about the version of the source code used to build your application. The Debug page in the GCP Console uses this information to display the correct version of the source.

To generate the source context file, run the following in the root directory of your local Git repository.

gcloud debug source gen-repo-info-file --output-directory="WEB-INF/classes/"

Then, deploy (or redeploy) your application to your Compute Engine instance, including the source-context.json file.

Using Stackdriver Debugger

After you have set up Stackdriver Debugger for use in your environment and you have started your application, you can use the Debug page in the GCP Console to capture and inspect the call stack and local variables in your application. See Using Stackdriver Debugger for more information.

Note that, when running in App Engine Standard, information about members of framework classes and private members of system classes is not displayed by Stackdriver Debugger. Attempting to inspect these objects returns a notice:

Non-public fields of system classes omitted

Send feedback about...

Stackdriver Debugger Documentation