为 Java 设置 Cloud Debugger

概览

本页面介绍如何配置您的环境和 Java 应用以使用 Cloud Debugger。对于一些环境,您必须明确指定访问权限范围,以让 Cloud Debugger 代理发送数据。我们建议尽可能设置最广泛的访问权限范围,然后使用 Identity and Access Management 来限制访问权限。为符合此最佳做法,请使用 cloud-platform 选项将访问权限范围设置为所有 Cloud API。

语言版本和计算环境

Cloud Debugger 适用于以下计算环境中的 Java 版本 7、8、9 和 11:

App Engine 标准环境 App Engine 柔性环境 Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos on Google Cloud 在其他位置运行的虚拟机和容器 云端函数

设置 Cloud Debugger

要设置 Cloud Debugger,请完成以下任务:

  1. 验证是否为您的项目启用了 Cloud Debugger API。

  2. 在您正在使用的计算环境中安装并配置 Debugger。

  3. 选择您的源代码。

验证 Cloud Debugger API 是否已启用

要开始使用 Cloud Debugger,请确保已启用 Cloud Debugger API。默认情况下,系统会为大多数项目启用 Cloud Debugger。
启用 Cloud Debugger API

Canary 快照和日志点

每次设置快照或日志点时,Java 版 Debugger 代理都可以使用 Canary 版快照和日志点。

Debugger 代理对快照和日志点执行 Canary 版,以防止大型作业在 Debugger 代理中出现可能会在应用快照或日志点时关闭整个作业的任何潜在错误。

为了缓解这种问题,Debugger 会在每次设置时对部分正在运行的实例上的快照和日志点执行 Canary 版。在 Debugger 验证快照或日志点不会对正在运行的实例产生不利影响后,Debugger 会将该快照或日志点应用于所有实例。

要了解如何在 Canary 模式下使用 Debugger,请转到调试快照页面和调试日志点页面。

启用 Canary 快照和日志点

安装最新版本的 Debugger 代理时,您可以选择启用或停用 Canary 版。Canary 版默认处于停用状态。

何时启用 Canary 快照和日志点

要保护部署和生产关键型工作负载,请在调试这些工作负载时启用 Canary 版。

如果您有一个实例,您仍然可以在启用 Canary 版的情况下进行调试,但单个实例无需对快照或日志点执行 Canary 版即可运行。

何时不应启用 Canary 快照和日志点

不要在执行时间小于 40 秒的工作负载(例如使用 Cloud Functions 的作业)上启用 Canary 版。

如果您需要更快的快照触发周期,请不要启用 Canary 版。

要将 Debugger 代理配置为不对快照和日志点执行 Canary 版,请转到适用于您在使用的 Google Cloud 平台的安装说明。

App Engine 标准环境

默认启用此调试程序,无需进行任何配置。Cloud Console 中的调试页面将尝试显示用于构建应用的 Java 源文件。

如需了解详情,请参阅自动选择源代码

App Engine 柔性环境

系统默认会启用适用于 Java 运行时的 Debugger,无需进行任何配置。Cloud Console 中的调试页面将尝试显示用于构建应用的 Java 源文件。

默认情况下,使用 Google 提供的 Java 基础映像的自定义运行时会包含 Debugger。如果使用默认入口点,则无需进行任何配置。Cloud Console 中的调试页面将尝试显示用于构建应用的 Java 源文件。

要将 Cloud Debugger 与使用其他基础映像构建的自定义运行时搭配使用,请按照 Compute Engine 的设置说明执行操作。

如需了解详情,请参阅自动选择源代码

Google Kubernetes Engine

GCLOUD

要使用 gcloud 启用 Debugger,请完成以下步骤:

  1. 创建集群,并为其指定以下访问权限范围之一:

    • https://www.googleapis.com/auth/cloud-platform 授予集群对所有 Google Cloud API 的访问权限。

    • https://www.googleapis.com/auth/cloud_debugger 仅授予集群对 Debugger API 的访问权限。使用此访问范围来强化集群的安全性

    gcloud container clusters create example-cluster-name \
           --scopes=https://www.googleapis.com/auth/cloud_debugger
    
  2. Dockerfile 中添加以下几行代码,以将 Debugger 代理添加到您的容器化应用中,并在部署应用时对该代理进行初始化。

    # 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
    

    要安装早期版本的代理,请将网址更改为以下值:

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

    VERSION_NUMBER 替换为要使用的代理版本,例如 https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz。Canary 版不适用于 2.25 之前的版本。要获取 Debugger 代理的版本,请转到 Java 代理的 GitHub 页面

  3. 将以下行添加到 Dockerfile 以运行 Debugger 代理:

    要在启用 Canary 版的情况下进行调试,请执行以下操作:

    # 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
    

    要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

    将命令中的占位符替换为以下内容:

    • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

    • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

    • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

您现在可以在部署容器化应用时使用 Debugger 了。

要让 Cloud Console 中的“调试”页面可以自动显示与所部署应用匹配的源代码,请参阅自动选择源代码

CONSOLE

