google-cloud-debugger 0.26.1 → 0.27.0

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

@@ -0,0 +1,96 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+require "forwardable"
+
+module Google
+  module Cloud
+    module Debugger
+      class Breakpoint
+        ##
+        # # VariableTable
+        #
+        # 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.
+        #
+        # See also {Breakpoint#variable_table}.
+        #
+        class VariableTable
+          extend Forwardable
+
+          ##
+          # @private Array to store variables.
+          attr_accessor :variables
+
+          ##
+          # @private Create a new VariableTable instance
+          def initialize
+            @variables = []
+          end
+
+          ##
+          # @private Create a new VariableTable instance from a variable table
+          # gRPC struct
+          def self.from_grpc grpc_table
+            return if grpc_table.nil?
+
+            new.tap do |vt|
+              vt.variables = grpc_table.map do |grpc_var|
+                Breakpoint::Variable.from_grpc grpc_var
+              end
+            end
+          end
+
+          ##
+          # @private Search a variable in this VariableTable by matching
+          # object_id, return the array index if found.
+          def rb_var_index rb_var
+            variables.each_with_index do |var, i|
+              return i if var.source_var.object_id == rb_var.object_id
+            end
+
+            nil
+          end
+
+          ##
+          # @private Add a Breakpoint::Variable to this VariableTable
+          def add var
+            return unless var.is_a? Breakpoint::Variable
+
+            variables << var
+          end
+
+          ##
+          # @private Export this VariableTable as a gRPC struct
+          def to_grpc
+            variables.map(&:to_grpc).compact
+          end
+
+          def_instance_delegators :@variables, :size, :first, :[]
+        end
+      end
+    end
+  end
+end

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

@@ -13,7 +13,8 @@
 # limitations under the License.
 
 
-require "google/cloud/debugger/breakpoint"
+require "google/cloud/debugger/snappoint"
+require "google/cloud/debugger/logpoint"
 
 module Google
   module Cloud
@@ -92,10 +93,8 @@ module Google
 
           @wait_token = response.next_wait_token
 
-          server_breakpoints = response.breakpoints || []
-          server_breakpoints = server_breakpoints.map do |grpc_b|
-            Breakpoint.from_grpc grpc_b
-          end
+          server_breakpoints =
+            convert_grpc_breakpoints response.breakpoints || []
 
           update_breakpoints server_breakpoints
 
@@ -117,9 +116,9 @@ module Google
         def update_breakpoints server_breakpoints
           synchronize do
             new_breakpoints =
-              server_breakpoints - @active_breakpoints - @completed_breakpoints
-            before_breakpoints_count =
-              @active_breakpoints.size + @completed_breakpoints.size
+              filter_breakpoints server_breakpoints - breakpoints
+
+            before_breakpoints_count = breakpoints.size
 
             # Remember new active breakpoints from server
             @active_breakpoints += new_breakpoints unless new_breakpoints.empty?
@@ -127,8 +126,7 @@ module Google
             # Forget old breakpoints
             @completed_breakpoints &= server_breakpoints
             @active_breakpoints &= server_breakpoints
-            after_breakpoints_acount =
-              @active_breakpoints.size + @completed_breakpoints.size
+            after_breakpoints_acount = breakpoints.size
 
             breakpoints_updated =
               !new_breakpoints.empty? ||
@@ -159,6 +157,7 @@ module Google
             # Take this completed breakpoint off manager's active breakpoints
             # list, submit the breakpoint snapshot, and update Tracer's
             # breakpoints_cache.
+
             return unless breakpoint.complete?
 
             # Remove this breakpoint from active list
@@ -269,6 +268,42 @@ module Google
             @completed_breakpoints.clear
           end
         end
+
+        private
+
+        ##
+        # @private Convert the list of grpc breakpoints from Debugger service to
+        # {Google::Cloud::Debugger::Breakpoint}.
+        def convert_grpc_breakpoints grpc_breakpoints
+          grpc_breakpoints.map do |grpc_b|
+            breakpoint = Breakpoint.from_grpc grpc_b
+            breakpoint.app_root = agent.app_root
+            breakpoint.init_var_table if breakpoint.is_a? Debugger::Snappoint
+            breakpoint
+          end
+        end
+
+        ##
+        # @private Varify a list of given breakpoints. Filter out those
+        # aren't valid and submit them directly.
+        def filter_breakpoints breakpoints
+          valid_breakpoints = []
+          invalid_breakpoints = []
+
+          breakpoints.each do |breakpoint|
+            if breakpoint.valid?
+              valid_breakpoints << breakpoint
+            else
+              invalid_breakpoints << breakpoint
+            end
+          end
+
+          invalid_breakpoints.each do |breakpoint|
+            agent.transmitter.submit breakpoint if breakpoint.complete?
+          end
+
+          valid_breakpoints
+        end
       end
     end
   end

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

@@ -21,7 +21,8 @@ module Google
       ##
       # @private Represents the OAuth 2.0 signing logic for Debugger.
       class Credentials < Google::Cloud::Credentials
