# Copyright 2017 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 # # https://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. module Google module Devtools module Clouddebugger module V2 # Represents a message with parameters. # @!attribute [rw] format # @return [String] # 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.+ # @!attribute [rw] parameters # @return [Array] # Optional parameters to be embedded into the message. class FormatMessage; end # 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+. # @!attribute [rw] is_error # @return [true, false] # Distinguishes errors from informational messages. # @!attribute [rw] refers_to # @return [Google::Devtools::Clouddebugger::V2::StatusMessage::Reference] # Reference to which the message applies. # @!attribute [rw] description # @return [Google::Devtools::Clouddebugger::V2::FormatMessage] # Status message text. class StatusMessage # Enumerates references to which the message applies. module 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 end end # Represents a location in the source code. # @!attribute [rw] path # @return [String] # Path to the source file within the source context of the target binary. # @!attribute [rw] line # @return [Integer] # Line inside the file. The first line in the file has the value +1+. class SourceLocation; end # 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. # @!attribute [rw] name # @return [String] # Name of the variable, if any. # @!attribute [rw] value # @return [String] # Simple value of the variable. # @!attribute [rw] type # @return [String] # 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. # @!attribute [rw] members # @return [Array] # Members contained or pointed to by the variable. # @!attribute [rw] var_table_index # @return [Google::Protobuf::Int32Value] # 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. # @!attribute [rw] status # @return [Google::Devtools::Clouddebugger::V2::StatusMessage] # 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+ class Variable; end # Represents a stack frame context. # @!attribute [rw] function # @return [String] # Demangled function name at the call site. # @!attribute [rw] location # @return [Google::Devtools::Clouddebugger::V2::SourceLocation] # Source location of the call site. # @!attribute [rw] arguments # @return [Array] # Set of arguments passed to this function. # Note that this might not be populated for all stack frames. # @!attribute [rw] locals # @return [Array] # Set of local variables at the stack frame location. # Note that this might not be populated for all stack frames. class StackFrame; end # Represents the breakpoint specification, status and results. # @!attribute [rw] id # @return [String] # Breakpoint identifier, unique in the scope of the debuggee. # @!attribute [rw] action # @return [Google::Devtools::Clouddebugger::V2::Breakpoint::Action] # Action that the agent should perform when the code at the # breakpoint location is hit. # @!attribute [rw] location # @return [Google::Devtools::Clouddebugger::V2::SourceLocation] # Breakpoint source location. # @!attribute [rw] condition # @return [String] # Condition that triggers the breakpoint. # The condition is a compound boolean expression composed using expressions # in a programming language at the source location. # @!attribute [rw] expressions # @return [Array] # 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. # @!attribute [rw] log_message_format # @return [String] # 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 ]+. # @!attribute [rw] log_level # @return [Google::Devtools::Clouddebugger::V2::Breakpoint::LogLevel] # Indicates the severity of the log. Only relevant when action is +LOG+. # @!attribute [rw] is_final_state # @return [true, false] # When true, indicates that this is a final result and the # breakpoint state will not change from here on. # @!attribute [rw] create_time # @return [Google::Protobuf::Timestamp] # Time this breakpoint was created by the server in seconds resolution. # @!attribute [rw] final_time # @return [Google::Protobuf::Timestamp] # Time this breakpoint was finalized as seen by the server in seconds # resolution. # @!attribute [rw] user_email # @return [String] # E-mail address of the user that created this breakpoint # @!attribute [rw] status # @return [Google::Devtools::Clouddebugger::V2::StatusMessage] # 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 # @!attribute [rw] stack_frames # @return [Array] # The stack at breakpoint time. # @!attribute [rw] evaluated_expressions # @return [Array] # 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. # @!attribute [rw] variable_table # @return [Array] # 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. # @!attribute [rw] labels # @return [Hash{String => String}] # A set of custom breakpoint properties, populated by the agent, to be # displayed to the user. class Breakpoint # Actions that can be taken when a breakpoint hits. # Agents should reject breakpoints with unsupported or unknown action values. module 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 end # Log severity levels. module LogLevel # Information log message. INFO = 0 # Warning log message. WARNING = 1 # Error log message. ERROR = 2 end end # 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. # @!attribute [rw] id # @return [String] # Unique identifier for the debuggee generated by the controller service. # @!attribute [rw] project # @return [String] # Project the debuggee is associated with. # Use project number or id when registering a Google Cloud Platform project. # @!attribute [rw] uniquifier # @return [String] # Uniquifier to further distiguish 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 distiguish the # application. Agents should consider seeding this field with value that # identifies the code, binary, configuration and environment. # @!attribute [rw] description # @return [String] # Human readable description of the debuggee. # Including a human-readable project name, environment name and version # information is recommended. # @!attribute [rw] is_inactive # @return [true, false] # If set to +true+, indicates that Controller service does not detect any # activity from the debuggee agents and the application is possibly stopped. # @!attribute [rw] agent_version # @return [String] # Version ID of the agent. # Schema: +domain/language-platform/vmajor.minor+ (for example # +google.com/java-gcp/v1.1+). # @!attribute [rw] is_disabled # @return [true, false] # If set to +true+, indicates that the agent should disable itself and # detach from the debuggee. # @!attribute [rw] status # @return [Google::Devtools::Clouddebugger::V2::StatusMessage] # 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. # @!attribute [rw] source_contexts # @return [Array] # References to the locations and revisions of the source code used in the # deployed application. # @!attribute [rw] ext_source_contexts # @return [Array] # References to the locations and revisions of the source code used in the # deployed application. # # NOTE: this field is experimental and can be ignored. # @!attribute [rw] labels # @return [Hash{String => String}] # A set of custom debuggee properties, populated by the agent, to be # displayed to the user. class Debuggee; end end end end end