Concepts

This page describes client roles, the data model and supported operations in the Stackdriver Debugger API.

Client roles

The API defines two client roles, agents and debugger clients.

Agents

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.

Example of agents include the Google-provided debugger agents that you can use with applications written in Java or Go that run on Google Compute Engine.

Debugger clients

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.

Data model

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.

Debuggees

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 Debuggee entity (REST or RPC).

Breakpoints

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

Breakpoints are represented by the Breakpoint entity (RPC or REST).

Source locations

A source location defines a point in the target application in terms of file path and line number. Source locations are represented by the SourceLocation entity (RPC or REST).

Variables

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 an local variable of type integer, or any number of members that are themselves variables. Variables are represented by the Variable entity (RPC or REST).

Status messages

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 StatusMessage entity (RPC or REST).

Format messages

A format message is the text content of a status message. Format messages are represented by the FormatMessage entity (RPC or REST).

Operations

The Controller and Debugger interfaces provide a set of operations for agents and debugger clients respectively.

Agent operations

The Controller interface allows agents to perform the following operations:

Operation Description REST RPC
Register Registers the debuggee with controller service. register RegisterDebuggee
List active breakpoints Returns a list of all active breakpoints for the specified debuggee. list ListActiveBreakpoints
Update active breakpoints Updates state data -- for example, program variables and the call stack -- for the application at the breakpoint. update UpdateActiveBreakpoint

A typical order of operations for an agent is as follows:

  1. When the application starts, the agent registers it as a debuggee using the register or RegisterDebugger method.

  2. At intervals, the agent calls list or ListActiveBreakpoints to retrieve the currently set breakpoints.

  3. 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 update or UpdateActiveBreakpoint.

Debugger client operations

The Debugger interface allows debugger clients to perform the following operations:

Operation Description REST RPC
List debuggees Lists the debuggees where a user of the client can set breakpoints. list ListDebuggees
Set breakpoint Sets a breakpoint location. set SetBreakpoint
List breakpoints Returns a list of breakpoints accessible to the current user. list ListBreakpoints
Get breakpoint Gets breakpoint details by debuggee and breakpoint IDs. get GetBreakpoint
Delete breakpoint Deletes the specified breakpoint. delete DeleteBreakpoint

A typical order of operations for a debugger client is as follows:

  1. When a user starts the debugger workflow -- for example, by opening the debugger view in the client application UI -- the client calls the list or ListDebugees method to retrieve a list of the application versions that are available for debugging and allows the user to choose from them.

  2. When the user creates a breakpoint in the UI, the client application calls set or SetBreakpoint operation to set the breakpoint.

  3. At intervals, the client application calls get or GetBreakpoint to 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.

  4. If the user deletes the breakpoint in the UI, the client calls delete or DeleteBreakpoint.

Send feedback about...

Stackdriver Debugger Documentation