Setting Up Cloud Debugger for Java

Overview

This page describes how to configure your environment and your Java application to use Cloud Debugger. For some environments, you must explicitly specify the access scope to let the Cloud Debugger agent send data. We recommend setting the broadest possible access scope and then using Identity and Access Management to restrict access. In keeping with this best practice, set the access scope to be all Cloud APIs with the option cloud-platform.

Language versions and compute environments

Cloud Debugger is available for Java versions 7, 8, 9, and 11 on the following compute environments:

App Engine Standard environment	App Engine Flexible environment	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos on Google Cloud	VMs and Containers running elsewhere	Cloud Functions

Setting up Cloud Debugger

To set up Cloud Debugger, complete the following tasks:

1. Verify the Cloud Debugger API is enabled for your project.

2. Install and configure the Debugger on the compute environment you're using.

3. Select your source code.

Verifying the Cloud Debugger API is enabled

To begin using Cloud Debugger, ensure that the Cloud Debugger API is enabled. Cloud Debugger is enabled by default for most projects.
Enable Cloud Debugger API

Note: Cloud Debugger is free to use. However, you need a Google Cloud project with billing enabled before you can use Cloud Debugger.

Canary snapshots and logpoints

The Debugger agent for Java can use canary snapshots and logpoints every time you set a snapshot or logpoint.

The Debugger agent canaries snapshots and logpoints to protect large jobs from any potential bug in the Debugger agent which can take the entire job down when a snapshot or a logpoint is applied.

To mitigate this, Debugger canaries snapshots and logpoints on a subset of your running instances each time they are set. After Debugger verifies the snapshot or logpoint does not adversely affect your running instances, Debugger then applies the snapshot or logpoint to all instances.

Note: Canarying is available for the Java Debugger agent version 2.25 and later.

To learn how to use Debugger in canary mode, go to the the Debug snapshots and Debug logpoints pages.

Enabling canary snapshots and logpoints

When you install the latest version of the Debugger agent, you have the option to enable or disable canarying. Canarying is disabled by default.

When to enable canary snapshots and logpoints

To protect deployment and production-critical workloads, enable canarying when debugging these workloads.

If you have a single instance, you can still debug with canarying enabled, but your single instance runs without canarying the snapshot or logpoint.

When not to enable canary snapshots and logpoints

Don't enable canarying on workloads that have an execution time of less than 40 seconds, for instance, jobs using Cloud Functions.

Don't enable canarying if you want a faster snapshot-triggering cycle.

To configure the Debugger agent to not canary snapshots and logpoints, go to the installation instructions for the Google Cloud platform you're using.

App Engine standard environment

The debugger is enabled by default; no configuration is required. The Debug page in the Cloud Console will try to display the Java source files used to build the app.

To learn more, see Selecting source code automatically.

App Engine flexible environment

The debugger is enabled by default for the Java runtime; no configuration is required. The Debug page in the Cloud Console will try to display the Java source files used to build the app.

The debugger is included by default for custom runtimes that use the Google-provided base images for Java. No configuration is required if the default entry point is used. The Debug page in the Cloud Console will try to display the Java source files used to build the app.

To use Cloud Debugger with custom runtimes built using other base images, follow the setup instructions for Compute Engine.

To learn more, see Selecting source code automatically.

Google Kubernetes Engine

Note: The Java agent is not regularly tested on Alpine Linux. This Dockerfile shows how to build a minimal image with the agent installed.

GCLOUD

To enable Debugger using gcloud, complete the following steps:

1. Create your cluster with one of the following access scopes:

   • https://www.googleapis.com/auth/cloud-platform grants your cluster access to all Google Cloud APIs.

   • https://www.googleapis.com/auth/cloud_debugger grants your cluster access to only the Debugger API. Use this access scope to harden your cluster's security.

   gcloud container clusters create example-cluster-name \
          --scopes=https://www.googleapis.com/auth/cloud_debugger
   

   Note: You cannot change the access scopes of a cluster after creation.

2. Add the following lines to your Dockerfile to add the Debugger agent to your containerized app and initialize it when the app is deployed:

   # Create a directory for the Debugger. Add and unzip the agent in the directory.
   RUN 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
   

   To install an earlier version of the agent, change the URL to the following value:

   https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

   Replace VERSION_NUMBER with the version of the agent you want to use, for example, https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. Canarying is not available on versions earlier than 2.25. To get the versions of the Debugger agent, go to the GitHub page for the Java agent.

3. Add the following lines to your Dockerfile to run the Debugger agent:

   To debug with canarying enabled:

   # Start the agent when the app is deployed.
   RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
       -Dcom.google.cdbg.module=MODULE \
       -Dcom.google.cdbg.version=VERSION \
       -Dcom.google.cdbg.breakpoints.enable_canary=true \
       -jar PATH_TO_JAR_FILE
   

   To debug with canarying NOT enabled, set the enable_canaryflag to false:

   -Dcom.google.cdbg.breakpoints.enable_canary=false
   

   Replace the placeholders in the command as follows:

   • PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

   • MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

The debugger is now ready for use when you deploy your containerized app.

To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.

CONSOLE

To enable Debugger using the console, complete the following steps:

1. After selecting your cluster type, click More options from the Node pools pane:

   

2. Select one of the following from the Security pane:

   • Allow full access to all Cloud APIs.

   • Allow access for each API and then select Enabled for Cloud Debugger.

3. Add the following lines to your Dockerfile to run the Debugger agent:

   To debug with canarying enabled:

   # Start the agent when the app is deployed.
   RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
       -Dcom.google.cdbg.module=MODULE \
       -Dcom.google.cdbg.version=VERSION \
       -Dcom.google.cdbg.breakpoints.enable_canary=true \
       -jar PATH_TO_JAR_FILE
   

   To debug with canarying NOT enabled, set the enable_canaryflag to false:

   -Dcom.google.cdbg.breakpoints.enable_canary=false
   

   Replace the placeholders in the command as follows:

   • PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

   • MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

