google.devtools.clouddebugger.v2.data.proto Maven / Gradle / Ivy
// Copyright (c) 2015, Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";
package google.devtools.clouddebugger.v2;
import "google/api/annotations.proto";
import "google/devtools/source/v1/source_context.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
option java_multiple_files = true;
option java_outer_classname = "DataProto";
option java_package = "com.google.devtools.clouddebugger.v2";
// Represents a message with parameters.
message FormatMessage {
// Format template for the message. The `format` uses placeholders `$0`,
// `$1`, etc. to reference parameters. `$$` can be used to denote the `$`
// character.
//
// Examples:
//
// * `Failed to load '$0' which helps debug $1 the first time it
// is loaded. Again, $0 is very important.`
// * `Please pay $$10 to use $0 instead of $1.`
string format = 1;
// Optional parameters to be embedded into the message.
repeated string parameters = 2;
}
// 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`.
message StatusMessage {
// Enumerates references to which the message applies.
enum Reference {
// Status doesn't refer to any particular input.
UNSPECIFIED = 0;
// Status applies to the breakpoint and is related to its location.
BREAKPOINT_SOURCE_LOCATION = 3;
// Status applies to the breakpoint and is related to its condition.
BREAKPOINT_CONDITION = 4;
// Status applies to the breakpoint and is related to its expressions.
BREAKPOINT_EXPRESSION = 7;
// Status applies to the entire variable.
VARIABLE_NAME = 5;
// Status applies to variable value (variable name is valid).
VARIABLE_VALUE = 6;
}
// Distinguishes errors from informational messages.
bool is_error = 1;
// Reference to which the message applies.
Reference refers_to = 2;
// Status message text.
FormatMessage description = 3;
}
// Represents a location in the source code.
message SourceLocation {
// Path to the source file within the source context of the target binary.
string path = 1;
// Line inside the file. The first line in the file has the value `1`.
int32 line = 2;
}
// 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 ``, ``, ``.
//
// 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.
message Variable {
// Name of the variable, if any.
string name = 1;
// Simple value of the variable.
string value = 2;
// Variable type (e.g. `MyClass`). If the variable is split with
// `var_table_index`, `type` goes next to `value`. The interpretation of
// a type is agent specific. It is recommended to include the dynamic type
// rather than a static type of an object.
string type = 6;
// Members contained or pointed to by the variable.
repeated Variable members = 3;
// Reference to a variable in the shared variable table. More than
// one variable can reference the same variable in the table. The
// `var_table_index` field is an index into `variable_table` in Breakpoint.
google.protobuf.Int32Value var_table_index = 4;
// 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 `refers_to` set to
// `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.
// In either case variable value and members will be unset.
//
// Example of error message applied to name: `Invalid expression syntax`.
//
// Example of information message applied to value: `Not captured`.
//
// Examples of error message applied to value:
//
// * `Malformed string`,
// * `Field f not found in class C`
// * `Null pointer dereference`
StatusMessage status = 5;
}
// Represents a stack frame context.
message StackFrame {
// Demangled function name at the call site.
string function = 1;
// Source location of the call site.
SourceLocation location = 2;
// Set of arguments passed to this function.
// Note that this might not be populated for all stack frames.
repeated Variable arguments = 3;
// Set of local variables at the stack frame location.
// Note that this might not be populated for all stack frames.
repeated Variable locals = 4;
}
// Represents the breakpoint specification, status and results.
message Breakpoint {
// Actions that can be taken when a breakpoint hits.
// Agents should reject breakpoints with unsupported or unknown action values.
enum Action {
// 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.
CAPTURE = 0;
// Log each breakpoint hit. The breakpoint remains active until
// deleted or expired.
LOG = 1;
}
// Log severity levels.
enum LogLevel {
// Information log message.
INFO = 0;
// Warning log message.
WARNING = 1;
// Error log message.
ERROR = 2;
}
// Breakpoint identifier, unique in the scope of the debuggee.
string id = 1;
// Action that the agent should perform when the code at the
// breakpoint location is hit.
Action action = 13;
// Breakpoint source location.
SourceLocation location = 2;
// Condition that triggers the breakpoint.
// The condition is a compound boolean expression composed using expressions
// in a programming language at the source location.
string condition = 3;
// 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`, the evaluated
// expressions are included in log statements.
repeated string expressions = 4;
// Only relevant when action is `LOG`. Defines the message to log when
// the breakpoint hits. The message may include parameter placeholders `$0`,
// `$1`, etc. These placeholders are replaced with the evaluated value
// of the appropriate expression. Expressions not referenced in
// `log_message_format` are not logged.
//
// Example: `Message received, id = $0, count = $1` with
// `expressions` = `[ message.id, message.count ]`.
string log_message_format = 14;
// Indicates the severity of the log. Only relevant when action is `LOG`.
LogLevel log_level = 15;
// When true, indicates that this is a final result and the
// breakpoint state will not change from here on.
bool is_final_state = 5;
// Time this breakpoint was created by the server in seconds resolution.
google.protobuf.Timestamp create_time = 11;
// Time this breakpoint was finalized as seen by the server in seconds
// resolution.
google.protobuf.Timestamp final_time = 12;
// E-mail address of the user that created this breakpoint
string user_email = 16;
// 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): `Still loading symbols...`
//
// Examples (final state):
//
// * `Invalid line number` referring to location
// * `Field f not found in class C` referring to condition
StatusMessage status = 10;
// The stack at breakpoint time.
repeated StackFrame stack_frames = 7;
// Values of evaluated expressions at breakpoint time.
// The evaluated expressions appear in exactly the same order they
// are listed in the `expressions` field.
// The `name` field holds the original expression text, the `value` or
// `members` field holds the result of the evaluated expression.
// If the expression cannot be evaluated, the `status` inside the `Variable`
// will indicate an error and contain the error text.
repeated Variable evaluated_expressions = 8;
// The `variable_table` exists to aid with computation, memory and network
// traffic optimization. It enables storing a variable once and reference
// it from multiple variables, including variables stored in the
// `variable_table` itself.
// For example, the same `this` object, which may appear at many levels of
// the stack, can have all of its data stored once in this table. The
// stack frame variables then would hold only a reference to it.
//
// The variable `var_table_index` field is an index into this repeated field.
// The stored objects are nameless and get their name from the referencing
// variable. The effective variable is a merge of the referencing variable
// and the referenced variable.
repeated Variable variable_table = 9;
// A set of custom breakpoint properties, populated by the agent, to be
// displayed to the user.
map labels = 17;
}
// Represents the application to debug. 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.
// The agents attached to the same debuggee are identified by using exactly the
// same field values when registering.
message Debuggee {
// Unique identifier for the debuggee generated by the controller service.
string id = 1;
// Project the debuggee is associated with.
// Use the project number when registering a Google Cloud Platform project.
string project = 2;
// Debuggee uniquifier within the project.
// Any string that identifies the application within the project can be used.
// Including environment and version or build IDs is recommended.
string uniquifier = 3;
// Human readable description of the debuggee.
// Including a human-readable project name, environment name and version
// information is recommended.
string description = 4;
// If set to `true`, indicates that the debuggee is considered as inactive by
// the Controller service.
bool is_inactive = 5;
// Version ID of the agent release. The version ID is structured as
// following: `domain/type/vmajor.minor` (for example
// `google.com/gcp-java/v1.1`).
string agent_version = 6;
// If set to `true`, indicates that the agent should disable itself and
// detach from the debuggee.
bool is_disabled = 7;
// 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.
StatusMessage status = 8;
// References to the locations and revisions of the source code used in the
// deployed application.
//
// NOTE: This field is deprecated. Consumers should use
// `ext_source_contexts` if it is not empty. Debug agents should populate
// both this field and `ext_source_contexts`.
repeated google.devtools.source.v1.SourceContext source_contexts = 9;
// References to the locations and revisions of the source code used in the
// deployed application.
//
// Contexts describing a remote repo related to the source code
// have a `category` label of `remote_repo`. Source snapshot source
// contexts have a `category` of `snapshot`.
repeated google.devtools.source.v1.ExtendedSourceContext ext_source_contexts = 13;
// A set of custom debuggee properties, populated by the agent, to be
// displayed to the user.
map labels = 11;
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy