Java Cloud Debugger

Overview

The Cloud Debugger lets you inspect the state of a Java application at any code location without stopping or slowing it down. The debugger makes it easier to view the application state without adding logging statements.

You can use the Cloud Debugger on both production and staging instances of your application. The debugger adds less than 10ms to the request latency only when the application state is captured. In most cases, this is not noticeable by users. The Cloud Debugger gives a read-only experience. Application variables can't be changed through the debugger.

The Cloud Debugger attaches to all instances of the application. The call stack and the variables come from the first instance to take the snapshot.

The Java Cloud Debugger is only supported on Linux at the moment. It was tested on Debian Linux, but it should work on other distributions as well.

The Cloud Debugger consists of 3 primary components:

The debugger agent (requires Java 7 and above).
Cloud Debugger backend that stores the list of snapshots for each application. You can explore the API using the APIs Explorer.
User interface for the debugger implemented using the Cloud Debugger API. Currently the only option for Java is the Google Developers Console. The UI requires that the source code is submitted to Google Cloud Repo. More options (including browsing local source files) are coming soon.

This document only focuses on the Java debugger agent. Please see the this page for explanation how to debug an application with the Cloud Debugger.

Options for Getting Help

StackOverflow: http://stackoverflow.com/questions/tagged/google-cloud-debugger
Google Group: cdbg-feedback@google.com

Installation

The easiest way to install the debugger agent is to download the pre-built package from the Internet:

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

Alternatively you can build the debugger agent from source code:

git clone https://github.com/GoogleCloudPlatform/cloud-debug-java.git
cd cloud-debug-java
chmod +x build.sh
./build.sh

Setup

The Java Cloud Debugger agent is a JVMTI agent that needs to be enabled when JVM starts. The agent is enabled by using -agentpath option with Java launcher. Most debugger options are configured through system properties.

For example:

java -agentpath:/opt/cdbg/cdbg_java_agent.so -jar ~/myapp.jar

By default the debugger agent assumes that it runs on Google Compute Engine and uses local metadata service to obtain the credentials. You can still use the Java Cloud Debugger outside of Google Compute Engine or on a virtual machine that does not allow API access to all Google Cloud services. This would require setting up a service account.

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"

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

ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so

Jetty

Add cdbg.ini file to /var/lib/jetty/start.d:

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so

Versioning

Developers normally run multiple versions of the application at the same time and multiple applications within the same project. You can tag each such entity with Cloud Debugger. This will make it easier to select the right application in the Cloud Debugger UI.

To tag the version of the application, please add one or more of these optional system properties:

-Dcom.google.cdbg.version=myversion
-Dcom.google.cdbg.module=mymodule
-Dcom.google.cdbg.minorversion=minor version or build ID

Logging

By default the Java Cloud Debugger write its logs to cdbg_java_agent.INFO file in the default logging directory. It is possible to change the log directory as following:

-agentpath:/opt/cdbg/cdbg_java_agent.so=--log_dir=/my/log/dir

Alternatively you can make the Java Cloud Debugger log to stderr:

-agentpath:/opt/cdbg/cdbg_java_agent.so=--logtostderr=1

Service Account

Service account authentication lets you run the debugger agent on any Linux machine, including outside of Google Cloud Platform. The debugger agent authenticates against the backend with the service account created in Google Developers Console. If your application runs on Google Compute Engine, metadata service authentication is an easier option.

The first step for this setup is to create the service account in .p12 format. Please see OAuth page for detailed instructions. If you don't have a Google Cloud Platform project, you can create one for free on Google Developers Console.

Once you have the service account, please note the service account e-mail, project ID and project number. Then copy the .p12 file to all the machines that run your application.

You will need to install the debugger agent that supports the service account. The URL is: https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_service_account.tar.gz.

To enable the service account authentication add these arguments to Java launcher command (same way as with -agentpath):

-Dcom.google.cdbg.auth.serviceaccount.enable=true
-Dcom.google.cdbg.auth.serviceaccount.projectid=myprojectid
-Dcom.google.cdbg.auth.serviceaccount.projectnumber=123456789
-Dcom.google.cdbg.auth.serviceaccount.email=email@something.com
-Dcom.google.cdbg.auth.serviceaccount.p12file=/opt/cdbg/svc.p12

pdeva / cloud-debug-java