google-cloud-debugger 0.40.0

data/lib/google/cloud/debugger/agent.rb

@@ -0,0 +1,255 @@
+# 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.
+
+
+require "google/cloud/debugger/breakpoint_manager"
+require "google/cloud/debugger/debuggee"
+require "google/cloud/debugger/debugger_c"
+require "google/cloud/debugger/tracer"
+require "google/cloud/debugger/transmitter"
+require "google/cloud/logging"
+require "stackdriver/core/async_actor"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Agent
+      #
+      # The Stackdriver Debugger Agent runs on the same system where a debuggee
+      # application is running. The agent is responsible for sending state data,
+      # such as the value of program variables and the call stack, to
+      # Stackdriver Debugger when the code at a breakpoint location is executed.
+      #
+      # The Debugger Agent runs in its own child thread when started. It ensures
+      # the instrumented application is registered properly and constantly
+      # monitors for any active breakpoints. Once the agent gets updated with
+      # active breakpoints from Stackdriver Debugger service, it facilitates
+      # the breakpoints in application requests thread, then transport the
+      # result snapshot back to Stackdriver Debugger service asynchronously.
+      #
+      # @example
+      #   require "google/cloud/debugger"
+      #
+      #   debugger = Google::Cloud::Debugger.new
+      #   agent = debugger.agent
+      #   agent.start
+      #
+      class Agent
+        ##
+        # Name of the logpoints log file.
+        DEFAULT_LOG_NAME = "debugger_logpoints".freeze
+
+        ##
+        # @private Debugger Agent is an asynchronous actor
+        include Stackdriver::Core::AsyncActor
+
+        ##
+        # @private The gRPC Service object.
+        attr_reader :service
+
+        ##
+        # The gRPC Debuggee representation of the debuggee application. It
+        # contains identification information to match running application to
+        # specific Cloud Source Repository code base, and correctly group
+        # same versions of the debuggee application together through a generated
+        # unique identifier.
+        # @return [Google::Cloud::Debugger::Debuggee]
+        attr_reader :debuggee
+
+        ##
+        # It manages syncing breakpoints between the Debugger Agent and
+        # Stackdriver Debugger service
+        # @return [Google::Cloud::Debugger::BreakpointManager]
+        attr_reader :breakpoint_manager
+
+        ##
+        # It monitors the debuggee application and triggers breakpoint
+        # evaluation when breakpoints are set.
+        # @return [Google::Cloud::Debugger::Tracer]
+        attr_reader :tracer
+
+        ##
+        # It sends evaluated breakpoints snapshot back to Stackdriver Debugger
+        # Service.
+        # @return [Google::Cloud::Debugger::Transmiter]
+        attr_reader :transmitter
+
+        ##
+        # The logger used to write the results of Logpoints.
+        attr_accessor :logger
+
+        ##
+        # A quota tracking object helps tracking resource consumption during
+        # evaluations.
+        attr_accessor :quota_manager
+
+        ##
+        # Absolute path to the debuggee Ruby application root directory. The
+        # Stackdriver Debugger service creates canonical breakpoints with only
+        # relative path. So the debugger agent combines the relative path to
+        # the application directory to trace and evaluate breakpoints.
+        # @return [String]
+        attr_accessor :app_root
+
+        ##
+        # @private The last exception captured in the agent child thread
+        attr_reader :last_exception
+
+        ##
+        # Create a new Debugger Agent instance.
+        #
+        # @param [Google::Cloud::Debugger::Service] service The gRPC Service
+        #   object
+        # @param [Google::Cloud::Logging::Logger] logger The logger used
+        #   to write the results of Logpoints.
+        # @param [String] service_name Name for the debuggee application.
+        # @param [String] service_version Version identifier for the debuggee
+        #   application.
+        # @param [String] app_root Absolute path to the root directory of
+        #   the debuggee application. Default to Rack root.
+        #
+        def initialize service, logger: nil, service_name:, service_version:,
+                       app_root: nil
+          super()
+
+          @service = service
+          @debuggee = Debuggee.new service, service_name: service_name,
+                                            service_version: service_version
+          @tracer = Debugger::Tracer.new self
+          @breakpoint_manager = BreakpointManager.new self, service
+          @breakpoint_manager.on_breakpoints_change =
+            method :breakpoints_change_callback
+
+          @transmitter = Transmitter.new self, service
+
+          @logger = logger || default_logger
+
+          init_app_root app_root
+
+          # Agent actor thread needs to force exit immediately.
+          set_cleanup_options timeout: 0
+        end
+
+        ##
+        # Starts the Debugger Agent in a child thread, where debuggee
+        # application registration and breakpoints querying will take place.
+        # It also starts the transmitter in another child thread.
+        #
+        def start
+          transmitter.start
+          async_start
+        end
+
+        ##
+        # Stops and terminates the Debugger Agent. It also properly shuts down
+        # transmitter and tracer.
+        #
+        # Once Debugger Agent is stopped, it cannot be started again.
+        #
+        def stop
+          transmitter.stop
+          async_stop
+        end
+
+        ##
+        # Stops the tracer regardless of whether any active breakpoints are
+        # present. Once the tracer stops monitoring the debuggee application,
+        # the application can return to normal performance.
+        def stop_tracer
+          tracer.stop
+        end
+
+        ##
+        # @private Callback function for AsyncActor module that kicks off
+        # the asynchronous job in a loop.
+        def run_backgrounder
+          sync_breakpoints = ensure_debuggee_registration
+
+          if sync_breakpoints
+            sync_result =
+              breakpoint_manager.sync_active_breakpoints debuggee.id
+            debuggee.revoke_registration unless sync_result
+          end
+        rescue StandardError => e
+          warn ["#{e.class}: #{e.message}", e.backtrace].join("\n\t")
+          @last_exception = e
+        end
+
+        ##
+        # @private Callback function when the async actor thread state changes
+        def on_async_state_change
+          if async_running?
+            tracer.start
+          else
+            tracer.stop
+          end
+        end
+
+        private
+
+        ##
+        # @private Initialize `@app_root` instance variable.
+        def init_app_root app_root = nil
+          app_root ||= Google::Cloud::Debugger.configure.app_root
+          app_root ||= Rack::Directory.new("").root if defined? Rack::Directory
+          app_root ||= Dir.pwd
+
+          @app_root = app_root
+        end
+
+        ##
+        # @private Callback function for breakpoint manager when any updates
+        # happens to the list of active breakpoints
+        def breakpoints_change_callback active_breakpoints
+          if active_breakpoints.empty?
+            tracer.stop
+          else
+            tracer.start
+          end
+        end
+
+        ##
+        # @private Helper method to register the debuggee application if not
+        # registered already.
+        def ensure_debuggee_registration
+          if debuggee.registered?
+            registration_result = true
+          else
+            registration_result = debuggee.register
+            if registration_result
+              puts "Debuggee #{debuggee.id} successfully registered"
+            end
+          end
+
+          registration_result
+        end
+
+        ##
+        # @private Create a default logger
+        def default_logger
+          project_id = @service.project
+          credentials = @service.credentials
+          logging = Google::Cloud::Logging::Project.new(
+            Google::Cloud::Logging::Service.new(project_id, credentials)
+          )
+          resource =
+            Google::Cloud::Logging::Middleware.build_monitored_resource
+
+          logging.logger DEFAULT_LOG_NAME, resource
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/debugger/backoff.rb