The debugger is now ready for use when you deploy your containerized app.

To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.

Compute Engine

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

1. Make sure your Compute Engine VM instances are running:

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

2. Make sure your Compute Engine VM instances are created with the access scope option Allow full access to all Cloud APIs, or have one of the following access scopes:

   • https://www.googleapis.com/auth/cloud-platform
   • https://www.googleapis.com/auth/cloud_debugger

3. Download the pre-built agent package:

   # Create a directory for the Debugger. Add and unzip the agent in the directory.
   sudo 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
   

   To install an earlier version of the agent, change the URL to the following value:

   https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

   Replace VERSION_NUMBER with the version of the agent you want to use, for example, https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. Canarying is not available on versions earlier than 2.25. To get the versions of the Debugger agent, go to the GitHub page for the Java agent.

4. Add the agent to your Java invocation:
   (If you are using Tomcat or Jetty, see the Web Servers section.)

   To debug with canarying enabled:

   # Start the agent when the app is deployed.
   java -agentpath:/opt/cdbg/cdbg_java_agent.so \
       -Dcom.google.cdbg.module=MODULE \
       -Dcom.google.cdbg.version=VERSION \
       -Dcom.google.cdbg.breakpoints.enable_canary=true \
       -jar PATH_TO_JAR_FILE
   

   To debug with canarying NOT enabled, set the enable_canaryflag to false:

   -Dcom.google.cdbg.breakpoints.enable_canary=false
   

   Replace the placeholders in the command as follows:

   • PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

   • MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

The debugger is now ready for use with your app.

To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.

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:

To debug with canarying enabled:

# Start the agent when the app is deployed.
JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true"

To debug with canarying NOT enabled, set the enable_canaryflag to false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Replace the placeholders in the command as follows:

• PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

• MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

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

To debug with canarying enabled:

# Start the agent when the app is deployed.
ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true

To debug with canarying NOT enabled, set the enable_canaryflag to false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Replace the placeholders in the command as follows:

• PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

• MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

Jetty

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

To debug with canarying enabled:

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so \
-Dcom.google.cdbg.module=MODULE \
-Dcom.google.cdbg.version=VERSION \
-Dcom.google.cdbg.breakpoints.enable_canary=true

To debug with canarying NOT enabled, set the enable_canaryflag to false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Replace the placeholders in the command as follows:

• PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

• MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

Cloud Run and Cloud Run for Anthos on Google Cloud

1. Add the following commands to your Dockerfile to create a directory in which to install the Debugger agent, download the Debugger agent archive, and extract it into the installation directory:

   # Create a directory for the Debugger. Add and unzip the agent in the directory.
   RUN 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
   

   To install an earlier version of the agent, change the URL to the following value:

   https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

   Replace VERSION_NUMBER with the version of the agent you want to use, for example, https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. Canarying is not available on versions earlier than 2.25. To get the versions of the Debugger agent, go to the GitHub page for the Java agent.

   Locate the Java invocation and add the following flag to initialize the Debugger agent:

   To debug with canarying enabled:

   # Start the agent when the app is deployed.
   RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
       -Dcom.google.cdbg.breakpoints.enable_canary=true \
       -jar PATH_TO_JAR_FILE
   

   To debug with canarying NOT enabled, set the enable_canaryflag to false:

   -Dcom.google.cdbg.breakpoints.enable_canary=false
   

   Replace the placeholders in the command as follows:

   • PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

On the Debug page, select the location of the source code. To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.

The debugger is now ready to use.

Local and elsewhere

1. Download the debugger pre-built agent package:

   mkdir /opt/cdbg
   wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_service_account.tar.gz | \
       tar xvz -C /opt/cdbg
   

2. Download service account credentials.
   To use the Cloud Debugger agent for Java on machines not hosted by Google Cloud, the agent must use Google Cloud service-account credentials to authenticate with the Cloud Debugger Service.

   Use the Cloud Console Service Accounts page to create a credentials file for an existing or new service-account. The service-account must have at least the Cloud Debugger Agent role.

   Place the service-account JSON file alongside the Cloud Debugger agent for Java.

3. Add the agent to your Java invocation:

   To debug with canarying enabled:

   java -agentpath:/opt/cdbg/cdbg_java_agent.so \
     -Dcom.google.cdbg.module=MODULE \
     -Dcom.google.cdbg.version=VERSION \
     -Dcom.google.cdbg.breakpoints.enable_canary=true \
     -Dcom.google.cdbg.auth.serviceaccount.enable=true \
     -Dcom.google.cdbg.auth.serviceaccount.jsonfile=/opt/cdbg/gcp-svc.json \
     -jar PATH_TO_JAR_FILE
   

   To debug with canarying NOT enabled, set the enable_canaryflag to false:

   -Dcom.google.cdbg.breakpoints.enable_canary=false
   

   Replace the placeholders in the command as follows:

   • PATH_TO_JAR_FILE is the relative path to the app's JAR file. e.g.,: ~/myapp.jar.

   • MODULE is the name of the app. Together with version, it identifies the app in the Cloud Console. Examples: MyApp, Backend, or Frontend.

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

   • The GOOGLE_APPLICATION_CREDENTIALS environment variable can be used instead of adding the auth.serviceaccount.jsonfile system property.

   Note: Go to Managing service account keys to learn how to implement best practices for user-managed keys.

The debugger is now ready for use with your app.

The Debug page in the Cloud Console can display local source files, without upload, for local development. See Selecting source code manually.

Note: You can find the debugger agent's code and documentation on GitHub.