google-cloud-debugger 0.24.0

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

@@ -0,0 +1,204 @@
+# 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/async_actor"
+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"
+
+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
+        ##
+        # @private Debugger Agent is an asynchronous actor
+        include 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
+
+        ##
+        # @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 [String] module_name Name for the debuggee application.
+        #   Optional.
+        # @param [String] module_version Version identifier for the debuggee
+        #   application. Optional.
+        #
+        def initialize service, module_name:, module_version:
+          super()
+
+          @service = service
+          @debuggee = Debuggee.new service, module_name: module_name,
+                                            module_version: module_version
+          @tracer = Debugger::Tracer.new self
+          @breakpoint_manager = BreakpointManager.new service
+          @breakpoint_manager.on_breakpoints_change =
+            method :breakpoints_change_callback
+
+          @transmitter = Transmitter.new service, self
+        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
+          tracer.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 => e
+          @last_exception = e
+        end
+
+        private
+
+        ##
+        # @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 Override AsyncActor#async_stop to immediately kill the child
+        # thread instead of waiting for it to return, because the breakpoints
+        # are queried with a hanging long poll mechanism.
+        def async_stop
+          @startup_lock.synchronize do
+            unless @thread.nil?
+              tracer.stop
+
+              @async_state = :stopped
+              @thread.kill
+              @thread.join
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,290 @@
+# 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 "set"
+
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # AsyncActor
+      #
+      # @private An module that provides a class asynchronous capability when
+      #   included. It can create a child thread to run background jobs, and
+      #   help make sure the child thread terminates properly when process
+      #   is interrupted.
+      #
+      # To use AsyncActor, the classes that are including this module need to
+      # define a run_backgrounder method that does the background job. The
+      # classes can then control the child thread job through instance methods
+      # like async_start, async_stop, etc.
+      #
+      # @example
+      #   class Foo
+      #     include AsyncActor
+      #
+      #     def initialize
+      #       super()
+      #     end
+      #
+      #     def run_backgrounder
+      #       # run async job
+      #     end
+      #   end
+      #
+      #   foo = Foo.new
+      #   foo.async_start
+      #
+      module AsyncActor
+        include MonitorMixin
+
+        CLEANUP_TIMEOUT = 10.0
+        WAIT_INTERVAL = 1.0
+
+        @cleanup_list = nil
+        @exit_lock = Monitor.new
+
+        ##
+        # @private The async actor state
+        attr_reader :async_state
+
+        ##
+        # Starts the child thread and asynchronous job
+        def async_start
+          ensure_thread
+        end
+
+        ##
+        # Nicely ask the child thread to stop by setting the state to
+        # :stopping if it's not stopped already.
+        #
+        # @return [Boolean] False if child thread is already stopped. Otherwise
+        #   true.
+        def async_stop
+          ensure_thread
+          synchronize do
+            if async_state != :stopped
+              @async_state = :stopping
+              @lock_cond.broadcast
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # Set the state to :suspend if the current state is :running.
+        #
+        # @return [Boolean] Returns true if the state has been set to
+        #   :suspended. Otherwise return false.
+        #
+        def async_suspend
+          ensure_thread
+          synchronize do
+            if async_state == :running
+              @async_state = :suspended
+              @lock_cond.broadcast
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # Set the state to :running if the current state is :suspended.
+        #
+        # @return [Boolean] True if the state has been set to :running.
+        #   Otherwise return false.
+        #
+        def async_resume
+          ensure_thread
+          synchronize do
+            if async_state == :suspended
+              @async_state = :running
+              @lock_cond.broadcast
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # Check if async job is running
+        #
+        # @return [Boolean] True if state equals :running. Otherwise false.
+        def async_running?
+          synchronize do
+            async_state == :running
+          end
+        end
+
+        ##
+        # Check if async job is suspended
+        #
+        # @return [Boolean] True if state equals :suspended. Otherwise false.
+        def async_suspended?
+          synchronize do
+            async_state == :suspended
+          end
+        end
+
+        ##
+        # Check if async job is working.
+        #
+        # @return [Boolean] True if state is either :running or :suspended.
+        #   Otherwise false.
+        def async_working?
+          synchronize do
+            async_state == :suspended || async_state == :running
+          end
+        end
+
+        ##
+        # Check if async job has stopped
+        #
+        # @return [Boolean] True if state equals :stopped. Otherwise false.
+        def async_stopped?
+          synchronize do
+            async_state == :stopped
+          end
+        end
+
+        ##
+        # Ask async job to stop. Then forcefully kill thread if it doesn't stop
+        # after timeout if needed.
+        #
+        # @param [Boolean] force If true, forcefully kill thread after timeout.
+        #   Default to false.
+        #
+        # @return [Symbol] :stopped if async job already stopped. :waited if
+        #   async job terminates within timeout range. :timeout if async job
+        #   doesn't terminate after timeout. :forced if thread is killed by
+        #   force after timeout.
+        def async_stop! timeout, force: false
+          return :stopped unless async_stop
+          return :waited if wait_until_async_stopped timeout
+          return :timeout unless force
+          @thread.kill
+          @thread.join
+          :forced
+        end
+
+        ##
+        # @private Cleanup this async job when process exists
+        #
+        def self.register_for_cleanup actor
+          @exit_lock.synchronize do
+            unless @cleanup_list
+              @cleanup_list = []
+              at_exit { run_cleanup }
+            end
+            @cleanup_list.push actor
+          end
+        end
+
+        ##
+        # @private Take this async job off exit cleanup list
+        #
+        def self.unregister_for_cleanup actor
+          @exit_lock.synchronize do
+            @cleanup_list.delete actor if @cleanup_list
+          end
+        end
+
+        ##
+        # @private Cleanup the async job
+        #
+        def self.run_cleanup
+          @exit_lock.synchronize do
+            if @cleanup_list
+              until @cleanup_list.empty?
+                @cleanup_list.shift.async_stop! CLEANUP_TIMEOUT, force: true
+              end
+            end
+          end
+        end
+
+        private_class_method :run_cleanup
+
+        private
+
+        ##
+        # @private Helper method to async_stop! to wait for async job to
+        # terminate.
+        #
+        # @return [Boolean] True if async job terminated. False if timeout.
+        #
+        def wait_until_async_stopped timeout = nil
+          ensure_thread
+          deadline = timeout ? ::Time.new.to_f + timeout : nil
+          synchronize do
+            until async_state == :stopped
+              cur_time = ::Time.new.to_f
+              return false if deadline && cur_time >= deadline
+              interval = deadline ? deadline - cur_time : WAIT_INTERVAL
+              interval = WAIT_INTERVAL if interval > WAIT_INTERVAL
+              @lock_cond.wait interval
+            end
+          end
+          true
+        end
+
+        ##
+        # @private Constructor to initialize MonitorMixin
+        #
+        def initialize
+          super()
+          @startup_lock = Mutex.new
+        end
+
+        ##
+        # @private Wrapper method for running the async job. It requires classes
+        #   that include AsyncActor module to define a run_backgrounder method.
+        #   Then it runs a loop that checks for the state is workable (:running
+        #   or :suspended), which calls the run_backgrounder method. It ensures
+        #   the state variable gets set to :stopped when this method exists.
+        def async_run_job
+          fail "run_backgrounder method not defined" unless
+            respond_to? :run_backgrounder
+          run_backgrounder while async_working?
+        ensure
+          @async_state = :stopped
+        end
+
+        ##
+        # @private Ensures the child thread is started and kick off the job
+        #   to run async_run_job. Also make calls register_for_cleanup on the
+        #   async job to make sure it exits properly.
+        def ensure_thread
+          fail "async_actor not initialized" if @startup_lock.nil?
+          @startup_lock.synchronize do
+            if (@thread.nil? || !@thread.alive?) && @async_state != :stopped
+              @lock_cond = new_cond
+              AsyncActor.register_for_cleanup self
+              @thread = Thread.new do
+                async_run_job
+                AsyncActor.unregister_for_cleanup self
+              end
+              @async_state = :running
+            end
+          end
+        end
+      end
+    end
+  end
+end