Index
Controller2(interface)Debugger2(interface)Breakpoint(message)Breakpoint.Action(enum)Breakpoint.LogLevel(enum)Breakpoint.State(enum)Debuggee(message)Debuggee.CanaryMode(enum)DeleteBreakpointRequest(message)FormatMessage(message)GetBreakpointRequest(message)GetBreakpointResponse(message)ListActiveBreakpointsRequest(message)ListActiveBreakpointsResponse(message)ListBreakpointsRequest(message)ListBreakpointsRequest.BreakpointActionValue(message)ListBreakpointsResponse(message)ListDebuggeesRequest(message)ListDebuggeesResponse(message)RegisterDebuggeeRequest(message)RegisterDebuggeeResponse(message)SetBreakpointRequest(message)SetBreakpointRequest.CanaryOption(enum)SetBreakpointResponse(message)SourceLocation(message)StackFrame(message)StatusMessage(message)StatusMessage.Reference(enum)UpdateActiveBreakpointRequest(message)UpdateActiveBreakpointResponse(message)Variable(message)
Controller2
The Controller service provides the API for orchestrating a collection of debugger agents to perform debugging tasks. These agents are each attached to a process of an application which may include one or more replicas.
The debugger agents register with the Controller to identify the application being debugged, the Debuggee. All agents that register with the same data, represent the same Debuggee, and are assigned the same debuggee_id.
The debugger agents call the Controller to retrieve the list of active Breakpoints. Agents with the same debuggee_id get the same breakpoints list. An agent that can fulfill the breakpoint request updates the Controller with the breakpoint result. The controller selects the first result received and discards the rest of the results. Agents that poll again for active breakpoints will no longer have the completed breakpoint in the list and should remove that breakpoint from their attached process.
The Controller service does not provide a way to retrieve the results of a completed breakpoint. This functionality is available using the Debugger service.
| ListActiveBreakpoints |
|---|
|
Returns the list of all active breakpoints for the debuggee. The breakpoint specification ( This means that an agent does not need to check if a breakpoint has changed when it encounters the same breakpoint on a successive call. Moreover, an agent should remember the breakpoints that are completed until the controller removes them from the active list to avoid setting those breakpoints again.
|
| RegisterDebuggee |
|---|
|
Registers the debuggee with the controller service. All agents attached to the same application must call this method with exactly the same request content to get back the same stable This protocol allows the controller service to disable debuggees, recover from data loss, or change the
|
| UpdateActiveBreakpoint |
|---|
|
Updates the breakpoint state or mutable fields. The entire Breakpoint message must be sent back to the controller service. Updates to active breakpoint fields are only allowed if the new value does not change the breakpoint specification. Updates to the
|
Debugger2
The Debugger service provides the API that allows users to collect run-time information from a running application, without stopping or slowing it down and without modifying its state. An application may include one or more replicated processes performing the same work.
A debugged application is represented using the Debuggee concept. The Debugger service provides a way to query for available debuggees, but does not provide a way to create one. A debuggee is created using the Controller service, usually by running a debugger agent with the application.
The Debugger service enables the client to set one or more Breakpoints on a Debuggee and collect the results of the set Breakpoints.
| DeleteBreakpoint |
|---|
|
Deletes the breakpoint from the debuggee.
|
| GetBreakpoint |
|---|
|
Gets breakpoint information.
|
| ListBreakpoints |
|---|
|
Lists all breakpoints for the debuggee.
|
| ListDebuggees |
|---|
|
Lists all the debuggees that the user has access to.
|
| SetBreakpoint |
|---|
|
Sets the breakpoint to the debuggee.
|
Breakpoint
Breakpoint (the resource)
Represents the breakpoint specification, status and results.
| Fields | |
|---|---|
id |
Breakpoint identifier, unique in the scope of the debuggee. |
action |
Action that the agent should perform when the code at the breakpoint location is hit. |
location |
Breakpoint source location. |
condition |
Condition that triggers the breakpoint. The condition is a compound boolean expression composed using expressions in a programming language at the source location. |
expressions[] |
List of read-only expressions to evaluate at the breakpoint location. The expressions are composed using expressions in the programming language at the source location. If the breakpoint action is |
log_message_format |
Only relevant when action is Example: |
log_level |
Indicates the severity of the log. Only relevant when action is |
is_final_state |
When true, indicates that this is a final result and the breakpoint state will not change from here on. |
create_time |
Time this breakpoint was created by the server in seconds resolution. |
final_time |
Time this breakpoint was finalized as seen by the server in seconds resolution. |
user_email |
E-mail address of the user that created this breakpoint |
status |
Breakpoint status. The status includes an error flag and a human readable message. This field is usually unset. The message can be either informational or an error message. Regardless, clients should always display the text message back to the user. Error status indicates complete failure of the breakpoint. Example (non-final state): Examples (final state):
|
stack_frames[] |
The stack at breakpoint time, where stack_frames[0] represents the most recently entered function. |
evaluated_expressions[] |
Values of evaluated expressions at breakpoint time. The evaluated expressions appear in exactly the same order they are listed in the |
variable_table[] |
The The variable |
labels |
A set of custom breakpoint properties, populated by the agent, to be displayed to the user. |
canary_expire_time |
The deadline for the breakpoint to stay in CANARY_ACTIVE state. The value is meaningless when the breakpoint is not in CANARY_ACTIVE state. |
state |
The current state of the breakpoint. |
Action
Actions that can be taken when a breakpoint hits. Agents should reject breakpoints with unsupported or unknown action values.
| Enums | |
|---|---|
CAPTURE |
Capture stack frame and variables and update the breakpoint. The data is only captured once. After that the breakpoint is set in a final state. |
LOG |
Log each breakpoint hit. The breakpoint remains active until deleted or expired. |
LogLevel
Log severity levels.
| Enums | |
|---|---|
INFO |
Information log message. |
WARNING |
Warning log message. |
ERROR |
Error log message. |
State
Breakpoint state.
| Enums | |
|---|---|
STATE_UNSPECIFIED |
Breakpoint state UNSPECIFIED. |
STATE_CANARY_PENDING_AGENTS |
Enabling canary but no agents are available. |
STATE_CANARY_ACTIVE |
Enabling canary and successfully assigning canary agents. |
STATE_ROLLING_TO_ALL |
Breakpoint rolling out to all agents. |
STATE_IS_FINAL |
Breakpoint is hit/complete/failed. |
Debuggee
Represents the debugged application. The application may include one or more replicated processes executing the same code. Each of these processes is attached with a debugger agent, carrying out the debugging commands. Agents attached to the same debuggee identify themselves as such by using exactly the same Debuggee message value when registering.
| Fields | |
|---|---|
id |
Unique identifier for the debuggee generated by the controller service. |
project |
Project the debuggee is associated with. Use project number or id when registering a Google Cloud Platform project. |
uniquifier |
Uniquifier to further distinguish the application. It is possible that different applications might have identical values in the debuggee message, thus, incorrectly identified as a single application by the Controller service. This field adds salt to further distinguish the application. Agents should consider seeding this field with value that identifies the code, binary, configuration and environment. |
description |
Human readable description of the debuggee. Including a human-readable project name, environment name and version information is recommended. |
is_inactive |
If set to |
agent_version |
Version ID of the agent. Schema: |
is_disabled |
If set to |
status |
Human readable message to be displayed to the user about this debuggee. Absence of this field indicates no status. The message can be either informational or an error status. |
source_contexts[] |
References to the locations and revisions of the source code used in the deployed application. |
ext_source_contexts[] |
References to the locations and revisions of the source code used in the deployed application. |
labels |
A set of custom debuggee properties, populated by the agent, to be displayed to the user. |
canary_mode |
Used when setting breakpoint canary for this debuggee. |
CanaryMode
Canary mode
| Enums | |
|---|---|
CANARY_MODE_UNSPECIFIED |
CANARY_MODE_UNSPECIFIED is equivalent to CANARY_MODE_ALWAYS_DISABLED so that if the debuggee is not configured to use the canary feature, the feature will be disabled. |
CANARY_MODE_ALWAYS_ENABLED |
Always enable breakpoint canary regardless of the value of breakpoint's canary option. |
CANARY_MODE_ALWAYS_DISABLED |
Always disable breakpoint canary regardless of the value of breakpoint's canary option. |
CANARY_MODE_DEFAULT_ENABLED |
Depends on the breakpoint's canary option. Enable canary by default if the breakpoint's canary option is not specified. |
CANARY_MODE_DEFAULT_DISABLED |
Depends on the breakpoint's canary option. Disable canary by default if the breakpoint's canary option is not specified. |
DeleteBreakpointRequest
Request to delete a breakpoint.
| Fields | |
|---|---|
debuggee_id |
Required. ID of the debuggee whose breakpoint to delete. |
breakpoint_id |
Required. ID of the breakpoint to delete. |
client_version |
Required. The client version making the call. Schema: |
FormatMessage
Represents a message with parameters.
| Fields | |
|---|---|
format |
Format template for the message. The Examples:
|
parameters[] |
Optional parameters to be embedded into the message. |
GetBreakpointRequest
Request to get breakpoint information.
| Fields | |
|---|---|
debuggee_id |
Required. ID of the debuggee whose breakpoint to get. |
breakpoint_id |
Required. ID of the breakpoint to get. |
client_version |
Required. The client version making the call. Schema: |
GetBreakpointResponse
Response for getting breakpoint information.
| Fields | |
|---|---|
breakpoint |
Complete breakpoint state. The fields |
ListActiveBreakpointsRequest
Request to list active breakpoints.
| Fields | |
|---|---|
debuggee_id |
Required. Identifies the debuggee. |
wait_token |
A token that, if specified, blocks the method call until the list of active breakpoints has changed, or a server-selected timeout has expired. The value should be set from the |
success_on_timeout |
If set to If set to |
agent_id |
Identifies the agent. This is the ID returned in the RegisterDebuggee response. |
ListActiveBreakpointsResponse
Response for listing active breakpoints.
| Fields | |
|---|---|
breakpoints[] |
List of all active breakpoints. The fields |
next_wait_token |
A token that can be used in the next method call to block until the list of breakpoints changes. |
wait_expired |
If set to |
ListBreakpointsRequest
Request to list breakpoints.
| Fields | |
|---|---|
debuggee_id |
Required. ID of the debuggee whose breakpoints to list. |
include_all_users |
When set to |
include_inactive |
When set to |
action |
When set, the response includes only breakpoints with the specified action. |
strip_results |
This field is deprecated. The following fields are always stripped out of the result: |
wait_token |
A wait token that, if specified, blocks the call until the breakpoints list has changed, or a server selected timeout has expired. The value should be set from the last response. The error code |
client_version |
Required. The client version making the call. Schema: |
BreakpointActionValue
Wrapper message for Breakpoint.Action. Defines a filter on the action field of breakpoints.
| Fields | |
|---|---|
value |
Only breakpoints with the specified action will pass the filter. |
ListBreakpointsResponse
Response for listing breakpoints.
| Fields | |
|---|---|
breakpoints[] |
List of breakpoints matching the request. The fields |
next_wait_token |
A wait token that can be used in the next call to |
ListDebuggeesRequest
Request to list debuggees.
| Fields | |
|---|---|
project |
Required. Project number of a Google Cloud project whose debuggees to list. |
include_inactive |
When set to |
client_version |
Required. The client version making the call. Schema: |
ListDebuggeesResponse
Response for listing debuggees.
| Fields | |
|---|---|
debuggees[] |
List of debuggees accessible to the calling user. The fields |
RegisterDebuggeeRequest
Request to register a debuggee.
| Fields | |
|---|---|
debuggee |
Required. Debuggee information to register. The fields |
RegisterDebuggeeResponse
Response for registering a debuggee.
| Fields | |
|---|---|
debuggee |
Debuggee resource. The field |
agent_id |
A unique ID generated for the agent. Each RegisterDebuggee request will generate a new agent ID. |
SetBreakpointRequest
Request to set a breakpoint
| Fields | |
|---|---|
debuggee_id |
Required. ID of the debuggee where the breakpoint is to be set. |
breakpoint |
Required. Breakpoint specification to set. The field |
client_version |
Required. The client version making the call. Schema: |
canary_option |
The canary option set by the user upon setting breakpoint. |
CanaryOption
Canary option
| Enums | |
|---|---|
CANARY_OPTION_UNSPECIFIED |
Depends on the canary_mode of the debuggee. |
CANARY_OPTION_TRY_ENABLE |
Enable the canary for this breakpoint if the canary_mode of the debuggee is not CANARY_MODE_ALWAYS_ENABLED or CANARY_MODE_ALWAYS_DISABLED. |
CANARY_OPTION_TRY_DISABLE |
Disable the canary for this breakpoint if the canary_mode of the debuggee is not CANARY_MODE_ALWAYS_ENABLED or CANARY_MODE_ALWAYS_DISABLED. |
SetBreakpointResponse
Response for setting a breakpoint.
| Fields | |
|---|---|
breakpoint |
Breakpoint resource. The field |
SourceLocation
Represents a location in the source code.
| Fields | |
|---|---|
path |
Path to the source file within the source context of the target binary. |
line |
Line inside the file. The first line in the file has the value |
column |
Column within a line. The first column in a line as the value |
StackFrame
Represents a stack frame context.
| Fields | |
|---|---|
function |
Demangled function name at the call site. |
location |
Source location of the call site. |
arguments[] |
Set of arguments passed to this function. Note that this might not be populated for all stack frames. |
locals[] |
Set of local variables at the stack frame location. Note that this might not be populated for all stack frames. |
StatusMessage
Represents a contextual status message. The message can indicate an error or informational status, and refer to specific parts of the containing object. For example, the Breakpoint.status field can indicate an error referring to the BREAKPOINT_SOURCE_LOCATION with the message Location not found.
| Fields | |
|---|---|
is_error |
Distinguishes errors from informational messages. |
refers_to |
Reference to which the message applies. |
description |
Status message text. |
Reference
Enumerates references to which the message applies.
| Enums | |
|---|---|
UNSPECIFIED |
Status doesn't refer to any particular input. |
BREAKPOINT_SOURCE_LOCATION |
Status applies to the breakpoint and is related to its location. |
BREAKPOINT_CONDITION |
Status applies to the breakpoint and is related to its condition. |
BREAKPOINT_EXPRESSION |
Status applies to the breakpoint and is related to its expressions. |
BREAKPOINT_AGE |
Status applies to the breakpoint and is related to its age. |
BREAKPOINT_CANARY_FAILED |
Status applies to the breakpoint when the breakpoint failed to exit the canary state. |
VARIABLE_NAME |
Status applies to the entire variable. |
VARIABLE_VALUE |
Status applies to variable value (variable name is valid). |
UpdateActiveBreakpointRequest
Request to update an active breakpoint.
| Fields | |
|---|---|
debuggee_id |
Required. Identifies the debuggee being debugged. |
breakpoint |
Required. Updated breakpoint information. The field |
UpdateActiveBreakpointResponse
Response for updating an active breakpoint. The message is defined to allow future extensions.
Variable
Represents a variable or an argument possibly of a compound object type. Note how the following variables are represented:
1) A simple variable:
int x = 5
{ name: "x", value: "5", type: "int" } // Captured variable
2) A compound object:
struct T {
int m1;
int m2;
};
T x = { 3, 7 };
{ // Captured variable
name: "x",
type: "T",
members { name: "m1", value: "3", type: "int" },
members { name: "m2", value: "7", type: "int" }
}
3) A pointer where the pointee was captured:
T x = { 3, 7 };
T* p = &x;
{ // Captured variable
name: "p",
type: "T*",
value: "0x00500500",
members { name: "m1", value: "3", type: "int" },
members { name: "m2", value: "7", type: "int" }
}
4) A pointer where the pointee was not captured:
T* p = new T;
{ // Captured variable
name: "p",
type: "T*",
value: "0x00400400"
status { is_error: true, description { format: "unavailable" } }
}
The status should describe the reason for the missing value, such as <optimized out>, <inaccessible>, <pointers limit reached>.
Note that a null pointer should not have members.
5) An unnamed value:
int* p = new int(7);
{ // Captured variable
name: "p",
value: "0x00500500",
type: "int*",
members { value: "7", type: "int" } }
6) An unnamed pointer where the pointee was not captured:
int* p = new int(7);
int** pp = &p;
{ // Captured variable
name: "pp",
value: "0x00500500",
type: "int**",
members {
value: "0x00400400",
type: "int*"
status {
is_error: true,
description: { format: "unavailable" } }
}
}
}
To optimize computation, memory and network traffic, variables that repeat in the output multiple times can be stored once in a shared variable table and be referenced using the var_table_index field. The variables stored in the shared table are nameless and are essentially a partition of the complete variable. To reconstruct the complete variable, merge the referencing variable with the referenced variable.
When using the shared variable table, the following variables:
T x = { 3, 7 };
T* p = &x;
T& r = x;
{ name: "x", var_table_index: 3, type: "T" } // Captured variables
{ name: "p", value "0x00500500", type="T*", var_table_index: 3 }
{ name: "r", type="T&", var_table_index: 3 }
{ // Shared variable table entry #3:
members { name: "m1", value: "3", type: "int" },
members { name: "m2", value: "7", type: "int" }
}
Note that the pointer address is stored with the referencing variable and not with the referenced variable. This allows the referenced variable to be shared between pointers and references.
The type field is optional. The debugger agent may or may not support it.
| Fields | |
|---|---|
name |
Name of the variable, if any. |
value |
Simple value of the variable. |
type |
Variable type (e.g. |
members[] |
Members contained or pointed to by the variable. |
var_table_index |
Reference to a variable in the shared variable table. More than one variable can reference the same variable in the table. The |
status |
Status associated with the variable. This field will usually stay unset. A status of a single variable only applies to that variable or expression. The rest of breakpoint data still remains valid. Variables might be reported in error state even when breakpoint is not in final state. The message may refer to variable name with Example of error message applied to name: Example of information message applied to value: Examples of error message applied to value:
|