@@ -0,0 +1,70 @@
+# 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 Cloud
+    module Debugger
+      ##
+      # @private Helps keep tracking of backoff on calling APIs in loop
+      class Backoff
+        ##
+        # Small interval to start with
+        DEFAULT_START_INTERVAL = 1
+
+        ##
+        # Maximum interval value to use
+        DEFAULT_MAX_INTERVAL = 600
+
+        ##
+        # Interval incremental multiplier
+        DEFAULT_MULTIPLIER = 2
+
+        ##
+        # The current time interval should wait until next iteration
+        attr_reader :interval
+
+        def initialize start_interval = DEFAULT_START_INTERVAL,
+                       max_interval = DEFAULT_MAX_INTERVAL,
+                       multiplier = DEFAULT_MULTIPLIER
+          @start_interval = start_interval
+          @max_interval = max_interval
+          @multiplier = multiplier
+        end
+
+        ##
+        # Resets backoff
+        def succeeded
+          @interval = nil
+        end
+
+        ##
+        # Initialize backoff or increase backoff interval
+        def failed
+          @interval = if @interval
+                        [@max_interval, @interval * @multiplier].min
+                      else
+                        @start_interval
+                      end
+        end
+
+        ##
+        # Check if a backoff delay should be applied
+        def backing_off?
+          !@interval.nil?
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/debugger/breakpoint.rb

