Setting Up Stackdriver Debugger for Java

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.

Kubernetes Engine

  1. Make sure your cluster is created with one of the following access scopes:

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

    Example:

    gcloud container clusters create EXAMPLE-CLUSTER-NAME \
        --scopes https://www.googleapis.com/auth/cloud-platform
    
  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 Java debugger agent 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 Java debugger agent.

  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.

Send feedback about...

Stackdriver Debugger Documentation