diff options
Diffstat (limited to 'google/devtools/clouddebugger/v2/data.proto')
| -rw-r--r-- | google/devtools/clouddebugger/v2/data.proto | 454 |
1 files changed, 454 insertions, 0 deletions
diff --git a/google/devtools/clouddebugger/v2/data.proto b/google/devtools/clouddebugger/v2/data.proto new file mode 100644 index 000000000..c2659a9fa --- /dev/null +++ b/google/devtools/clouddebugger/v2/data.proto @@ -0,0 +1,454 @@ +// Copyright 2018 Google LLC. +// +// 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/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Debugger.V2"; +option go_package = "google.golang.org/genproto/googleapis/devtools/clouddebugger/v2;clouddebugger"; +option java_multiple_files = true; +option java_outer_classname = "DataProto"; +option java_package = "com.google.devtools.clouddebugger.v2"; +option php_namespace = "Google\\Cloud\\Debugger\\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 breakpoint and is related to its age. + BREAKPOINT_AGE = 8; + + // 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; + + // Column within a line. The first column in a line as the value `1`. + // Agents that do not support setting breakpoints on specific columns ignore + // this field. + int32 column = 3; +} + +// 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. +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, where stack_frames[0] represents the most + // recently entered function. + 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<string, string> labels = 17; +} + +// 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. +message Debuggee { + // Unique identifier for the debuggee generated by the controller service. + string id = 1; + + // Project the debuggee is associated with. + // Use project number or id when registering a Google Cloud Platform project. + string project = 2; + + // 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. + 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 Controller service does not detect any + // activity from the debuggee agents and the application is possibly stopped. + bool is_inactive = 5; + + // Version ID of the agent. + // Schema: `domain/language-platform/vmajor.minor` (for example + // `google.com/java-gcp/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. + repeated google.devtools.source.v1.SourceContext source_contexts = 9; + + // References to the locations and revisions of the source code used in the + // deployed application. + repeated google.devtools.source.v1.ExtendedSourceContext ext_source_contexts = + 13 [deprecated = true]; + + // A set of custom debuggee properties, populated by the agent, to be + // displayed to the user. + map<string, string> labels = 11; +} |