@@ -0,0 +1,443 @@
+# 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.
+
+
+require "time"
+require "google/cloud/debugger/breakpoint/evaluator"
+require "google/cloud/debugger/breakpoint/source_location"
+require "google/cloud/debugger/breakpoint/stack_frame"
+require "google/cloud/debugger/breakpoint/status_message"
+require "google/cloud/debugger/breakpoint/validator"
+require "google/cloud/debugger/breakpoint/variable"
+require "google/cloud/debugger/breakpoint/variable_table"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Breakpoint
+      #
+      # Abstract class that represents a breakpoint, which can be set and
+      # triggered in a debuggee application. Maps to gRPC struct
+      # {Google::Cloud::Debugger::V2::Breakpoint}.
+      #
+      class Breakpoint
+        include MonitorMixin
+
+        ##
+        # Breakpoint identifier, unique in the scope of the debuggee.
+        attr_accessor :id
+
+        ##
+        # Action to take when a breakpoint is hit. Either :CAPTURE or :LOG.
+        # @return [Symbol]
+        attr_accessor :action
+
+        ##
+        # Absolute path to the debuggee Ruby application root directory.
+        # @return [String]
+        attr_accessor :app_root
+
+        ##
+        # 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
+        # logMessageFormat are not logged.
+        attr_accessor :log_message_format
+
+        ##
+        # Indicates the severity of the log. Only relevant when action is LOG.
+        attr_accessor :log_level
+
+        ##
+        # The evaluated log message when action is LOG.
+        attr_accessor :evaluated_log_message
+
+        ##
+        # Breakpoint source location.
+        # @return [Google::Cloud::Debugger::Breakpoint::SourceLocation]
+        attr_accessor :location
+
+        ##
+        # Condition that triggers the breakpoint. The condition is a compound
+        # boolean expression composed using expressions in a programming
+        # language at the source location.
+        attr_accessor :condition
+
+        ##
+        # When true, indicates that this is a final result and the breakpoint
+        # state will not change from here on.
+        # @return [Boolean]
+        attr_accessor :is_final_state
+
+        ##
+        # 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.
+        # @return [Array<String>]
+        attr_accessor :expressions
+
+        ##
+        # 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.
+        # @return [Array<Google::Cloud::Debugger::Breakpoint::Variable>]
+        attr_accessor :evaluated_expressions
+
+        ##
+        # Time this breakpoint was created by the server in seconds resolution.
+        # @return [Time]
+        attr_accessor :create_time
+
+        ##
+        # Time this breakpoint was finalized as seen by the server in seconds
+        # resolution.
+        # @return [Time]
+        attr_accessor :final_time
+
+        ##
+        # E-mail address of the user that created this breakpoint
+        attr_accessor :user_email
+
+        ##
+        # 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.
+        attr_accessor :status
+
+        ##
+        # 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.
+        attr_accessor :variable_table
+
+        ##
+        # A set of custom breakpoint properties, populated by the agent, to be
+        # displayed to the user.
+        # @return [Hash<String, String>]
+        attr_accessor :labels
+
+        ##
+        # The stack at breakpoint time.
+        # @return [Array<Google::Cloud::Debugger::Breakpoint::StackFrame>]
+        attr_accessor :stack_frames
+
+        ##
+        # @private Construct a new instance of Breakpoint.
+        def initialize id = nil, path = nil, line = nil
+          super()
+
+          @id = id
+          @action = :CAPTURE
+          # Use relative path for SourceLocation, because that's how the server
+          # side canonical breakpoints are defined.
+          @location = SourceLocation.new.tap do |sl|
+            sl.path = path
+            sl.line = line.to_i
+          end
+          @expressions = []
+          @evaluated_expressions = []
+          @stack_frames = []
+          @labels = {}
+          @variable_table = VariableTable.new
+        end
+
+        ##
+        # @private New Google::Cloud::Debugger::Breakpoint
+        # from a Google::Cloud::Debugger::V2::Breakpoint object.
+        def self.from_grpc grpc
+          return new if grpc.nil?
+
+          breakpoint = grpc.action == :LOG ? Logpoint.new : Snappoint.new
+          breakpoint.tap do |b|
+            b.id = grpc.id
+            b.action = grpc.action
+            b.condition = grpc.condition
+            b.expressions = grpc.expressions.to_a
+            b.labels = hashify_labels grpc.labels
+            b.log_message_format = grpc.log_message_format
+            b.log_level = grpc.log_level
+            b.is_final_state = grpc.is_final_state
+            b.user_email = grpc.user_email
+
+            assign_complex_grpc_fields grpc, b
+          end
+        end
+
+        ##
+        # @private Helper method that helps extracting complex fields from
+        # grpc struct into a breakpoint.
+        def self.assign_complex_grpc_fields grpc, breakpoint
+          breakpoint.create_time = timestamp_from_grpc grpc.create_time
+          breakpoint.evaluated_expressions =
+            Breakpoint::Variable.from_grpc_list grpc.evaluated_expressions
+          breakpoint.final_time = timestamp_from_grpc grpc.final_time
+          breakpoint.location =
+            Breakpoint::SourceLocation.from_grpc grpc.location
+          breakpoint.stack_frames = stack_frames_from_grpc grpc
+          breakpoint.status = Breakpoint::StatusMessage.from_grpc grpc.status
+          breakpoint.variable_table =
+            Breakpoint::VariableTable.from_grpc grpc.variable_table
+        end
+
+        ##
+        # @private Extract array of stack_frame from grpc
+        def self.stack_frames_from_grpc grpc
+          return nil if grpc.stack_frames.nil?
+          grpc.stack_frames.map { |sf| Breakpoint::StackFrame.from_grpc sf }
+        end
+
+        ##
+        # @private Get a Time object from a Google::Protobuf::Timestamp object.
+        def self.timestamp_from_grpc grpc_timestamp
+          return nil if grpc_timestamp.nil?
+          Time.at grpc_timestamp.seconds, Rational(grpc_timestamp.nanos, 1000)
+        end
+
+        ##
+        # @private Helper method to convert a gRPC map to Ruby Hash
+        def self.hashify_labels grpc_labels
+          if grpc_labels.respond_to? :to_h
+            grpc_labels.to_h
+          else
+            # Enumerable doesn't have to_h on ruby 2.0...
+            Hash[grpc_labels.to_a]
+          end
+        end
+
+        private_class_method :stack_frames_from_grpc,
+                             :timestamp_from_grpc,
+                             :hashify_labels,
+                             :assign_complex_grpc_fields
+
+        ##
+        # Marks a breakpoint as complete if this breakpoint isn't completed
+        # already. Set @is_final_state to true and set @final_time.
+        def complete
+          synchronize do
+            return if complete?
+
+            @is_final_state = true
+            @final_time = Time.now
+          end
+        end
+
+        ##
+        # Check if the breakpoint has been evaluated or set to a final error
+        # state.
+        def complete?
+          is_final_state ? true : false
+        end
+
+        ##
+        # Check if the breakpoint is valid or not. Invoke validation function
+        # if breakpoint hasn't been finallized yet.
+        def valid?
+          Validator.validate self unless complete?
+
+          status && status.is_error ? false : true
+        end
+
+        ##
+        # Get the file path of this breakpoint
+        # @example
+        #   breakpoint =
+        #     Google::Cloud::Debugger::Breakpoint.new nil, "path/to/file.rb"
+        #   breakpoint.path #=> "path/to/file.rb"
+        # @return [String] The file path for this breakpoint
+        def path
+          location.nil? ? nil : location.path
+        end
+
+        ##
+        # Get the line number of this breakpoint
+        # @example
+        #   breakpoint =
+        #     Google::Cloud::Debugger::Breakpoint.new nil, "path/to/file.rb", 11
+        #   breakpoint.line #=> 11
+        # @return [Integer] The line number for this breakpoint
+        def line
+          location.nil? ? nil : location.line
+        end
+
+        ##
+        # Evaluate the breakpoint's condition expression against a given binding
+        # object. Returns true if the condition expression evalutes to true or
+        # there isn't a condition; otherwise false. Set breakpoint to error
+        # state if exception happens.
+        #
+        # @param [Binding] binding A Ruby Binding object
+        # @return [Boolean] True if condition evalutes to true or there isn't a
+        #   condition. False if condition evaluates to false or error raised
+        #   during evaluation.
+        def check_condition binding
+          return true if condition.nil? || condition.empty?
+          condition_result =
+            Evaluator.readonly_eval_expression binding, condition
+
+          if condition_result.is_a?(Exception) &&
+             condition_result.instance_variable_get(:@mutation_cause)
+            set_error_state "Error: #{condition_result.message}",
+                            refers_to: StatusMessage::BREAKPOINT_CONDITION
+
+            return false
+          end
+
+
+          condition_result ? true : false
+        rescue StandardError => e
+          set_error_state "Error: #{e.message}",
+                          refers_to: StatusMessage::BREAKPOINT_CONDITION
+          false
+        end
+
+        ##
+        # Check if two breakpoints are equal to each other
+        def eql? other
+          id == other.id &&
+            path == other.path &&
+            line == other.line
+        end
+
+        ##
+        # @private Override default hashing function
+        def hash
+          id.hash ^ path.hash ^ line.hash
+        end
+
+        ##
+        # @private Exports the Breakpoint to a
+        # Google::Cloud::Debugger::V2::Breakpoint object.
+        def to_grpc
+          Google::Cloud::Debugger::V2::Breakpoint.new(
+            id: id.to_s,
+            location: location.to_grpc,
+            condition: condition.to_s,
+            expressions: expressions || [],
+            is_final_state: is_final_state,
+            create_time: timestamp_to_grpc(create_time),
+            final_time: timestamp_to_grpc(final_time),
+            user_email: user_email.to_s,
+            stack_frames: stack_frames_to_grpc,
+            evaluated_expressions: evaluated_expressions_to_grpc,
+            status: status_to_grpc,
+            labels: labels_to_grpc,
+            variable_table: variable_table.to_grpc
+          )
+        end
+
+        ##
+        # Set breakpoint to an error state, which initializes the @status
+        # instance variable with the error message. Also mark this breakpoint as
+        # completed if is_final is true.
+        #
+        # @param [String] message The error message
+        # @param [Symbol] refers_to Enum that specifies what the error refers
+        #   to. Defaults :UNSPECIFIED. See {Breakpoint::StatusMessage} class for
+        #   list of possible values
+        # @param [Boolean] is_final Marks the breakpoint as final if true.
+        #   Defaults true.
+        #
+        # @return [Google::Cloud::Debugger::Breakpoint::StatusMessage] The grpc
+        #   StatusMessage object, which describes the breakpoint's error state.
+        def set_error_state message, refers_to: StatusMessage::UNSPECIFIED,
+                            is_final: true
+          @status = StatusMessage.new.tap do |s|
+            s.is_error = true
+            s.refers_to = refers_to
+            s.description = message
+          end
+
+          complete if is_final
+
+          @status
+        end
+
+        ##
+        # Get full absolute file path by combining the relative file path
+        # with application root directory path.
+        def full_path
+          if app_root.nil? || app_root.empty?
+            path
+          else
+            File.join app_root, path
+          end
+        end
+
+        private
+
+        ##
+        # @private Formats the labels so they can be saved to a
+        # Google::Cloud::Debugger::V2::Breakpoint object.
+        def labels_to_grpc
+          # Coerce symbols to strings
+          Hash[labels.map do |k, v|
+            [String(k), String(v)]
+          end]
+        end
+
+        ##
+        # @private Exports the Breakpoint stack_frames to an array of
+        # Google::Cloud::Debugger::V2::StackFrame objects.
+        def stack_frames_to_grpc
+          stack_frames.nil? ? [] : stack_frames.map(&:to_grpc)
+        end
+
+        ##
+        # @private Exports the Breakpoint stack_frames to an array of
+        # Google::Cloud::Debugger::V2::Variable objects.
+        def evaluated_expressions_to_grpc
+          evaluated_expressions.nil? ? [] : evaluated_expressions.map(&:to_grpc)
+        end
+
+        ##
+        # @private Exports Breakpoint status to
+        # Google::Cloud::Debugger::V2::StatusMessage object
+        def status_to_grpc
+          status.nil? ? nil : status.to_grpc
+        end
+
+        ##
+        # @private Formats the timestamp as a Google::Protobuf::Timestamp
+        # object.
+        def timestamp_to_grpc time
+          return nil if time.nil?
+          Google::Protobuf::Timestamp.new(
+            seconds: time.to_i,
+            nanos: time.nsec
+          )
+        end
+      end
+    end
+  end
+end