-        SCOPE = ["https://www.googleapis.com/auth/cloud_debugger"]
+        SCOPE = ["https://www.googleapis.com/auth/cloud_debugger"] +
+                Google::Cloud::Logging::Credentials::SCOPE
         PATH_ENV_VARS = %w(DEBUGGER_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
         JSON_ENV_VARS = %w(DEBUGGER_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
                            GCLOUD_KEYFILE_JSON)

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

@@ -0,0 +1,97 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+require "google/cloud/debugger/breakpoint"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Logpoint
+      #
+      # A kind of {Google::Cloud::Debugger::Breakpoint} that can be evaluated
+      # to generate a formatted log string, which later can be submitted to
+      # Stackdriver Logging service
+      #
+      class Logpoint < Breakpoint
+        ##
+        # Evaluate the breakpoint unless it's already marked as completed.
+        # Store evaluted expressions and stack frame variables in
+        # @evaluated_expressions and @evaluated_log_message.
+        #
+        # @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
+            binding = call_stack_bindings[0]
+
+            return false if complete? || !check_condition(binding)
+
+            begin
+              evaluate_log_message binding
+            rescue
+              return false
+            end
+          end
+
+          true
+        end
+
+        ##
+        # @private Evaluate the expressions and log message. Store the result
+        # in @evaluated_log_message
+        def evaluate_log_message binding
+          evaluated_expressions = expressions.map do |expression|
+            Evaluator.readonly_eval_expression binding, expression
+          end
+
+          @evaluated_log_message =
+            format_message log_message_format, evaluated_expressions
+        end
+
+        ##
+        # @private Format log message by interpolate expressions.
+        #
+        # @example
+        #   Evaluator.format_log_message("Hello $0",
+        #                                ["World"]) #=> "Hello World"
+        #
+        # @param [String] message_format The message with with
+        #   expression placeholders such as `$0`, `$1`, etc.
+        # @param [Array<Google::Cloud::Debugger::Breakpoint::Variable>]
+        #   expressions An array of evaluated expression variables to be
+        #   placed into message_format's placeholders. The variables need
+        #   to have type equal String.
+        #
+        # @return [String] The formatted message string
+        #
+        def format_message message_format, expressions
+          # Substitute placeholders with expressions
+          message = message_format.gsub(/(?<!\$)\$\d+/) do |placeholder|
+            index = placeholder.match(/\$(\d+)/)[1].to_i
+            index < expressions.size ? expressions[index].inspect : ""
+          end
+
+          # Unescape "$" characters
+          message.gsub(/\$\$/, "$")
+        end
+      end
+    end
+  end
+end

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

@@ -14,6 +14,7 @@
 
 
 require "google/cloud/logging/logger"
+require "google/cloud/debugger/request_quota_manager"
 
 module Google
   module Cloud
@@ -44,11 +45,18 @@ module Google
 
           load_config kwargs
 
-          @debugger = debugger ||
-                      Debugger.new(project: configuration.project_id,
-                                   keyfile: configuration.keyfile,
-                                   module_name: configuration.module_name,
-                                   module_version: configuration.module_version)
+          if debugger
+            @debugger = debugger
+          else
+            @debugger =
+              Debugger.new(project: configuration.project_id,
+                           keyfile: configuration.keyfile,
+                           module_name: configuration.module_name,
+                           module_version: configuration.module_version)
+
+            @debugger.agent.quota_manager =
+              Google::Cloud::Debugger::RequestQuotaManager.new
+          end
 
           # Immediately start the debugger agent
           @debugger.start
@@ -77,6 +85,9 @@ module Google
         ensure
           # Stop breakpoints tracing beyond this point
           @debugger.agent.tracer.disable_traces_for_thread
+
+          # Reset quotas after each request finishes.
+          @debugger.agent.quota_manager.reset if @debugger.agent.quota_manager
         end
 
         private

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

@@ -0,0 +1,95 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # RequestQuotaManager
+      #
+      # Tracking object used by debugger agent to manage quota in
+      # request-based applications. This class tracks the amount of time
+      # and number of breakpoints to evaluation in a single session.
+      #
+      # The debugger agent doesn't have use a quota manager by default, which
+      # means it will evaluate all breakpoints encountered and takes as much
+      # time as needed. This class is utilized by
+      # {Google::Cloud::Debugger::Middleware} class to limit latency overhead
+      # when used in Rack-based applications.
+      #
+      class RequestQuotaManager
+        # Default Total time allowed to consume, in seconds
+        DEFAULT_TIME_QUOTA = 0.05
+
+        # Default max number of breakpoints to evaluate
+        DEFAULT_COUNT_QUOTA = 10
+
+        ##
+        # The time quota for this manager
+        attr_accessor :time_quota
+
+        ##
+        # The count quota for this manager
+        attr_accessor :count_quota
+
+        ##
+        # The time quota used
+        attr_accessor :time_used
+
+        ##
+        # The count quota used
+        attr_accessor :count_used
+
+        ##
+        # Construct a new RequestQuotaManager instance
+        #
+        # @param [Float] time_quota The max quota for time consumed.
+        # @param [Integer] count_quota The max quota for count usage.
+        def initialize time_quota: DEFAULT_TIME_QUOTA,
+                       count_quota: DEFAULT_COUNT_QUOTA
+          @time_quota = time_quota
+          @time_used = 0
+          @count_quota = count_quota
+          @count_used = 0
+        end
+
+        ##
+        # Check if there's more quota left.
+        #
+        # @return [Boolean] True if there's more quota; false otherwise.
+        def more?
+          (time_used < time_quota) && (count_used < count_quota)
+        end
+
+        ##
+        # Reset all the quota usage.
+        def reset
+          @time_used = 0
+          @count_used = 0
+        end
+
+        ##
+        # Notify the quota manager some resource has been consumed. Each time
+        # called increases the count quota usage.
+        #
+        # @param [Float] time Amount of time to deduct from the time quota.
+        def consume time: 0
+          @time_used += time
+          @count_used += 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,208 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+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
+              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] binding 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