调试快照

部署或启动应用后,您可以在 Google Cloud Console 中打开 Cloud Debugger。Debugger 允许您捕获和检查应用中的调用堆栈和局部变量,既不需要停止应用,也不会导致应用变慢。

访问 Cloud Console 的调试页面以使用 Debugger。

准备工作

无论 Debugger 是否可以访问应用的源代码,都可以使用 Debugger。如果您的源代码不可用,请参阅下面的截取调试快照,了解有关手动输入文件名和行号的说明。

要访问存储在本地或 Git 代码库中的源代码,您可能需要选择源代码位置

快照

快照捕获应用源代码中特定行位置的局部变量和调用堆栈。您可以指定特定条件和位置以返回应用数据的快照,并详细查看以调试您的应用。

Canary 版的 Debugger 代理

设置快照后,Debugger 代理会在部分实例上测试快照。在 Debugger 代理验证快照可以成功执行后,会将快照应用于您的所有实例。此过程大约需要 40 秒。

此过程完成后,触发快照时,结果将显示在变量调用堆栈窗格中。如果在设置快照后的 40 秒内触发快照,您将看到已应用 Canary 版快照的实例的结果。

Debugger 代理实施了几种策略,用于最小化捕捉数据时产生的延迟时间。

在 Debugger 代理执行 Canary 版时,您会看到以下内容:

Debugger 代理是 Canary 版实例

要了解在 Canary 模式下 Debugger 代理失败时要执行的操作,请转到“调试快照”页面上的“问题排查”部分

要了解哪些 Debugger 代理版本具有 Canary 版功能,请参阅特定于语言的页面。

非 Canary 版的 Debugger 代理

使用非 Canary 版 Debugger 代理并设置快照时,它适用于所有正在运行的应用实例。任何实例首次在快照位置执行代码时,Debugger 代理都会截取快照并使其可供查看。Debugger 代理实施了几种策略,用于最小化捕捉数据时产生的延迟时间。

截取调试快照

Console

点击源代码行号以在该位置截取快照。

  1. 确保在右侧面板中选择了快照面板。
  2. 在左侧面板中,选择包含要监视的源代码的文件。所选文件的内容会显示在中央面板中。
  3. 点击源代码位置的行号。

浏览到快照位置

您可以点击多行以在文件上设置多个快照位置。

如需了解在 Debugger 中加载源代码的其他方法,请参阅源代码选项部分。

如果没有源代码可用,您可以在快照面板中手动输入文件名:行以截取快照:

手动设置快照位置

gcloud

要从命令行设置快照位置:

gcloud debug snapshots create LOCATION

其中:

  • LOCATION 是设置快照的文件名和行。格式为 FILE:LINE,其中 FILE 可以是文件名或前面有足够路径组件的文件名,以区别于其他名称相同的文件。请务必提供在调试目标中唯一的文件名。

快照条件(可选)

快照条件是应用语言(支持 Java、Python 和 Go)中的简单表达式,此表达式的值必须为 true 才能生成快照。每次执行该行时,实例都会计算快照条件,直到条件计算结果为 true 或快照超时为止。

快照条件的使用是可选的。

快照条件是一个完整的布尔表达式,可以包含逻辑运算符:

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

Console

要指定条件,在快照面板的条件字段中输入条件。

设置快照条件

gcloud

使用 snapshots create--condition 标志指定条件:

gcloud debug snapshots create LOCATION --condition="ultimateAnswer <= 42 && foo==bar"

您可以使用以下语言功能来表达条件:

Java

支持大多数 Java 表达式,包括:
  • 本地变量:a == 8
  • 数值和布尔运算:x + y < 20
  • 实例和静态字段:this.counter == 20this.myObj.isShutdownmyStaticcom.mycompany.MyClass.staticMember
  • 字符串与等式运算符的比较:myString == "abc"
  • 函数调用。只能使用只读函数。例如,支持 StringBuilder.indexOf(),但不支持 StringBuilder.append()
  • 类型转换,具有完全限定类型:((com.myprod.ClassImpl) myInterface).internalField

支持以下语言功能:

  • 取消装箱数值类型,例如 Integer;改用 myInteger.value

Python

