为 Python 设置 Cloud Debugger

概览

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

语言版本和计算环境

Cloud Debugger 适用于以下计算环境中的 Python 3:

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

每次设置快照或日志点时,Python 版 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 标准环境

Python 3.7 或 Python 3.8

如果您使用的是 Python 3.7 或 Python 3.8,则必须执行以下步骤来手动启用 Debugger 代理:

  1. 请确保您的 app.yaml 文件包含以下代码行:

    runtime: python37
    or
    runtime: python38
    
  2. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架(仅限版本 1.*),则在 manage.py 中添加以下代码行。

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

     breakpoint_enable_canary=False
    
  3. google-python-cloud-debugger 添加到 requirements.txt

  4. 要让 Cloud Console 中的调试页面可以自动显示与已部署应用匹配的源代码,请转到自动选择源代码

现在,Debugger 便可与您的应用搭配使用。

App Engine 柔性环境

您可以将 Debugger 与 App Engine Python 运行时或自定义运行时搭配使用。

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

    • 一个 64 位的 Debian Linux 映像
    • Python 3
  2. 请确保您的 app.yaml 文件包含以下代码行:

    runtime: python
    env: flex
    

    如果您使用的是自定义运行时,请使用 runtime: custom

  3. google-python-cloud-debugger 添加到 requirements.txt

  4. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架(仅限版本 1.*),则在 manage.py 中添加以下代码行。

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

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

现在,Debugger 便可与您的应用搭配使用。

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. 将 Debugger 软件包添加到您的应用中:

    如果您使用的是 requirements.txt 文件,请添加以下行:

      google-python-cloud-debugger
    

    如果您使用的是 Dockerfile,请添加以下行:

      RUN pip install google-python-cloud-debugger
    
  3. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架,则在 manage.py 中添加以下代码行:

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

      try:
        import googleclouddebugger
        googleclouddebugger.enable(
          breakpoint_enable_canary=True
        )
      except ImportError:
        pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

      breakpoint_enable_canary=False
    

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

Debugger 现在可以使用了。

控制台

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

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

    显示以红色矩形框住“更多选项”按钮的节点池字段。

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

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

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

  3. 将 Debugger 软件包添加到您的应用中:

    如果您使用的是 requirements.txt 文件,请添加以下行:

    google-python-cloud-debugger
    

    如果您使用的是 Dockerfile,请添加以下行:

    RUN pip install google-python-cloud-debugger
    
  4. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架,则在 manage.py 中添加以下代码行:

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

    breakpoint_enable_canary=False
    

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

Debugger 现在可以使用了。

Compute Engine

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

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

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  3. 下载 Debugger 代理。

    安装 Python Debugger 的最简单方法是使用 [pip][pip]:

    pip install google-python-cloud-debugger
    
  4. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架,则在 manage.py 中添加以下代码行。

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        module='[MODULE]',
        version='[VERSION]'
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

    breakpoint_enable_canary=False
    

    如果您无法更改代码,请将 Debugger 代理作为模块运行:

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

    python -m googleclouddebugger \
          --module=[MODULE] \
          --version=[VERSION] \
          --breakpoint_enable_canary=True
          -- \
          myapp.py
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

    breakpoint_enable_canary=False
    

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

    • [MODULE] 是应用的名称。
      它与版本一起用于在 Cloud Console 的调用页面中标识调试目标。
      示例:MyAppBackendFrontend
    • [VERSION] 是应用版本(如版本 ID)。
      Cloud Console 的调试页面将运行版本显示为 [MODULE] - [VERSION]
      示例值:v1.0build_147v20170714

现在,Debugger 便可与您的应用搭配使用。

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

Cloud Run 和 Cloud Run for Anthos on Google Cloud

  1. Python 软件包。

    如果您使用的是 requirements.txt 文件,请添加以下行:

    google-python-cloud-debugger
    

    否则,请将以下行添加到 Dockerfile 中:

    RUN pip install google-python-cloud-debugger
    
  2. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架,则在 manage.py 中添加以下代码行:

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    
    except ImportError:
      pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

    breakpoint_enable_canary=False
    

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

Debugger 现在可以使用了。

本地和其他位置

  1. 确保您的工作站正在运行:

    • 一个 64 位的 Debian Linux 映像
    • Python 3
  2. 下载 Debugger 代理。

    安装 Python Debugger 的最简单方法是使用 [pip][pip]{: .external}:

    pip install google-python-cloud-debugger
    
  3. 下载服务帐号凭据。

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

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

    将服务帐号 JSON 文件与 Python 版 Cloud Debugger 代理置于同一目录下。

  4. 在您的初始化代码中尽早添加以下代码行,例如在 main 函数中,或者,如果使用了 Django Web 框架,则在 manage.py 中添加以下代码行。

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
          module='[MODULE]',
          version='[VERSION]',
          breakpoint_enable_canary=True
          service_account_json_file='/opt/cdbg/gcp-svc.json')
    except ImportError:
      pass
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

    breakpoint_enable_canary=False
    

    如果您无法更改代码,请将 Debugger 代理作为模块运行:

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

    python \
        -m googleclouddebugger \
        --module=[MODULE] \
        --version=[VERSION] \
        --breakpoint_enable_canary=True
        --service_account_json_file=/opt/cdbg/gcp-svc.json \
        -- \
        myapp.py
    

    要在未启用 Canary 版的情况下进行调试,请将 breakpoint_enable_canary 参数设置为 False

    breakpoint_enable_canary=False
    

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

    • [MODULE] 是应用的名称。
      它与版本一起用于在 Cloud Console 的调用页面中标识调试目标。
      示例:MyAppBackendFrontend
    • [VERSION] 是应用版本(如版本 ID)。
      Cloud Console 的调试页面将运行版本显示为 [MODULE] - [VERSION]
      示例值:v1.0build_147v20170714
    • 可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量,而无需指定 service_account_json_file

现在,Debugger 便可与您的应用搭配使用。

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