为 Node.js 设置 Cloud Debugger

概览

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

语言版本和计算环境

Cloud Debugger 适用于以下计算环境中的 Node.js 6 和更高版本:

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 快照和日志点

每次设置快照或日志点时,Node.js 版 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

  1. 使用 npm 安装软件包:

    npm install --save @google-cloud/debug-agent
    
  2. 在应用的主要脚本或入口点的顶部启用代理(但如果您也在使用 @google/cloud-trace,则必须在它之后启用代理):

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
    

Debugger 现可用于您的应用。

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

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 代理:

    RUN  npm install --save @google-cloud/debug-agent
    
  3. 在应用的主要脚本或入口点的顶部启用代理(但如果您也在使用 @google/cloud-trace,则必须在它之后启用代理):

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    其中:

    • SERVICE 是应用的名称,例如 MyAppBackendFrontend
    • VERSION 是版本,例如 v1.0build_147v20170714

    我们建议您在环境变量中设置这些变量,这样就无需在每次部署时更改源代码。

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

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

控制台

要使用控制台启用 Debugger,请完成以下步骤:

  1. 选择集群类型后,点击节点池窗格中的更多选项

    节点池选项

  2. 安全性窗格中选择下列其中一项:

    • 允许所有 Cloud API 的全面访问权限

    • 允许每个 API 的访问权限,然后针对 Cloud Debugger 选择已启用

  3. 将下面一行代码添加到 Dockerfile 以添加 Debugger 代理:

        RUN  npm install --save @google-cloud/debug-agent
    
  4. 在应用的主要脚本或入口点的顶部启用代理(但如果您也在使用 @google/cloud-trace,则必须在它之后启用代理):

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    其中:

    • SERVICE 是应用的名称,例如 MyAppBackendFrontend
    • VERSION 是版本,例如 v1.0build_147v20170714

    我们建议您在环境变量中设置这些变量,这样就无需在每次部署时更改源代码。

Compute Engine

  1. 确保使用访问权限范围选项允许所有 Cloud API 的全面访问权限创建 Compute Engine 实例,或者您具有以下访问权限范围之一:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  2. 使用 npm 安装软件包:

    npm install --save @google-cloud/debug-agent
    
  3. 在应用的主要脚本或入口点的顶部启用代理(但如果您也在使用 @google/cloud-trace,则必须在它之后启用代理):

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    其中:

    • SERVICE 是应用的名称,例如 MyAppBackendFrontend
    • VERSION 是版本,例如 v1.0build_147v20170714

    我们建议您在环境变量中设置这些变量,这样就无需在每次部署时更改源代码。

Debugger 现可用于您的应用。

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

Cloud Run 和 Cloud Run for Anthos on Google Cloud

  1. 使用 npm 安装软件包:

    npm install --save @google-cloud/debug-agent
    
  2. 在应用的主要脚本或入口点的顶部启用代理(但如果您也在使用 @google/cloud-trace,则必须在它之后启用代理):

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

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

    enableCanary: false
    

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

本地和其他位置

  1. 使用 npm 安装软件包:

    npm install --save @google-cloud/debug-agent
    
  2. 下载服务帐号凭据。

    要在非 Google Cloud 托管的计算机上使用 Node.js 版 Cloud Debugger 代理,代理必须使用 Google Cloud 服务帐号凭据对 Cloud Debugger 服务进行身份验证。

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

  3. 使用下载的凭据配置和启用代理:

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

    require('@google-cloud/debug-agent').start({
      projectId: 'your-project-id',
      keyFilename: '/path/to/key.json',
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    其中:

    • SERVICE 是应用的名称,例如 MyAppBackendFrontend
    • VERSION 是版本,例如 v1.0build_147v20170714

    我们建议您在环境变量中设置这些变量,这样就无需在每次部署时更改源代码。

Debugger 现可用于您的应用。

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