Setting Up Stackdriver Debugger for Java

This page describes how to configure your environment and your Java application to use Stackdriver Debugger. For some environments, you must explicitly specify the access scope to let the Stackdriver Debugger agent send data. We recommend setting the broadest possible access scope and then using Cloud 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.

App Engine standard environment

The debugger is enabled by default; no configuration is required. The Debug page in the GCP Console will try to automatically 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 GCP Console will try to automatically 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 GCP Console will try to automatically display the Java source files used to build the app.

To use the Stackdriver 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

  1. Create your cluster, with one of the following access scopes:
    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger

    To create a cluster using gcloud, do the following:

    1. (Optional) Update gcloud to the latest version:
      gcloud components update
    2. Set your default project ID:
      gcloud config set project [PROJECT_ID]
    3. If you're working with zonal clusters, set your default compute zone:
      gcloud config set compute/zone [COMPUTE_ZONE]
    4. If you're working with regional clusters, set your default compute region:
      gcloud config set compute/region [COMPUTE_REGION]
    5. Issue the create command:
      gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform

    For more detailed information on creating a cluster, see Creating a cluster.

  2. Follow the instructions for Compute Engine.

Compute Engine

You can use Stackdriver Debugger with any Java app running on a Google Compute Engine instance. We recommend that you enable it 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:

    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
    
  4. Add the agent to your Java invocation:
    (If you are using Tomcat or Jetty, see the Web Servers section.)

    java -agentpath:/opt/cdbg/cdbg_java_agent.so \
      -Dcom.google.cdbg.module=MODULE \
      -Dcom.google.cdbg.version=VERSION \
      -jar PATH_TO_JAR_FILE
    

    Where:

    • 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 GCP Console. Examples: MyApp, Backend, or Frontend.

    • VERSION is the app version (e.g., the build ID). The GCP 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 GCP 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:

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

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 Stackdriver Debugger agent for Java on machines not hosted by Google Cloud Platform, the agent must use GCP service-account credentials to authenticate with the Stackdriver Debugger Service.

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

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

  3. Add the agent to your Java invocation:

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

    Where:

    • 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. Along with version, it identifies the app 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 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.

The debugger is now ready for use with your app.

The Debug page in the GCP Console can display local source files, without upload, for local development. See Selecting Source Code Manually.

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Debugger Documentation