支持大多数 Python 表达式,包括:
  • 读取局部变量和全局变量。
  • 从数组、列表、切片、字典和对象中读取。
  • 调用简单的方法。

不支持以下语言功能:

  • 调用分配新对象或使用复杂构造的函数。
  • 在表达式中创建新对象。

Go

支持大多数 Go 表达式语法,包括:
  • 读取局部变量和全局变量。
  • 从数组、切片、映射和结构体中读取。

不支持以下语言功能:

  • 从接口值读取。
  • 类型转换和复合文字。
  • len 之外的函数调用。

表达式(可选)

Debugger 的表达式功能允许您在截取快照时计算复杂表达式或遍历对象层次结构。表达式支持与上述快照条件相同的语言功能。

表达式的使用是可选的。

表达式的典型用法是:

  • 查看不属于局部变量集的静态或全局变量。
  • 轻松查看深层嵌套的成员变量,而不必每次都在 Debugger 面板中展开局部变量。
  • 避免重复的数学计算。例如,使用 (endTimeMillis - startTimeMillis) / 1000.0 计算持续时间(以秒为单位)。

要添加表达式:

Console

  1. 表达式字段中输入表达式。按 Tab 键添加其他表达式。
  2. 按 Enter 键或快照按钮 快照按钮

截取快照时会显示表达式的结果。

设置表达式

gcloud

使用 snapshots create--expression 标志定义表达式:

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

查看快照

Console

当应用在您指定的位置执行源代码时,快照数据会显示在 Debugger 中。实例变量和局部变量显示在面板的变量部分中。堆栈轨迹显示在面板的调用堆栈部分中。

查看快照

您可以在截取快照时检查局部变量的值,并深入研究更深层次的数据结构。您还可以点击任何调用堆栈帧,并检查堆栈中该级别的局部变量。

如果您在文件上设置了多个快照位置,或者要查看已经截取的快照,请展开快照历史记录面板:

gcloud

要从命令行检索快照的 Cloud Console 网址:

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE  HighScoreService.java:105                             53bd97d4-b6c6-74fc  https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

复制 VIEW 列的值并粘贴到浏览器中,即可在 Cloud Console 中查看快照。

要从命令行查看详细的快照数据:

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

describe 命令返回堆栈轨迹和局部变量值,它主要是机器可读的,而不是人类可读的。

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

重新截取快照

快照只截取一次。如果要在同一位置截取应用数据的另一个快照,可以手动重新截取快照。

Console

要重新截取快照,请点击快照面板右上角的相机图标:

快照按钮

新快照将添加到快照历史记录面板中。可以从快照历史记录或该行号上的标记访问该行的过去快照:

以前快照显示在行标记上

gcloud

要从命令行重新截取快照,请重复最初使用的 create 命令:

gcloud debug snapshots create LOCATION

移除快照位置

Console

通过点击快照标记中的 X 来移除快照位置。

快照图标

gcloud

要从命令行删除快照,请执行以下操作:

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

其中:

共享快照

要与其他项目成员共享快照,您可以从浏览器或从 gcloud debug snapshots list 命令的输出复制快照网址并将其提供给其他有权访问项目的用户。您也可以保存此网址以供日后参考,并再次返回以查看其结果。Debugger 为每个截取的快照使用一个新网址。这允许您共享不同的结果集,即使它们是在代码的同一位置截取的。截取快照 30 天后,共享将过期。

问题排查

Debugger 代理是否促使我的实例崩溃?

如果 Debugger 代理出现故障,您可能会看到以下错误:

“变量”窗格显示错误消息

如果 Debugger 代理因以下原因触发了其保护措施,您可能会收到假正例:

  • Debugger 代理在执行 Canary 版时关闭实例。

    关闭应用了 Canary 版快照的实例时,Debugger 代理似乎终止了该实例。验证创建快照后的 40 秒内未关闭任何实例。例如,从 Cloud Run 和 App Engine 自动扩缩或部署新代码可能会导致关闭实例。

您应该从实例中移除 Debugger 代理并重新安装以前的版本。要重新安装旧版本,请按照安装旧版 Debugger 代理的安装说明执行操作。

如果问题在旧版代理中仍存在,请验证它不是假正例,然后停用 Debugger 代理并发送反馈。