1 // Copyright 2018 Google LLC.
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
18 package google.devtools.clouddebugger.v2;
20 import "google/api/annotations.proto";
21 import "google/devtools/source/v1/source_context.proto";
22 import "google/protobuf/duration.proto";
23 import "google/protobuf/timestamp.proto";
24 import "google/protobuf/wrappers.proto";
26 option cc_enable_arenas = true;
27 option csharp_namespace = "Google.Cloud.Debugger.V2";
28 option go_package = "google.golang.org/genproto/googleapis/devtools/clouddebugger/v2;clouddebugger";
29 option java_multiple_files = true;
30 option java_outer_classname = "DataProto";
31 option java_package = "com.google.devtools.clouddebugger.v2";
32 option php_namespace = "Google\\Cloud\\Debugger\\V2";
34 // Represents a message with parameters.
35 message FormatMessage {
36 // Format template for the message. The `format` uses placeholders `$0`,
37 // `$1`, etc. to reference parameters. `$$` can be used to denote the `$`
42 // * `Failed to load '$0' which helps debug $1 the first time it
43 // is loaded. Again, $0 is very important.`
44 // * `Please pay $$10 to use $0 instead of $1.`
47 // Optional parameters to be embedded into the message.
48 repeated string parameters = 2;
51 // Represents a contextual status message.
52 // The message can indicate an error or informational status, and refer to
53 // specific parts of the containing object.
54 // For example, the `Breakpoint.status` field can indicate an error referring
55 // to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.
56 message StatusMessage {
57 // Enumerates references to which the message applies.
59 // Status doesn't refer to any particular input.
62 // Status applies to the breakpoint and is related to its location.
63 BREAKPOINT_SOURCE_LOCATION = 3;
65 // Status applies to the breakpoint and is related to its condition.
66 BREAKPOINT_CONDITION = 4;
68 // Status applies to the breakpoint and is related to its expressions.
69 BREAKPOINT_EXPRESSION = 7;
71 // Status applies to the breakpoint and is related to its age.
74 // Status applies to the entire variable.
77 // Status applies to variable value (variable name is valid).
81 // Distinguishes errors from informational messages.
84 // Reference to which the message applies.
85 Reference refers_to = 2;
87 // Status message text.
88 FormatMessage description = 3;
91 // Represents a location in the source code.
92 message SourceLocation {
93 // Path to the source file within the source context of the target binary.
96 // Line inside the file. The first line in the file has the value `1`.
99 // Column within a line. The first column in a line as the value `1`.
100 // Agents that do not support setting breakpoints on specific columns ignore
105 // Represents a variable or an argument possibly of a compound object type.
106 // Note how the following variables are represented:
108 // 1) A simple variable:
112 // { name: "x", value: "5", type: "int" } // Captured variable
114 // 2) A compound object:
122 // { // Captured variable
125 // members { name: "m1", value: "3", type: "int" },
126 // members { name: "m2", value: "7", type: "int" }
129 // 3) A pointer where the pointee was captured:
134 // { // Captured variable
137 // value: "0x00500500",
138 // members { name: "m1", value: "3", type: "int" },
139 // members { name: "m2", value: "7", type: "int" }
142 // 4) A pointer where the pointee was not captured:
146 // { // Captured variable
149 // value: "0x00400400"
150 // status { is_error: true, description { format: "unavailable" } }
153 // The status should describe the reason for the missing value,
154 // such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.
156 // Note that a null pointer should not have members.
158 // 5) An unnamed value:
160 // int* p = new int(7);
162 // { // Captured variable
164 // value: "0x00500500",
166 // members { value: "7", type: "int" } }
168 // 6) An unnamed pointer where the pointee was not captured:
170 // int* p = new int(7);
173 // { // Captured variable
175 // value: "0x00500500",
178 // value: "0x00400400",
182 // description: { format: "unavailable" } }
187 // To optimize computation, memory and network traffic, variables that
188 // repeat in the output multiple times can be stored once in a shared
189 // variable table and be referenced using the `var_table_index` field. The
190 // variables stored in the shared table are nameless and are essentially
191 // a partition of the complete variable. To reconstruct the complete
192 // variable, merge the referencing variable with the referenced variable.
194 // When using the shared variable table, the following variables:
200 // { name: "x", var_table_index: 3, type: "T" } // Captured variables
201 // { name: "p", value "0x00500500", type="T*", var_table_index: 3 }
202 // { name: "r", type="T&", var_table_index: 3 }
204 // { // Shared variable table entry #3:
205 // members { name: "m1", value: "3", type: "int" },
206 // members { name: "m2", value: "7", type: "int" }
209 // Note that the pointer address is stored with the referencing variable
210 // and not with the referenced variable. This allows the referenced variable
211 // to be shared between pointers and references.
213 // The type field is optional. The debugger agent may or may not support it.
215 // Name of the variable, if any.
218 // Simple value of the variable.
221 // Variable type (e.g. `MyClass`). If the variable is split with
222 // `var_table_index`, `type` goes next to `value`. The interpretation of
223 // a type is agent specific. It is recommended to include the dynamic type
224 // rather than a static type of an object.
227 // Members contained or pointed to by the variable.
228 repeated Variable members = 3;
230 // Reference to a variable in the shared variable table. More than
231 // one variable can reference the same variable in the table. The
232 // `var_table_index` field is an index into `variable_table` in Breakpoint.
233 google.protobuf.Int32Value var_table_index = 4;
235 // Status associated with the variable. This field will usually stay
236 // unset. A status of a single variable only applies to that variable or
237 // expression. The rest of breakpoint data still remains valid. Variables
238 // might be reported in error state even when breakpoint is not in final
241 // The message may refer to variable name with `refers_to` set to
242 // `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.
243 // In either case variable value and members will be unset.
245 // Example of error message applied to name: `Invalid expression syntax`.
247 // Example of information message applied to value: `Not captured`.
249 // Examples of error message applied to value:
251 // * `Malformed string`,
252 // * `Field f not found in class C`
253 // * `Null pointer dereference`
254 StatusMessage status = 5;
257 // Represents a stack frame context.
259 // Demangled function name at the call site.
262 // Source location of the call site.
263 SourceLocation location = 2;
265 // Set of arguments passed to this function.
266 // Note that this might not be populated for all stack frames.
267 repeated Variable arguments = 3;
269 // Set of local variables at the stack frame location.
270 // Note that this might not be populated for all stack frames.
271 repeated Variable locals = 4;
274 // Represents the breakpoint specification, status and results.
276 // Actions that can be taken when a breakpoint hits.
277 // Agents should reject breakpoints with unsupported or unknown action values.
279 // Capture stack frame and variables and update the breakpoint.
280 // The data is only captured once. After that the breakpoint is set
284 // Log each breakpoint hit. The breakpoint remains active until
285 // deleted or expired.
289 // Log severity levels.
291 // Information log message.
294 // Warning log message.
297 // Error log message.
301 // Breakpoint identifier, unique in the scope of the debuggee.
304 // Action that the agent should perform when the code at the
305 // breakpoint location is hit.
308 // Breakpoint source location.
309 SourceLocation location = 2;
311 // Condition that triggers the breakpoint.
312 // The condition is a compound boolean expression composed using expressions
313 // in a programming language at the source location.
314 string condition = 3;
316 // List of read-only expressions to evaluate at the breakpoint location.
317 // The expressions are composed using expressions in the programming language
318 // at the source location. If the breakpoint action is `LOG`, the evaluated
319 // expressions are included in log statements.
320 repeated string expressions = 4;
322 // Only relevant when action is `LOG`. Defines the message to log when
323 // the breakpoint hits. The message may include parameter placeholders `$0`,
324 // `$1`, etc. These placeholders are replaced with the evaluated value
325 // of the appropriate expression. Expressions not referenced in
326 // `log_message_format` are not logged.
328 // Example: `Message received, id = $0, count = $1` with
329 // `expressions` = `[ message.id, message.count ]`.
330 string log_message_format = 14;
332 // Indicates the severity of the log. Only relevant when action is `LOG`.
333 LogLevel log_level = 15;
335 // When true, indicates that this is a final result and the
336 // breakpoint state will not change from here on.
337 bool is_final_state = 5;
339 // Time this breakpoint was created by the server in seconds resolution.
340 google.protobuf.Timestamp create_time = 11;
342 // Time this breakpoint was finalized as seen by the server in seconds
344 google.protobuf.Timestamp final_time = 12;
346 // E-mail address of the user that created this breakpoint
347 string user_email = 16;
349 // Breakpoint status.
351 // The status includes an error flag and a human readable message.
352 // This field is usually unset. The message can be either
353 // informational or an error message. Regardless, clients should always
354 // display the text message back to the user.
356 // Error status indicates complete failure of the breakpoint.
358 // Example (non-final state): `Still loading symbols...`
360 // Examples (final state):
362 // * `Invalid line number` referring to location
363 // * `Field f not found in class C` referring to condition
364 StatusMessage status = 10;
366 // The stack at breakpoint time, where stack_frames[0] represents the most
367 // recently entered function.
368 repeated StackFrame stack_frames = 7;
370 // Values of evaluated expressions at breakpoint time.
371 // The evaluated expressions appear in exactly the same order they
372 // are listed in the `expressions` field.
373 // The `name` field holds the original expression text, the `value` or
374 // `members` field holds the result of the evaluated expression.
375 // If the expression cannot be evaluated, the `status` inside the `Variable`
376 // will indicate an error and contain the error text.
377 repeated Variable evaluated_expressions = 8;
379 // The `variable_table` exists to aid with computation, memory and network
380 // traffic optimization. It enables storing a variable once and reference
381 // it from multiple variables, including variables stored in the
382 // `variable_table` itself.
383 // For example, the same `this` object, which may appear at many levels of
384 // the stack, can have all of its data stored once in this table. The
385 // stack frame variables then would hold only a reference to it.
387 // The variable `var_table_index` field is an index into this repeated field.
388 // The stored objects are nameless and get their name from the referencing
389 // variable. The effective variable is a merge of the referencing variable
390 // and the referenced variable.
391 repeated Variable variable_table = 9;
393 // A set of custom breakpoint properties, populated by the agent, to be
394 // displayed to the user.
395 map<string, string> labels = 17;
398 // Represents the debugged application. The application may include one or more
399 // replicated processes executing the same code. Each of these processes is
400 // attached with a debugger agent, carrying out the debugging commands.
401 // Agents attached to the same debuggee identify themselves as such by using
402 // exactly the same Debuggee message value when registering.
404 // Unique identifier for the debuggee generated by the controller service.
407 // Project the debuggee is associated with.
408 // Use project number or id when registering a Google Cloud Platform project.
411 // Uniquifier to further distinguish the application.
412 // It is possible that different applications might have identical values in
413 // the debuggee message, thus, incorrectly identified as a single application
414 // by the Controller service. This field adds salt to further distinguish the
415 // application. Agents should consider seeding this field with value that
416 // identifies the code, binary, configuration and environment.
417 string uniquifier = 3;
419 // Human readable description of the debuggee.
420 // Including a human-readable project name, environment name and version
421 // information is recommended.
422 string description = 4;
424 // If set to `true`, indicates that Controller service does not detect any
425 // activity from the debuggee agents and the application is possibly stopped.
426 bool is_inactive = 5;
428 // Version ID of the agent.
429 // Schema: `domain/language-platform/vmajor.minor` (for example
430 // `google.com/java-gcp/v1.1`).
431 string agent_version = 6;
433 // If set to `true`, indicates that the agent should disable itself and
434 // detach from the debuggee.
435 bool is_disabled = 7;
437 // Human readable message to be displayed to the user about this debuggee.
438 // Absence of this field indicates no status. The message can be either
439 // informational or an error status.
440 StatusMessage status = 8;
442 // References to the locations and revisions of the source code used in the
443 // deployed application.
444 repeated google.devtools.source.v1.SourceContext source_contexts = 9;
446 // References to the locations and revisions of the source code used in the
447 // deployed application.
448 repeated google.devtools.source.v1.ExtendedSourceContext ext_source_contexts =
449 13 [deprecated = true];
451 // A set of custom debuggee properties, populated by the agent, to be
452 // displayed to the user.
453 map<string, string> labels = 11;