This page describes client roles, the data model and supported operations in the Stackdriver Debugger API.
The API defines two client roles, agents and debugger clients.
An agent is a program that runs on the same system where a debuggee application is running. The agent is responsible for sending state data -- such as the value of program variables and the call stack -- to Stackdriver Debugger when the code at a breakpoint location is executed.
You can have more than one agent per debuggee. For example, you may have an application that is made up of several runnable tasks. Each task has its own agent, but all together make up a single debuggee. However, if you are running multiple versions of an application, each version is a separate debuggee that can be debugged separately.
A debugger client is an application that allows a user to set and remove breakpoints, and to view state data that is captured at a breakpoint (also known as a snapshot). An example of a debugger client is the Stackdriver Debugger tool that runs in the Google Cloud Platform Console. Another example is an IDE where you want to add debugger functionality.
The API data model provides entities for debuggees and breakpoints, as well as types of state data that an agent can collect when code at a breakpoint location is executed.
A debuggee is an application that a user wants to debug. As above, all tasks
that comprise an application are considered to be the same debuggee and share
the same debuggee ID. Different versions of the sample application are
considered to be different debuggees. Debuggees are represented in
the API by the
A breakpoint is an entity that provides information to an agent about where and when to collect state data about an application. It also stores the state data itself when it is collected.
A breakpoint specifies the following:
- Location in the debuggee source code
- Conditional expression that the agent uses to determine when to collect state data
- Expressions to evaluate when data is collected
When state data is collected from the debuggee, it can include:
- Values of program variables
- Call stack
- Values of expressions that were evaluated
A variable contains the contents of a program object (named or unnamed) at the
time state data was collected by an agent. For instance, it can contain the
value of a local variable of type integer, or any number of members that are
themselves variables. Variables are represented by the
A status message provides state information about the state of breakpoints
and/or variables. For instance, a breakpoint set on an invalid source location
may contain a status message that indicates an error. Status messages are
represented by the
The Controller and Debugger interfaces provide a set of operations for agents and debugger clients respectively.
The Controller interface allows agents to perform the following operations:
|Register||Registers the debuggee with controller service.||
|List active breakpoints||Returns a list of all active breakpoints for the specified debuggee.||
|Update active breakpoints||Updates state data -- for example, program variables and the call stack -- for the application at the breakpoint.||
A typical order of operations for an agent is as follows:
When the application starts, the agent registers it as a debuggee using the
At intervals, the agent calls
ListActiveBreakpointsto retrieve the currently set breakpoints.
When the application reaches a code location where a breakpoint is set, the agent collects state data -- for example, the value of program variables or the call stack -- and sends it to the controller service using
Debugger client operations
The Debugger interface allows debugger clients to perform the following operations:
|List debuggees||Lists the debuggees where a user of the client can set breakpoints.||
|Set breakpoint||Sets a breakpoint location.||
|List breakpoints||Returns a list of breakpoints accessible to the current user.||
|Get breakpoint||Gets breakpoint details by debuggee and breakpoint IDs.||
|Delete breakpoint||Deletes the specified breakpoint.||
A typical order of operations for a debugger client is as follows:
When a user starts the debugger workflow -- for example, by opening the debugger view in the client application UI -- the client calls the
ListDebugeesmethod to retrieve a list of the application versions that are available for debugging and allows the user to choose from them.
When the user creates a breakpoint in the UI, the client application calls
SetBreakpointoperation to set the breakpoint.
At intervals, the client application calls
GetBreakpointto check whether a debuggee has executed code at the breakpoint location and the agent has updated the state data for the breakpoint. If so, the client application displays the state data to the user.
If the user deletes the breakpoint in the UI, the client calls