如需使用 Google Cloud Console 启用 Debugger,请完成以下步骤:

  1. 节点池部分中,选择安全,然后选择针对每个 API 设置访问权限

  2. 启用 Debugger。

    为集群启用了 Debugger API。

  3. 选项:选择允许所有 Cloud API 的全面访问权限

  4. 将以下行添加到 Dockerfile 以运行 Debugger 代理:

    要在启用 Canary 版的情况下进行调试,请执行以下操作:

    # 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
    

    要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

    将命令中的占位符替换为以下内容:

    • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

    • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

    • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

您现在可以在部署容器化应用时使用 Debugger 了。

要让 Cloud Console 中的“调试”页面可以自动显示与所部署应用匹配的源代码,请参阅自动选择源代码

Compute Engine

您可以将 Cloud Debugger 与在 Google Compute Engine 实例上运行的任何 Java 应用结合使用。我们建议您对所有正在运行的应用实例启用 Debugger。

  1. 确保您的 Compute Engine 虚拟机实例正在运行:

    • 一个 64 位的 Debian Linux 映像
    • Java JDK 版本 7、8 或 9
  2. 确保使用访问权限范围选项允许所有 Cloud API 的全面访问权限创建 Compute Engine 虚拟机实例,或者您具有以下访问权限范围之一:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  3. 下载预构建的代理软件包:

    # 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
    

    要安装早期版本的代理,请将网址更改为以下值:

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

    VERSION_NUMBER 替换为要使用的代理版本,例如 https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz。Canary 版不适用于 2.25 之前的版本。要获取 Debugger 代理的版本,请转到 Java 代理的 GitHub 页面

  4. 将此代理添加到您的 Java 调用:
    (如果您使用的是 Tomcat 或 Jetty,请参阅 Web 服务器部分。)

    要在启用 Canary 版的情况下进行调试,请执行以下操作:

    # 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
    

    要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

    将命令中的占位符替换为以下内容:

    • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

    • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

    • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

现在,此调试程序便可与您的应用搭配使用。

要让 Cloud Console 中的“调试”页面可以自动显示与所部署应用匹配的源代码,请参阅自动选择源代码

Web 服务器

Java Web 服务器通常在引导过程中启动,并且每个 Web 服务器都有自己的 Java 选项自定义方法。

Tomcat

将此行内容添加到 /etc/default/tomcat7/etc/default/tomcat8

要在启用 Canary 版的情况下进行调试,请执行以下操作:

# 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"

要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

将命令中的占位符替换为以下内容:

  • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

  • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

  • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

如果在 Docker 容器中运行 Tomcat,请将此行内容添加到 Dockerfile

要在启用 Canary 版的情况下进行调试,请执行以下操作:

# 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

要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

将命令中的占位符替换为以下内容:

  • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

  • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

  • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

Jetty

将以下代码行添加到 /var/lib/jetty/start.d

要在启用 Canary 版的情况下进行调试,请执行以下操作:

--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

要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

将命令中的占位符替换为以下内容:

  • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

  • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

  • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

Cloud Run 和 Cloud Run for Anthos on Google Cloud

  1. Dockerfile 中添加以下命令以创建 Debugger 代理的安装目录,下载 Debugger 代理归档文件并将其解压到安装目录中:

    # 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
    

    要安装早期版本的代理,请将网址更改为以下值:

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

    VERSION_NUMBER 替换为要使用的代理版本,例如 https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz。Canary 版不适用于 2.25 之前的版本。要获取 Debugger 代理的版本,请转到 Java 代理的 GitHub 页面

    找到 Java 调用并添加以下标志以初始化 Debugger 代理:

    要在启用 Canary 版的情况下进行调试,请执行以下操作:

    # 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
    

    要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

    将命令中的占位符替换为以下内容:

    • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

调试页面上,选择源代码的位置。要让 Cloud Console 中的调试页面可以自动显示与所部署应用匹配的源代码,请参阅自动选择源代码

Debugger 现在可以使用了。

本地和其他位置

  1. 下载此调试程序的预构建代理软件包:

    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. 下载服务帐号凭据。
    要在非 Google Cloud 托管的计算机上使用 Java 版 Cloud Debugger 代理,代理必须使用 Google Cloud 服务帐号凭据对 Cloud Debugger 服务进行身份验证。

    使用 Cloud Console 的“服务帐号”页面为现有或新的服务帐号创建凭据文件。该服务帐号必须至少具有 Cloud Debugger Agent 角色。

    将服务帐号 JSON 文件与适用于 Java 的 Cloud Debugger 代理置于同一目录下。

  3. 将此代理添加到您的 Java 调用:

    要在启用 Canary 版的情况下进行调试,请执行以下操作:

    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
    

    要在未启用 Canary 版的情况下进行调试,请将 enable_canary 标志设置为 false

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

    将命令中的占位符替换为以下内容:

    • PATH_TO_JAR_FILE 是应用的 JAR 文件的相对路径。例如:~/myapp.jar

    • MODULE 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

    • VERSION 是应用版本(例如构建版本 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

    • 可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量,而无需添加 auth.serviceaccount.jsonfile 系统属性。

现在,此调试程序便可与您的应用搭配使用。

Cloud Console 中的“调试”页面可以显示本地源文件(无需上传),以进行本地开发。请参阅手动选择源代码