为 Go 设置 Cloud Debugger

概览

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

语言版本和计算环境

Cloud Debugger 适用于以下计算环境中的 Go 1.9 和更低版本：

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

设置 Cloud Debugger

要设置 Cloud Debugger，请完成以下任务：

验证是否为您的项目启用了 Cloud Debugger API。
在您正在使用的计算环境中安装并配置 Debugger。
选择您的源代码。

验证 Cloud Debugger API 是否已启用

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

Google Kubernetes Engine

GCLOUD

要使用 gcloud 启用 Debugger，请完成以下步骤：

创建集群，并为其指定以下访问权限范围之一：
- 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
```
注意：集群的访问权限范围一经创建便无法更改。
在 Dockerfile 中添加以下几行代码，以将 Debugger 代理添加到您的容器化应用中：
```
RUN go get cloud.google.com/go/cmd/go-cloud-debug-agent \
    go-cloud-debug-agent -sourcecontext=[PATH_TO_FILE] -appmodule=[APP_NAME] \
    -appversion=[APP_VERSION] -- [PATH_TO_BINARY] [ARG1] [ARG2]
```
警告：编译 go-cloud-debug-agent 时所用的 Go 版本必须与在调试二进制文件时使用的 Go 版本相同或高于此版本。

其中：
- PATH_TO_FILE 指定包含源上下文配置的 JSON 格式文件的相对路径。
- APP_NAME 是应用或服务的名称。它与版本一起用于在 Google Cloud Console 中标识您的应用。
- APP_VERSION 是应用提供的版本标记。例如，您可以使用版本号。Google Cloud Console 将运行版本显示为 module - version。例如 main - 1.0。
- PATH_TO_BINARY 指定应用二进制文件的相对路径。
- ARG1 和 ARG2 是应用所需的任何其他参数的占位符。
注意：$GOPATH/bin 必须在您的 PATH 上。否则，您必须使用 go-cloud-debug-agent 二进制文件的绝对路径。

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

如需详细了解如何创建集群，请参阅创建集群。

控制台

如需使用 Google Cloud 控制台启用 Debugger，请完成以下步骤：

在节点池部分中，选择安全，然后选择针对每个 API 设置访问权限。
启用 Debugger。
选项：选择允许所有 Cloud API 的全面访问权限。

Compute Engine

确保您的 Compute Engine 虚拟机实例运行的是 64 位 Debian Linux 映像。
确保使用访问权限范围选项允许所有 Cloud API 的全面访问权限创建 Compute Engine 虚拟机实例，或者您具有以下访问权限范围之一：
- https://www.googleapis.com/auth/cloud-platform
- https://www.googleapis.com/auth/cloud_debugger
当前 Go 编译器的优化会干扰准确的调试。因此，当使用默认的 Go 编译器优化构建应用时，Cloud Debugger 会显示有关此应用的错误信息。

要获取正确的调试信息，请在不使用默认优化的情况下构建应用。以下示例命令演示了在使用 go1.10 或更高版本时如何停用优化：
```
go build -gcflags=all='-N -l'
```
前面的 gcflags 值包含 -N 来停用优化，并包含 -l 来停用内嵌。
下载 Debugger 代理。

Cloud Debugger 代理是一个轻量级二进制文件，您可以在启动应用时启用它。代理与您的应用一起启动，并在应用运行时与 Cloud Debugger 后端进行通信。

构建并部署了 Compute Engine 应用后，下载并安装调试代理：
```
go get cloud.google.com/go/cmd/go-cloud-debug-agent
```
警告：必须使用与要调试的二进制文件相同的 Go 版本编译 go-cloud-debug-agent。
启动此代理和您的程序：
```
go-cloud-debug-agent -sourcecontext=[PATH_TO_FILE] -appmodule=[APP_NAME] \
                 -appversion=[APP_VERSION] -- [PATH_TO_BINARY] [ARG1] [ARG2]
```
注意：$GOPATH/bin 必须在您的 PATH 上。否则，您必须使用 go-cloud-debug-agent 二进制文件的绝对路径。

其中：
- PATH_TO_FILE 指定包含源上下文配置的 JSON 格式文件的相对路径。
- APP_NAME 是应用或服务的名称。它与版本一起用于在 Google Cloud Console 中标识您的应用。
- APP_VERSION 是应用提供的版本标记。例如，您可以使用版本号。Google Cloud Console 将运行版本显示为 module - version。例如 main - 1.0。
- PATH_TO_BINARY 指定应用二进制文件的相对路径。
- ARG1 和 ARG2 是应用所需的任何其他参数的占位符。
例如：
```
go-cloud-debug-agent -appmodule=main -appversion=1.0 -- bin/my-app my-arg
```

Debugger 现可用于您的应用。

本地和其他位置

使用 Go 1.9 及更早版本的本地环境或其他环境支持适用于 Go 的 Cloud Debugger 代理。