google-cloud-debugger 0.40.0

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

@@ -0,0 +1,208 @@
+# 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"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Snappoint
+      #
+      # A kind of {Google::Cloud::Debugger::Breakpoint} that can be evaluated
+      # to capture the state of the program at time of evaluation. This is
+      # essentially a {Google::Cloud::Debugger::Breakpoint} with action attrubte
+      # set to `:CAPTURE`
+      #
+      class Snappoint < Breakpoint
+        ##
+        # Max number of top stacks to collect local variables information
+        STACK_EVAL_DEPTH = 5
+
+        ##
+        # Max size of payload a Snappoint collects
+        MAX_PAYLOAD_SIZE = 32768 # 32KB
+
+        ##
+        # @private Max size an evaluated expression variable is allowed to be
+        MAX_EXPRESSION_LIMIT = 32768 # 32KB
+
+        ##
+        # @private Max size a normal evaluated variable is allowed to be
+        MAX_VAR_LIMIT = 1024 # 1KB
+
+        ##
+        # @private Construct a new Snappoint instance.
+        def initialize *args
+          super
+
+          init_var_table
+        end
+
+        ##
+        # @private Initialize the variable table by inserting a buffer full
+        # variable at index 0. This variable will be shared by other variable
+        # evaluations if this Snappoint exceeds size limit.
+        def init_var_table
+          return if @variable_table[0] &&
+                    @variable_table[0].buffer_full_variable?
+
+          buffer_full_var = Variable.buffer_full_variable
+          @variable_table.variables.unshift buffer_full_var
+        end
+
+        ##
+        # Evaluate the breakpoint unless it's already marked as completed.
+        # Store evaluted expressions and stack frame variables in
+        # @evaluated_expressions, @stack_frames. Mark breakpoint complete if
+        # successfully evaluated.
+        #
+        # @param [Array<Binding>] call_stack_bindings An array of Ruby Binding
+        #   objects, from the call stack that leads to the triggering of the
+        #   breakpoints.
+        #
+        # @return [Boolean] True if evaluated successfully; false otherwise.
+        #
+        def evaluate call_stack_bindings
+          synchronize do
+            top_binding = call_stack_bindings[0]
+
+            return false if complete? || !check_condition(top_binding)
+
+            begin
+              eval_expressions top_binding
+              eval_call_stack call_stack_bindings
+
+              complete
+            rescue StandardError
+              return false
+            end
+          end
+
+          true
+        end
+
+        ##
+        # @private Evaluates the breakpoint expressions at the point that
+        # triggered the breakpoint. The expressions subject to the read-only
+        # rules. If the expressions do any write operations, the evaluations
+        # abort and show an error message in place of the real result.
+        #
+        # @param [Binding] bind The binding object from the context
+        #
+        def eval_expressions bind
+          @evaluated_expressions = []
+
+          expressions.each do |expression|
+            eval_result = Evaluator.readonly_eval_expression bind, expression
+
+            if eval_result.is_a?(Exception) &&
+               eval_result.instance_variable_get(:@mutation_cause)
+              evaluated_var = Variable.new
+              evaluated_var.name = expression
+              evaluated_var.set_error_state \
+                "Error: #{eval_result.message}",
+                refers_to: StatusMessage::VARIABLE_VALUE
+            else
+              evaluated_var = convert_variable eval_result,
+                                               name: expression,
+                                               limit: MAX_EXPRESSION_LIMIT
+            end
+
+            @evaluated_expressions << evaluated_var
+          end
+        end
+
+        ##
+        # @private Evaluates call stack. Collects function name and location of
+        # each frame from given binding objects. Collects local variable
+        # information from top frames.
+        #
+        # @param [Array<Binding>] call_stack_bindings A list of binding
+        #   objects that come from each of the call stack frames.
+        # @return [Array<Google::Cloud::Debugger::Breakpoint::StackFrame>]
+        #   A list of StackFrame objects that represent state of the
+        #   call stack
+        #
+        def eval_call_stack call_stack_bindings
+          @stack_frames = []
+
+          call_stack_bindings.each_with_index do |frame_binding, i|
+            frame_info = StackFrame.new.tap do |sf|
+              sf.function = frame_binding.eval("__method__").to_s
+              sf.location = SourceLocation.new.tap do |l|
+                l.path =
+                  frame_binding.eval "::File.absolute_path(__FILE__)"
+                l.line = frame_binding.eval "__LINE__"
+              end
+            end
+
+            @stack_frames << frame_info
+
+            next if i >= STACK_EVAL_DEPTH
+
+            frame_binding.local_variables.each do |local_var_name|
+              local_var = frame_binding.local_variable_get local_var_name
+              var = convert_variable local_var, name: local_var_name,
+                                                limit: MAX_VAR_LIMIT
+
+              frame_info.locals << var
+            end
+          end
+        end
+
+        private
+
+        ##
+        # @private Compute the total size of all the evaluated variables in
+        # this breakpoint.
+        def calculate_total_size
+          result = evaluated_expressions.inject 0 do |sum, exp|
+            sum + exp.payload_size
+          end
+
+          stack_frames.each do |stack_frame|
+            result = stack_frame.locals.inject result do |sum, local|
+              sum + local.payload_size
+            end
+          end
+
+          result = variable_table.variables.inject result do |sum, var|
+            sum + var.payload_size
+          end
+
+          result
+        end
+
+        ##
+        # @private Translate a Ruby variable into a {Breakpoint::Variable}.
+        # If the existing evaluated variables already exceed maximum allowed
+        # size, then return a buffer full warning variable instead.
+        def convert_variable source, name: nil, limit: nil
+          current_total_size = calculate_total_size
+          var = Variable.from_rb_var source, name: name, limit: limit,
+                                             var_table: variable_table
+
+          if (current_total_size + var.payload_size <= MAX_PAYLOAD_SIZE) ||
+             var.reference_variable?
+            var
+          else
+            Breakpoint::Variable.buffer_full_variable variable_table, name: name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# 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 "binding_of_caller"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Tracer
+      #
+      # When active breakpoints are set for the debugger, the tracer monitors
+      # the running Ruby application and triggers evaluation when the code is
+      # executed at the breakpoint locations.
+      #
+      # The tracer tracks the running application using several Ruby TracePoints
+      # and C level Ruby debugging API.
+      #
+      class Tracer
+        ##
+        # The debugger agent this tracer belongs to
+        # @return [Google::Cloud::Debugger::Agent]
+        attr_reader :agent
+
+        ##
+        # @private File tracing point that enables line tracing when program
+        # counter enters a file that contains breakpoints
+        attr_reader :file_tracepoint
+
+        ##
+        # @private Fiber tracing point that enables line tracing when program
+        # counter enters a file that contains breakpoints through fiber
+        # switching
+        attr_reader :fiber_tracepoint
+
+        ##
+        # @private A nested hash structure represent all the active breakpoints.
+        # The structure is optimized for fast access. For example:
+        # {
+        #   "path/to/file.rb" => {                     # The absolute file path
+        #     123 => [                                 # The line number in file
+        #       <Google::Cloud::Debugger::Breakpoint>  # List of breakpoints
+        #     ]
+        #   }
+        # }
+        attr_reader :breakpoints_cache
+
+        ##
+        # @private Construct a new instance of Tracer
+        def initialize agent
+          @agent = agent
+          @file_tracepoint = nil
+          @fiber_tracepoint = nil
+          @breakpoints_cache = {}
+        end
+
+        ##
+        # Update tracer's private breakpoints cache with the list of active
+        # breakpoints from BreakpointManager.
+        #
+        # This methood is atomic for thread safety purpose.
+        def update_breakpoints_cache
+          active_breakpoints = agent.breakpoint_manager.active_breakpoints.dup
+          breakpoints_hash = {}
+
+          active_breakpoints.each do |active_breakpoint|
+            breakpoint_line = active_breakpoint.line
+            breakpoint_path = active_breakpoint.full_path
+            breakpoints_hash[breakpoint_path] ||= {}
+            breakpoints_hash[breakpoint_path][breakpoint_line] ||= []
+            breakpoints_hash[breakpoint_path][breakpoint_line].push(
+              active_breakpoint
+            )
+          end
+
+          # Tracer is explicitly designed to not have a lock. This should be the
+          # only place writing @breakpoints_cache to ensure thread safety.
+          @breakpoints_cache = breakpoints_hash
+        end
+
+        ##
+        # Callback function when a set of breakpoints are hit. Handover the hit
+        # breakpoint to breakpoint_manager to be evaluated.
+        def breakpoints_hit breakpoints, call_stack_bindings
+          breakpoints.each do |breakpoint|
+            # Stop evaluating breakpoints if we have quotas and the quotas are
+            # met.
+            break if agent.quota_manager && !agent.quota_manager.more?
+
+            next if breakpoint.nil? || breakpoint.complete?
+
+            time_begin = Time.now
+
+            agent.breakpoint_manager.breakpoint_hit breakpoint,
+                                                    call_stack_bindings
+
+            # Report time and resource consumption to quota manager
+            if agent.quota_manager.respond_to? :consume
+              agent.quota_manager.consume time: Time.now - time_begin
+            end
+          end
+
+          update_breakpoints_cache
+
+          # Disable all trace points and tracing if all breakpoints are complete
+          disable_traces if @breakpoints_cache.empty?
+        end
+
+        ##
+        # Get the sync the breakpoints cache with BreakpointManager. Start
+        # tracing and monitoring if there are any breakpoints.
+        def start
+          update_breakpoints_cache
+          enable_traces unless breakpoints_cache.empty?
+        end
+
+        ##
+        # Stops all tracing.
+        def stop
+          disable_traces
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,199 @@
+# 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 "concurrent"
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # TransmitterError
+      #
+      # Used to indicate a problem submitting breakpoints. This can occur when
+      # there are not enough resources allocated for the amount of usage, or
+      # when the calling the API returns an error.
+      #
+      class TransmitterError < Google::Cloud::Error
+        # @!attribute [r] breakpoint
+        #   @return [Array<Google::Cloud::Debugger::Breakpoint>] The
+        #   individual error event that was not submitted to Stackdriver
+        #   Debugger service.
+        attr_reader :breakpoint
+
+        def initialize message, breakpoint = nil
+          super message
+          @breakpoint = breakpoint
+        end
+      end
+
+      ##
+      # # Transmitter
+      #
+      # Responsible for submit evaluated breakpoints back to Stackdriver
+      # Debugger service asynchronously. It maintains a thread pool.
+      #
+      # The transmitter is controlled by the debugger agent it belongs to.
+      # Debugger agent submits evaluated breakpoint asynchronously, and the
+      # transmitter submits the breakpoints to Stackdriver Debugger service.
+      #
+      class Transmitter
+        ##
+        # @private The gRPC Service object and thread pool.
+        attr_reader :service, :thread_pool
+
+        ##
+        # The debugger agent this transmiter belongs to
+        # @return [Google::Cloud::Debugger::Agent]
+        attr_accessor :agent
+
+        ##
+        # Maximum backlog size for this transmitter's queue
+        attr_accessor :max_queue
+        alias max_queue_size  max_queue
+        alias max_queue_size= max_queue=
+
+        ##
+        # Maximum threads used in the thread pool
+        attr_accessor :threads
+
+        ##
+        # @private Creates a new Transmitter instance.
+        def initialize agent, service, max_queue: 1000, threads: 10
+          @agent   = agent
+          @service = service
+
+          @max_queue = max_queue
+          @threads   = threads
+
+          @thread_pool = Concurrent::ThreadPoolExecutor.new \
+            max_threads: @threads, max_queue: @max_queue
+
+          @error_callbacks = []
+
+          # Make sure all queued calls are completed when process exits.
+          at_exit { stop }
+        end
+
+        ##
+        # Enqueue an evaluated breakpoint to be submitted by the transmitter.
+        #
+        # @raise [TransmitterError] if there are no resources available to make
+        #   queue the API call on the thread pool.
+        def submit breakpoint
+          Concurrent::Promises.future_on @thread_pool, breakpoint do |bp|
+            submit_sync bp
+          end
+        rescue Concurrent::RejectedExecutionError => e
+          raise TransmitterError.new(
+            "Error asynchronously submitting breakpoint: #{e.message}",
+            breakpoint
+          )
+        end
+
+        ##
+        # Starts the transmitter and its thread pool.
+        #
+        # @return [Transmitter] returns self so calls can be chained.
+        def start
+          # no-op
+          self
+        end
+
+        ##
+        # Stops the transmitter and its thread pool. Once stopped, cannot be
+        # started again.
+        #
+        # @return [Transmitter] returns self so calls can be chained.
+        def stop timeout = nil
+          if @thread_pool
+            @thread_pool.shutdown
+            @thread_pool.wait_for_termination timeout
+          end
+
+          self
+        end
+
+        ##
+        # Whether the transmitter has been started.
+        #
+        # @return [boolean] `true` when started, `false` otherwise.
+        #
+        def started?
+          @thread_pool.running? if @thread_pool
+        end
+
+        ##
+        # Whether the transmitter has been stopped.
+        #
+        # @return [boolean] `true` when stopped, `false` otherwise.
+        #
+        def stopped?
+          !started?
+        end
+
+        ##
+        # Register to be notified of errors when raised.
+        #
+        # If an unhandled error has occurred the transmitter will attempt to
+        # recover from the error and resume submitting breakpoints.
+        #
+        # Multiple error handlers can be added.
+        #
+        # @yield [callback] The block to be called when an error is raised.
+        # @yieldparam [Exception] error The error raised.
+        #
+        def on_error &block
+          @error_callbacks << block
+        end
+
+        protected
+
+        # Calls all error callbacks.
+        def error! error
+          error_callbacks = @error_callbacks
+          error_callbacks = default_error_callbacks if error_callbacks.empty?
+          error_callbacks.each { |error_callback| error_callback.call error }
+        end
+
+        def default_error_callbacks
+          # This is memoized to reduce calls to the configuration.
+          @default_error_callbacks ||= begin
+            error_cb = Google::Cloud::Debugger.configure.on_error
+            error_cb ||= Google::Cloud.configure.on_error
+            if error_cb
+              [error_cb]
+            else
+              []
+            end
+          end
+        end
+
+        def submit_sync breakpoint
+          service.update_active_breakpoint agent.debuggee.id, breakpoint
+        rescue StandardError => e
+          sync_error = TransmitterError.new(
+            "Error asynchronously transmitting breakpoint: #{e.message}",
+            breakpoint
+          )
+          # Manually set backtrace so we don't have to raise
+          sync_error.set_backtrace caller
+
+          error! sync_error
+        end
+      end
+    end
+  end
+end