'快照调试器CLI工具。
项目描述
快照调试器
快照调试器允许您在任何代码位置检查正在运行云应用程序的状态，而无需停止或减慢它的速度。它不是传统的进程调试器，而是一个始终在线的整个应用程序调试器，可以从应用程序的任何实例中获取快照。
您可以使用快照调试器与您的应用程序的任何部署一起使用，包括测试、开发和生产。当捕获应用程序状态时，调试器通常只会将少于10毫秒的延迟添加到请求延迟。在大多数情况下，用户不会注意到这一点。
项目状态：已归档
此项目已被归档且不再受支持。将不再进行错误修复或安全补丁。如果用户想继续维护，可以分叉存储库。
此开源解决方案是Cloud Debugger的替代品。Cloud Debugger于2022年5月16日弃用，并于2023年5月31日停止服务
限制
- 不支持Python 2.7
CLI命令参考
安装快照调试器CLI
在您的本地环境或Cloud Shell的$HOME目录中安装调试器CLI。有关使用Cloud Shell的信息，请参阅使用Cloud Shell。
python3 -m pip install snapshot-dbg-cli
注意：在Cloud Shell中使用快照调试器时，您将需要使用您的账户凭据进行授权。
运行快照调试器CLI
完成pip安装后，有两种运行CLI的方式。
选项1：使用已安装的脚本
作为pip安装过程的一部分，将安装一个名为snapshot-dbg-cli的脚本，可用于运行CLI。
运行list_debuggees命令的示例
snapshot-dbg-cli list_debuggees
注意：要从任何目录以这种方式运行脚本，您必须确保脚本的安装目录在您的PATH中。如果安装位置不在PATH中，Pip将发出警告，并提供在这种情况下，您可以将它添加到PATH中的安装位置。
选项2：直接运行包
运行list_debuggees命令的示例
python3 -m snapshot_dbg_cli list_debuggees
开始之前
确保您具有适当的权限
要完成设置，您需要在您的Google Cloud项目中具有以下权限。如果您是Owner或Editor，则您具有这些权限。
- firebase.projects.create
- firebase.projects.update,
- firebasedatabase.instances.create
- firebasedatabase.instances.get
- resourcemanager.projects.get
- serviceusage.services.enable
- serviceusage.services.get
有关Google项目中权限和角色的更多信息，请阅读理解角色
在Cloud Shell中使用快照调试器
快照调试器需要Python 3.6或更高版本和gcloud CLI。如果您在Cloud Shell中工作，您已经安装了Python和gcloud。
此外，环境应该默认正确配置。您可以通过运行以下命令来验证此
gcloud config get-value projectgcloud config get-value account
注意：当运行cli时，您可能会遇到一个弹出警告，提示
gcloud正在请求您的凭据以进行GCP API调用。您需要单击AUTHORIZE才能继续。
在Cloud Shell之外使用快照调试器
确保您已安装Python 3.6或更高版本
快照调试器CLI需要Python 3.6或更高版本。
安装Google Cloud gcloud CLI
快照调试器CLI依赖于gcloud CLI。要安装gcloud CLI，请遵循以下说明。如果您已经安装了gcloud CLI，请运行gcloud components update以将所有已安装组件更新到最新版本。
设置环境
- 运行
gcloud auth login，请确保使用具有对您正在工作的Google Cloud项目权限的账户。 - 运行
gcloud config set project PROJECT_ID。其中，PROJECT_ID 是您想要使用的项目。Snapshot Debugger CLI 始终作用于当前配置的gcloud项目。
为您的 Google Cloud 项目启用 Firebase
Snapshot Debugger CLI 和代理使用 Firebase 实时数据库 (RTDB) 进行通信。
如果您已经在项目中使用了 Firebase，请跳转到设置 Firebase RTDB部分。
-
将 Firebase 添加到您的项目中
https://console.firebase.google.com/?dlAction=MigrateCloudProject&cloudProjectNumber=PROJECT_ID
其中，PROJECT_ID 是您的项目 ID
-
选择您的项目 ID并点击继续。如果您的项目中已启用计费，则会选择按量付费的 Blaze 计划，否则将选择免费的 Spark 计划。如果您已启用计费并希望使用免费 Spark 计划，请设置一个未启用计费的新项目。
注意：Snapshot Debugger 使用 Firebase RTDB 服务。大多数用户的用量都足够低，可以保持在免费使用限制之下。
-
如果您正在使用按量付费的 Blaze 计划，请点击确认计划。如果您使用的是免费 Spark 计划，则不会提示您确认。
-
阅读 添加 Firebase 到 Google Cloud 项目时需要注意的几点下的信息，然后点击继续。
-
切换启用分析选项以启用或禁用 Firebase 的 Google Analytics。Google Analytics 不是调试器使用所必需的。
-
点击继续。
-
点击开始使用。
-
点击您的项目。
设置 Firebase RTDB
具体步骤取决于您是否在 Spark 或 Blaze 计费计划下。根据您的计划，遵循以下部分中的步骤。
您可以在 Firebase 使用情况与计费页面上检查项目的计费计划
https://console.firebase.google.com/project/PROJECT_ID/usage/details
其中，PROJECT_ID 是您的项目 ID
Blaze 计划 RTDB 设置
这将指示调试器 CLI 创建并使用名为 PROJECT_ID-cdbg 的数据库。
- 运行
snapshot-dbg-cli init。 - 输出类似于以下内容
Project 'test-proj' is successfully configured with the Firebase Realtime
Database for use by Snapshot Debugger.
The full database information is below. If you have specified a custom database
ID the url below is the one you'll need to specify when using the other cli
commands.
name: projects/23498723497/locations/us-central1/instances/test-proj-cdbg
project: projects/23498723497
database url: https://test-proj-cdbg.firebaseio.com
type: USER_DATABASE
state: ACTIVE
注意：init 命令打印的信息可以从您的 Firebase 项目中访问。您可以多次运行 snapshot-dbg-cli init 命令来查看此信息。
Spark 计划 RTDB 设置
这将指示 CLI 创建并使用名为 PROJECT_ID-default-rtdb 的数据库。如果它当前不存在，则会创建。
- 运行
snapshot-dbg-cli init --use-default-rtdb - 输出类似于以下内容
Project 'test-proj' is successfully configured with the Firebase Realtime
Database for use by Snapshot Debugger.
The full database information is below. If you have specified a custom database
ID the url below is the one you'll need to specify when using the other cli
commands.
name: projects/23498723497/locations/us-central1/instances/default
project: projects/23498723497
database url: https://test-proj-default-rtdb.firebaseio.com
type: USER_DATABASE
state: ACTIVE
注意：init 命令打印的信息可以从您的 Firebase 项目中访问。您可以多次运行 snapshot-dbg-cli init --use-default-rtdb 命令来查看此信息。
在其他地区设置 Firebase RTDB
默认情况下，snapshot-dbg-cli init 将在 us-central1 创建 Firebase 实时数据库。您可以在 Firebase 实时数据库支持的所有地区创建和使用数据库。请参阅支持的 RTDB 位置。
在非默认地区设置数据库有一些权衡
- 作为积极的一面，您可以控制快照数据将存储的位置。这可能对于合规性原因很重要。
- 作为消极的一面，vsCode 扩展和代理将无法自动找到数据库。需要通过配置显式提供数据库 URL，有关详细信息请参阅以下内容
您可以将数据库设置在非默认位置，方法如下：
snapshot-dbg-cli init --location={YOUR_LOCATION}
例如，您可能想将数据库设置在比利时，因此会运行 snapshot-dbg-cli init --location=europe-west1
请记住命令输出中提供的数据库URL；您需要将其提供给调试代理和vsCode插件。
在您的Google Cloud项目中设置Snapshot Debugger
工作示例
有关使用Snapshot Debugger与Java、Python和Node.js应用程序在不同Google Cloud环境中进行交互的工作示例，可以在以下位置找到：
代理文档
请参阅以下代理特定文档：
示例工作流程
您在调试对象上设置一个断点（快照或日志点）。调试对象代表正在运行的应用程序的实例。通常，同一版本的程序的所有实例都将具有相同的调试对象ID，并且设置在调试对象上的断点将安装在所有运行的实例上。
列出调试对象
运行以下命令：
snapshot-dbg-cli list_debuggees --include-inactive
输出类似于以下内容
Name ID Description Last Active Status
------------- ---------- ---------------------------------------- -------------------- --------
test-app - v2 d-8dd7f149 node index.js module:test-app version:v2 2022-12-16T21:45:07Z ACTIVE
test-app - v1 d-24abc4f1 node index.js module:test-app version:v1 2022-10-16T21:45:07Z INACTIVE
设置快照
快照捕获应用程序源代码中特定行位置的局部变量和调用栈。您可以指定某些条件和方法，以返回应用程序数据的快照，并详细查看它以调试应用程序。
使用以下命令设置快照：
snapshot-dbg-cli set_snapshot index.js:21 --debuggee-id d-8dd7f149
其中：
index.js:21是快照的file:lined-8dd7f149是调试对象ID
快照条件（可选）
快照条件是应用程序语言中的一个简单表达式，该表达式必须评估为true，才能捕获快照。每次执行该行时，快照条件都会由任何实例评估，直到条件评估为true或快照超时。
使用快照条件是可选的。
该条件是一个完整的布尔表达式，可以包含逻辑运算符。条件通过set_snapshots命令的--condition标志进行指定。
示例
snapshot-dbg-cli set_snapshot index.js:26 --debuggee-id d-8dd7f149 --condition="ultimateAnswer <= 42 && foo==bar"
您可以使用以下语言功能来表示条件：
Java
大多数Java表达式都受到支持，包括
- 局部变量：
a == 8。 - 数值和布尔运算：
x + y < 20。 - 实例和静态字段：
this.counter == 20、this.myObj.isShutdown、myStatic或com.mycompany.MyClass.staticMember。 - 使用等号运算符进行字符串比较：
myString == "abc"。 - 函数调用。只能使用只读函数。例如，
StringBuilder.indexOf()受支持，但StringBuilder.append()不受支持。 - 类型转换，使用完全限定类型：
((com.myprod.ClassImpl) myInterface).internalField
以下语言功能不支持：
- 数值类型的解包，如
Integer；请使用myInteger.value代替。
Python
大多数Python表达式都受到支持，包括
- 读取局部和全局变量。
- 从数组、列表、切片、字典和对象中读取。
- 调用简单方法。
以下语言功能不支持：
- 调用分配新对象或使用复杂结构的函数。
- 在表达式中创建新对象。
Node.js
大多数JavaScript表达式都受到支持，但有以下注意事项
可能具有静态副作用的表达式是不允许的。调试代理确保您添加的所有条件和观察点都是只读的并且没有副作用，但是它无法检测具有动态副作用的表达式。
例如，o.f 看起来像属性访问，但动态上，它可能最终调用getter函数。调试程序目前无法检测此类动态副作用。
快照表达式（可选）
Snapshot Debugger的“表达式”功能允许您在捕获快照时评估复杂表达式或遍历对象层次结构。表达式支持与上述描述的snapshot conditions相同的语言功能。
表达式的使用是可选的。
表达式的典型用途包括
- 查看不属于局部变量集的静态或全局变量。
- 轻松查看深度嵌套的成员变量。
- 避免重复的数学计算。例如，使用
(endTimeMillis - startTimeMillis) / 1000.0计算持续时间（以秒为单位）。
使用 set_snapshots 命令的 --expression 标志来指定表达式。
示例
snapshot-dbg-cli set_snapshot index.js:26 --debuggee-id d-8dd7f149 --expression="histogram.length"
列出快照
使用以下命令列出快照
snapshot-dbg-cli list_snapshots --debuggee-id d-8dd7f149 --include-inactive
其中：
d-8dd7f149是调试对象ID
输出类似于以下内容
Status Location Condition CompletedTime ID
--------- ----------- ----------- -------------------- ------------
ACTIVE index.js:21 b-1648008775
ACTIVE index.js:21 b-1648044994
ACTIVE index.js:21 b-1648045010
COMPLETED index.js:21 2022-03-23T02:52:23Z b-1648003845
获取快照
使用以下命令获取快照
snapshot-dbg-cli get_snapshot b-1649947203 --debuggee-id d-8dd7f149
其中：
b-1649947203是快照 IDd-8dd7f149是调试对象ID
输出类似于以下内容
--------------------------------------------------------------------------------
| Summary
--------------------------------------------------------------------------------
Location: index.js:30
Condition: No condition set.
Expressions: No expressions set.
Status: Complete
Create Time: 2022-05-13T14:14:01Z
Final Time: 2022-05-13T14:14:02Z
-------------------------------------------------------------------------------
| Evaluated Expressions
--------------------------------------------------------------------------------
There were no expressions specified.
--------------------------------------------------------------------------------
| Local Variables For Stack Frame Index 0:
--------------------------------------------------------------------------------
[
{
"req (IncomingMessage) ": {
"_readableState (ReadableState) ": {
"objectMode": "false",
"highWaterMark": "16384",
"buffer (BufferList) ": {
"head": null,
"tail": null,
"length": "0"
},
[... snip]
--------------------------------------------------------------------------------
| CallStack:
--------------------------------------------------------------------------------
Function Location
-------------------- -----------
(anonymous function) index.js:30
设置日志点
将调试日志点添加到调试目标（调试程序）。日志点在不更改您的代码或重新启动应用程序的情况下将日志注入到运行的服务中。每次任何实例在日志点位置执行代码时，快照调试器都会记录一条消息。输出将发送到目标编程语言的标准日志（Java 的 java.logging，Python 的 logging 等）。
日志点在创建后保持活跃状态24小时，或者直到它们被删除或服务重新部署。如果您在接收大量流量的行上放置日志点，调试器会限制日志点的速度以减少对应用程序的影响。
使用以下命令设置日志点
snapshot-dbg-cli set_logpoint index.js:21 "a={a} b={b}" --debuggee-id d-8dd7f149
其中：
index.js:21是日志点的文件:行。a={a} b={b}是日志点消息格式。d-8dd7f149是调试对象ID
注意：用户遇到的一个常见问题是，INFO 级别的日志通常会被默认的记录器抑制，因此日志点看起来像是损坏的。有关设置更高优先级日志级别的选项，请参阅
--log-level。
日志点消息格式
格式字符串是每次日志点位置执行时将被记录的消息。如果字符串包含大括号 ('{' 和 '}')，则大括号内的任何文本将被解释为调试目标的编程语言中的运行时表达式，该表达式将在日志点被击中时评估。一些有效的示例包括 {a}、{myObj.myFunc()} 或 {a + b}。该表达式的值将替换结果日志输出中的 {} 表达式。例如，如果您指定格式字符串 "a={a}, (b+1)={b+1}"，并且日志点在局部变量 a 为 1、b 为 3 时被击中，则结果日志输出将是 "a=1, (b+1)=3"。
有关有效表达式的更多详细信息，请参阅 快照表达式，因为规则对日志点表达式相同。
日志点条件（可选）
日志点条件是应用语言中的一个简单表达式，该表达式必须评估为 true，日志点才会被记录。日志点条件将在每次执行该行时由任何实例评估，直到日志点过期或被删除。
使用日志点条件是可选的。
有关有效条件的更多详细信息，请参阅 快照条件，因为规则对日志点条件相同。
列出日志点
使用以下命令列出日志点
snapshot-dbg-cli list_logpoints --debuggee-id d-8dd7f149 --include-inactive
其中：
d-8dd7f149是调试对象ID
输出类似于以下内容
User Email Location Condition Log Level Log Message Format ID Status
------------ -------------- --------- --------- ------------------- ------------ -------------------------------------------
foo1@bar.com Main.java:23 INFO a={a} b={b} b-1660681047 EXPIRED
foo2@bar.com Main.java:25 a == 3 WARNING Line hit b-1660932877 EXPIRED
foo2@bar.com Main.java:9999 INFO Log msg b-1661203071 SOURCE_LOCATION: No code found at line 9999
获取日志点
使用以下命令获取日志点
snapshot-dbg-cli get_logpoint b-1660681047 --debuggee-id d-8dd7f149
其中：
b-1660681047是日志点 IDd-8dd7f149是调试对象ID
输出类似于以下内容
Logpoint ID: b-1660681047
Log Message Format: a == 3
Location: Main.java:23
Condition: No condition set
Status: EXPIRED
Create Time: 2022-08-19T18:14:38Z
Final Time: 2022-08-20T18:14:39Z
User Email: foo1@bar.com
清理
可以使用以下命令删除调试程序和断点（快照和日志点）。
删除调试程序
运行以下命令：
snapshot-dbg-cli delete_debuggees
输出类似于以下内容
This command will delete the following debuggees:
Name ID Last Active Status
------------------------- ---------- -------------------- ------
default - 20221125t224954 d-39f7082e 2022-12-05T03:13:42Z STALE
default - 20221125t154414 d-dba89292 2022-12-04T03:02:48Z STALE
Do you want to continue (Y/n)?
Deleted 2 debuggees.
删除调试程序时，也将删除属于它的所有断点。
删除快照
使用以下命令删除快照
snapshot-dbg-cli delete_snapshots --debuggee-id d-8dd7f149 --include-inactive
其中：
d-8dd7f149是调试对象ID
输出类似于以下内容
This command will delete the following snapshots:
Status Location Condition ID
--------- ----------- ----------- ------------
ACTIVE index.js:28 b-1649959801
ACTIVE index.js:27 b-1649959807
COMPLETED index.js:19 b-1649702213
COMPLETED index.js:22 b-1649702753
Do you want to continue (Y/n)? Y
Deleted 4 snapshots.
删除日志点
使用以下命令删除日志点
snapshot-dbg-cli delete_snapshots --debuggee-id d-8dd7f149 --include-inactive
其中：
d-8dd7f149是调试对象ID
输出类似于以下内容
This command will delete the following logpoints:
Location Condition Log Level Log Message Format ID
--------------- --------- --------- ------------------ ------------
Main.java:25 a == 3 WARNING Line hit b-1660927187
Main.java:9999 INFO Log msg b-1660927272
Do you want to continue (Y/n)?
Deleted 4 snapshots.
VSCode 扩展
存在用于快照调试器的 VSCode 扩展。您可以使用此扩展在 IDE 中设置日志点、设置断点并查看快照。有关更多详细信息，请参阅扩展的 README。
您可以通过从 最新版本 下载扩展，然后运行 code --install-extension snapshotdbg-*.vsix 来安装扩展。
请注意，您仍然需要使用快照调试器CLI来设置您的环境并清除旧数据。需要安装Gcloud以进行凭据管理。
故障排除
请参阅快照调试器故障排除
Firebase DB架构
下载文件
下载您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。