概念

本页介绍了 Stackdriver Debugger API 中的客户端角色、数据模型和支持的操作。

客户端角色

API 定义了两种客户端角色:代理和调试程序客户端。

代理

代理是在运行调试对象应用的同一系统上运行的程序。执行断点位置的代码时,代理负责向 Stackdriver Debugger 发送状态数据(例如程序变量的值和调用堆栈)。

每个调试对象可以有多个代理。例如,您可能有一个由多个可运行任务组成的应用。每个任务都有自己的代理,但所有代理组成了一个调试对象。但是,如果您运行的是多个版本的应用,则每个版本都是一个单独的调试对象,可以单独进行调试。

代理示例包括 Google 提供的 Debugger 代理,这些代理适用于在 Google Compute Engine 上运行的使用 JavaGo 编写的应用。

调试程序客户端

调试程序客户端是一个应用,允许用户设置和删除断点,以及查看在断点处捕获的状态数据(也称为快照)。调试程序客户端的一个示例是在 Google Cloud Platform Console 中运行的 Stackdriver Debugger 工具。另一个示例是您想要添加调试程序功能的 IDE。

数据模型

API 数据模型为调试对象和断点提供实体,以及在执行断点位置的代码时代理可以收集的状态数据类型。

调试对象

调试对象是用户想要调试的应用。如上所述,构成应用的所有任务都被认为是同一调试对象并共享同一调试对象 ID。不同版本的示例应用被认为是不同的调试对象。调试对象在 API 中表示为 Debuggee 实体(RESTRPC)。

断点

断点是一个实体,它向代理提供何时何地收集有关应用的状态数据的信息。它还会在收集状态数据时存储状态数据。

断点指定以下内容:

  • 调试对象源代码中的位置
  • 代理用于确定何时收集状态数据的条件表达式
  • 收集数据时计算的表达式

从调试对象收集状态数据时,它可以包括:

  • 程序变量的值
  • 调用堆栈
  • 被求值的表达式的值

断点表示为 Breakpoint 实体(RPCREST)。

源位置

源位置根据文件路径和行号定义目标应用中的一个点。来源位置表示为 SourceLocation 实体(RPCREST)。

变量

变量包含代理收集状态数据时程序对象(无论是否命名)的内容。例如,变量可以包含 integer 类型的局部变量的值,或者包含任意数量的变量。变量表示为 Variable 实体(RPCREST)。

状态消息

状态消息提供有关断点和/或变量的状态的状态信息。例如,在无效源位置上设置的断点可能包含一条表示错误的状态消息。状态消息表示为 StatusMessage 实体(RPCREST)。

格式消息

格式消息是状态消息的文本内容。格式消息表示为 FormatMessage 实体(RPCREST)。

操作

Controller 和 Debugger 接口分别为代理和调试程序客户端提供一组操作。

代理操作

Controller 接口允许代理执行以下操作:

操作 说明 REST RPC
注册 使用控制器服务注册调试对象。 register RegisterDebuggee
列出活动断点 返回指定调试对象的所有活动断点的列表。 list ListActiveBreakpoints
更新活动断点 更新断点处应用的状态数据(例如,程序变量和调用堆栈)。 update UpdateActiveBreakpoint

代理的典型操作顺序如下所示:

  1. 应用启动时,代理会使用 registerRegisterDebugger 方法将应用注册为调试对象。

  2. 每隔一段时间,代理会调用 listListActiveBreakpoints 来检索当前设置的断点。

  3. 当应用到达设置断点的代码位置时,代理会收集状态数据(例如,程序变量的值或调用堆栈),并使用 updateUpdateActiveBreakpoint 将其发送到控制器服务。

调试程序客户端操作

Debugger 接口允许调试程序客户端执行以下操作:

操作 说明 REST RPC
列出调试对象 列出客户端用户可以设置断点的调试对象。 list ListDebuggees
设置断点 设置断点位置。 set SetBreakpoint
列出断点 返回当前用户可访问的断点列表。 list ListBreakpoints
获得断点 通过调试对象和断点 ID 获取断点详细信息。 get GetBreakpoint
删除断点 删除指定的断点。 delete DeleteBreakpoint

调试程序客户端的典型操作顺序如下所示:

  1. 当用户启动调试程序工作流时(例如,通过在客户端应用界面中打开调试器视图),客户端会调用 listListDebugees 方法来检索可用于调试的应用版本列表,并允许用户从列表中进行选择。

  2. 当用户在界面中创建断点时,客户端应用调用 setSetBreakpoint 操作来设置断点。

  3. 每隔一段时间,客户端应用调用 getGetBreakpoint 来检查调试对象是否在断点位置执行了代码,并且代理是否已更新断点的状态数据。如果是,则客户端应用向用户显示状态数据。

  4. 如果用户在界面中删除断点,则客户端会调用 deleteDeleteBreakpoint