Setting Up Stackdriver Debugger for Java applications on Google 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 http://github.com/GoogleCloudPlatform/cloud-debug-java/.

Requirements

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- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
    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/cdbg_java_agent.so -jar [PATH_TO_JAR_FILE] \
  -Dcom.google.cdbg.module=[MODULE] \
  -Dcom.google.cdbg.version=[VERSION]

Where:

[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 Cloud Platform Console. Examples: MyApp, Backend, or Frontend.
[VERSION] is the app version (e.g. the build ID). The Cloud Platform 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.

Tomcat

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

JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \
  -Dcom.google.cdbg.module=[MODULE] \
  -Dcom.google.cdbg.version=[VERSION]"

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

ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \
              -Dcom.google.cdbg.module=[MODULE] \
              -Dcom.google.cdbg.version=[VERSION]

Jetty

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

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so
-Dcom.google.cdbg.module=[MODULE] \
-Dcom.google.cdbg.version=[VERSION]

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 Cloud Platform 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 preview app 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 open the Debug page in the Cloud Platform Console. See Using Stackdriver Debugger for more information.