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.

Before you begin

To begin using Debugger, ensure the Debugger API is enabled.
Enable Debugger API

App Engine standard environment

The debugger is enabled by default; no configuration is required. The Debug page in the Cloud 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 Cloud 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 Cloud 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

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
    
  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
    
    # 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 \
        -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 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:

    Node pool field showing red rectangle over the more options button.

  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.

Compute Engine

You can use Stackdriver 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:

    sudo mkdir /opt/cdbg
    wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
        sudo 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 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:

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

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:

    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
    

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

    RUN  java -agentpath:/opt/cdbg/cdbg_java_agent.so \
        -jar PATH_TO_JAR_FILE
    

    Where:

    • PATH_TO_JAR_FILE is the relative path to the app's JAR file. For example: ~/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 Stackdriver Debugger agent for Java on machines not hosted by Google Cloud, the agent must use Google Cloud service-account credentials to authenticate with the Stackdriver 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 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 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.

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.

หน้านี้มีประโยชน์ไหม โปรดแสดงความคิดเห็น

ส่งความคิดเห็นเกี่ยวกับ...