调试日志点

部署或启动应用后,您可以在 Google Cloud Console 中打开 Cloud Debugger。Cloud Debugger 让您可将日志记录注入正在运行的服务,而无需重启服务或干扰服务的正常功能。这对于调试正式版问题非常有用,无需添加日志语句并重新部署。

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

准备工作

在可访问或不可访问应用的源代码的情况下均可使用 Cloud Debugger。如果无法访问源代码,请参阅下面的添加调试日志点,以获取有关手动输入文件名和行号的说明。

如果您的源代码存储在 Google Cloud 软件库中,则会在“调试”视图中自动显示源代码。

要访问存储在其他位置(例如本地或 git 代码库中)的源代码,您可能需要选择源代码位置

日志点

日志点可让您将日志记录注入正在运行的服务,而无需重启服务或干扰服务的正常功能。每次当实例在日志点位置执行代码时,Cloud Debugger 都会记录一条消息,并将输出发送至目标环境的相应日志。例如,在 App Engine 上,会将输出发送至 Cloud Logging 中的请求日志。

日志点在创建后的 24 小时内保持活动状态,或者直到它们被删除或重新部署服务。

Canary 版的 Debugger 代理

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

此过程完成后,触发日志点时,Debugger 代理会记录消息。如果在设置后 40 秒内触发日志点,Debugger 代理会记录来自已应用 Canary 版日志点的实例的消息。

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

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

Debugger 代理是 Canary 版实例

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

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

非 Canary 版的 Debugger 代理

使用非 Canary 版 Debugger 代理并设置日志点时,它适用于所有正在运行的应用实例。当任意实例第一次在日志点位置执行代码时,Debugger 代理会记录消息。Debugger 代理实施了几种策略,用于最小化捕捉数据时产生的延迟时间。

添加调试日志点

Console

要从 Cloud Console 添加日志点,请执行以下操作:

  1. 确保在右侧面板中选择了日志点标签页。
  2. 在左侧面板中,选择包含要添加日志点的源代码的文件。该文件的内容将显示在中央面板中。
  3. 点击该位置的行号以添加日志点。
  4. logpoint("") 字段之中填写消息,然后点击“添加”按钮。可以将表达式放在大括号中(例如 {newScore.score})来记录其值。

以内嵌方式添加日志点


如果没有源代码可用,您可以在日志点面板中手动输入“文件名:行”和其他详细信息:手动添加日志点

gcloud

要从命令行添加日志点,请运行以下命令:

gcloud debug logpoints create LOCATION MESSAGE

其中:

  • LOCATION 是设置日志点的文件名和行。格式为 FILE:LINE,其中 FILE 可以是文件名或前面有足够路径组成部分的文件名,以区别于其他名称相同的文件。请务必提供在调试目标中唯一的文件名。
  • MESSAGE 是您要记录的消息。

以下示例在 info 日志级别(这是日志点的默认日志级别)记录 score 的值:

gcloud debug logpoints create HighScoreService.java:105 \
  "User {name} scored {newScore.score}"

执行 HighScoreService.java executes 的第 105 行时,会将记录了变量 namenewScore.score 的值的消息插入到输出字符串中。

日志点消息格式

日志点消息确定输出中记录的内容。表达式允许您计算和记录感兴趣的值。大括号中消息(例如 {myObj.myFunc()}{a + b})的任何内容都将被替换为输出中该表达式的值。上述示例中的消息 User {name} scored {newScore.score} 将记录与 User user1 scored 99 类似的输出。

您可以使用以下语言的表达式:

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 之外的函数调用。

日志点条件

日志点条件是应用语言中的一个简单表达式,只有此条件求得的值为 true 时才能记录日志点。每次执行该行时,实例都会计算日志点条件,直到日志点到期或被删除为止。

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

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

表达式支持的语言功能适用于日志点条件。

Console

在“if”语句中输入条件:

以内嵌方式设置条件

如果没有源代码可用,可以在日志点面板中指定条件。

gcloud

使用 logpoints create--condition 标志表示条件:

gcloud debug logpoints create HighScoreService.java:105 
--condition="newScore.score > 40"
--log-level="warning"
"Suspiciously high score ({newScore.score}) from user {name}"

在上面的示例中,执行应用的第 105 行时,日志点会检查 newScore.score 的值。如果该值大于 40,则会在日志中添加一条警告消息。

查看输出

日志点输出将被发送至目标环境的相应日志。

App Engine

在 App Engine 应用上设置的日志点会将其输出发送至 Cloud Logging 中的请求日志

您可以在日志面板或专用的日志查看器中查看日志。

日志面板中的日志点

Compute Engine

在 Compute Engine 应用上设置的日志点会将其输出发送至与常规日志语句相同的位置。例如,在 Python 中,默认的日志记录模块将其输出发送至 stdout,但也可以将其配置为写入特定文件。

您可以设置 Logging 代理以将这些日志转发至 Cloud Logging。之后,您可以在日志查看器中查看日志。

删除日志点

24 小时后,日志点会变为非活动状态并停止记录消息,并在 30 天后自动删除。您可以手动删除日志点,这样做将停止日志记录并将日志点从历史记录中移除以供日后参考。但请注意,删除日志点不会删除已生成的日志消息。

Console

要手动删除日志点,请使用日志点历史记录面板中的溢出菜单。

删除日志点

gcloud

要手动删除日志点,您可以通过 ID 或在代码位置使用正则表达式来指定日志点:

gcloud debug logpoints delete HighScoreService.java:105

Debug target not specified. Using default target: default-1
This command will delete the following logpoints:

LOCATION                   CONDITION            LOG_LEVEL  LOG_MESSAGE_FORMAT                                             ID
HighScoreService.java:105                       INFO       User {name} scored {newScore.score}.                           53aaa3bd8d2d7-b76f-feb5d
HighScoreService.java:105  newScore.score > 40  WARNING    Suspiciously high score ({newScore.score}) from user {name}  53aaa3bsdffd7-b56f-fasfg

Do you want to continue (Y/n)?  Y
Deleted 2 logpoints.