google-cloud-debugger 0.24.0

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

@@ -0,0 +1,165 @@
+# 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 "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
+
+        ##
+        # Ruby application root directory, in absolute path form. The
+        # Stackdriver Debugger Service only knows the relative application file
+        # path. So the tracer needs to combine relative file path with
+        # application root directory to get full file path for tracing purpose
+        # @return [String]
+        attr_accessor :app_root
+
+        ##
+        # @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, app_root: nil
+          @agent = agent
+          @file_tracepoint = nil
+          @fiber_tracepoint = nil
+          @breakpoints_cache = {}
+
+          @app_root = app_root
+          @app_root ||= Rack::Directory.new("").root if defined? Rack::Directory
+
+          fail "Unable to determine application root path" unless @app_root
+        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 = full_breakpoint_path active_breakpoint.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
+
+        ##
+        # Evaluates a hit breakpoint, and signal BreakpointManager and
+        # Transmitter if this breakpoint is evaluated successfully.
+        #
+        # See {Breakpoint#eval_call_stack} for evaluation details.
+        #
+        # @param [Google::Cloud::Debugger::Breakpoint] breakpoint The breakpoint
+        #   to be evaluated
+        # @param [Array<Binding>] call_stack_bindings An array of Ruby Binding
+        #   objects, from the each frame of the call stack that leads to the
+        #   triggering of the breakpoints.
+        #
+        def eval_breakpoint breakpoint, call_stack_bindings
+          return if breakpoint.nil? || breakpoint.complete?
+
+          breakpoint.eval_call_stack call_stack_bindings
+
+          # Take this completed breakpoint off manager's active breakpoints
+          # list, submit the breakpoint snapshot, and update Tracer's
+          # breakpoints_cache.
+          return unless breakpoint.complete?
+
+          # Signal breakpoint_manager that this breakpoint is evaluated
+          agent.breakpoint_manager.mark_off breakpoint
+          # Signal transmitter to submit this breakpoint
+          agent.transmitter.submit breakpoint
+
+          update_breakpoints_cache
+
+          # Disable all trace points and tracing if all breakpoints are complete
+          disable_traces if @breakpoints_cache.empty?
+        end
+
+        ##
+        # @private Covert breakpoint's relative file path to absolute file
+        # path by combining it with application root directory path.
+        def full_breakpoint_path breakpoint_path
+          if app_root.nil? || app_root.empty?
+            breakpoint_path
+          else
+            "#{app_root}/#{breakpoint_path}"
+          end
+        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,129 @@
+# 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"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Transmitter
+      #
+      # Responsible for submit evaluated breakpoints back to Stackdriver
+      # Debugger service asynchronously. It has it's own dedicated child thread,
+      # so it doesn't interfere with main Ruby application threads or the
+      # debugger agent's thread.
+      #
+      # The transmitter is controlled by the debugger agent it belongs to.
+      # Debugger agent submits evaluated breakpoint into a thread safe queue,
+      # and the transmitter operates directly on the queue along with minimal
+      # interaction with the rest debugger agent components
+      #
+      class Transmitter
+        include AsyncActor
+
+        ##
+        # @private Default maximum backlog size for the job queue
+        DEFAULT_MAX_QUEUE_SIZE = 1000
+
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # The debugger agent this transmiter belongs to
+        # @return [Google::Cloud::Debugger::Agent]
+        attr_accessor :agent
+
+        ##
+        # Maxium backlog size for this transmitter's queue
+        attr_accessor :max_queue_size
+
+        ##
+        # @private Construct a new instance of Tramsnitter
+        def initialize service, agent, max_queue_size = DEFAULT_MAX_QUEUE_SIZE
+          super()
+          @service = service
+          @agent = agent
+          @max_queue_size = max_queue_size
+          @queue = Thread::Queue.new
+        end
+
+        ##
+        # Starts the transmitter and its worker thread
+        def start
+          async_start
+        end
+
+        ##
+        # Stops the transmitter and its worker thread. Once stopped, cannot be
+        # started again.
+        def stop
+          async_stop
+        end
+
+        ##
+        # Enqueue an evaluated breakpoints to be submitted by the transmitter.
+        #
+        # @param [Google::Cloud::Debugger::Breakpoint] breakpoint The evaluated
+        #   breakpoint to be submitted
+        def submit breakpoint
+          synchronize do
+            @queue.push breakpoint
+            @lock_cond.broadcast
+            # Discard old entries if queue gets too large
+            @queue.pop while @queue.size > @max_queue_size
+          end
+        end
+
+        ##
+        # @private Callback fucntion for AsyncActor module to run the async
+        # job in a loop
+        def run_backgrounder
+          breakpoint = wait_next_item
+          return if breakpoint.nil?
+          begin
+            service.update_active_breakpoint agent.debuggee.id, breakpoint
+          rescue => e
+            @last_exception = e
+          end
+        end
+
+        private
+
+        ##
+        # @private The the next item from the transmitter queue. If there are
+        # no more item, it blocks the transmitter thread until an item is
+        # enqueued
+        def wait_next_item
+          synchronize do
+            @lock_cond.wait_while do
+              async_state == :suspended ||
+                (async_state == :running && @queue.empty?)
+            end
+            queue_item = nil
+            if @queue.empty?
+              @async_state = :stopped
+            else
+              queue_item = @queue.pop
+            end
+            @lock_cond.broadcast
+            queue_item
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# 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/v2/controller2_client"
+require "google/cloud/debugger/v2/debugger2_client"

data/lib/google/cloud/debugger/v2/controller2_client.rb

@@ -0,0 +1,299 @@
+# 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.
+#
+# EDITING INSTRUCTIONS
+# This file was generated from the file
+# https://github.com/googleapis/googleapis/blob/master/google/devtools/clouddebugger/v2/controller.proto,
+# and updates to that file get reflected here through a refresh process.
+# For the short term, the refresh process will only be runnable by Google
+# engineers.
+#
+# The only allowed edits are to method and file documentation. A 3-way
+# merge preserves those additions if the generated source changes.
+
+require "json"
+require "pathname"
+
+require "google/gax"
+
+require "google/devtools/clouddebugger/v2/controller_pb"
+
+module Google
+  module Cloud
+    module Debugger
+      module V2
+        # The Controller service provides the API for orchestrating a collection of
+        # debugger agents to perform debugging tasks. These agents are each attached
+        # to a process of an application which may include one or more replicas.
+        #
+        # The debugger agents register with the Controller to identify the application
+        # being debugged, the Debuggee. All agents that register with the same data,
+        # represent the same Debuggee, and are assigned the same +debuggee_id+.
+        #
+        # The debugger agents call the Controller to retrieve  the list of active
+        # Breakpoints. Agents with the same +debuggee_id+ get the same breakpoints
+        # list. An agent that can fulfill the breakpoint request updates the
+        # Controller with the breakpoint result. The controller selects the first
+        # result received and discards the rest of the results.
+        # Agents that poll again for active breakpoints will no longer have
+        # the completed breakpoint in the list and should remove that breakpoint from
+        # their attached process.
+        #
+        # The Controller service does not provide a way to retrieve the results of
+        # a completed breakpoint. This functionality is available using the Debugger
+        # service.
+        #
+        # @!attribute [r] controller2_stub
+        #   @return [Google::Devtools::Clouddebugger::V2::Controller2::Stub]
+        class Controller2Client
+          attr_reader :controller2_stub
+
+          # The default address of the service.
+          SERVICE_ADDRESS = "clouddebugger.googleapis.com".freeze
+
+          # The default port of the service.
+          DEFAULT_SERVICE_PORT = 443
+
+          DEFAULT_TIMEOUT = 30
+
+          # The scopes needed to make gRPC calls to all of the methods defined in
+          # this service.
+          ALL_SCOPES = [
+            "https://www.googleapis.com/auth/cloud-platform",
+            "https://www.googleapis.com/auth/cloud_debugger"
+          ].freeze
+
+          # @param service_path [String]
+          #   The domain name of the API remote host.
+          # @param port [Integer]
+          #   The port on which to connect to the remote host.
+          # @param channel [Channel]
+          #   A Channel object through which to make calls.
+          # @param chan_creds [Grpc::ChannelCredentials]
+          #   A ChannelCredentials for the setting up the RPC client.
+          # @param client_config[Hash]
+          #   A Hash for call options for each method. See
+          #   Google::Gax#construct_settings for the structure of
+          #   this data. Falls back to the default config if not specified
+          #   or the specified config is missing data points.
+          # @param timeout [Numeric]
+          #   The default timeout, in seconds, for calls made through this client.
+          def initialize \
+              service_path: SERVICE_ADDRESS,
+              port: DEFAULT_SERVICE_PORT,
+              channel: nil,
+              chan_creds: nil,
+              scopes: ALL_SCOPES,
+              client_config: {},
+              timeout: DEFAULT_TIMEOUT,
+              app_name: nil,
+              app_version: nil,
+              lib_name: nil,
+              lib_version: ""
+            # These require statements are intentionally placed here to initialize
+            # the gRPC module only when it's required.
+            # See https://github.com/googleapis/toolkit/issues/446
+            require "google/gax/grpc"
+            require "google/devtools/clouddebugger/v2/controller_services_pb"
+
+
+            if app_name || app_version
+              warn "`app_name` and `app_version` are no longer being used in the request headers."
+            end
+
+            google_api_client = "gl-ruby/#{RUBY_VERSION}"
+            google_api_client << " #{lib_name}/#{lib_version}" if lib_name
+            google_api_client << " gapic/0.6.8 gax/#{Google::Gax::VERSION}"
+            google_api_client << " grpc/#{GRPC::VERSION}"
+            google_api_client.freeze
+
+            headers = { :"x-goog-api-client" => google_api_client }
+            client_config_file = Pathname.new(__dir__).join(
+              "controller2_client_config.json"
+            )
+            defaults = client_config_file.open do |f|
+              Google::Gax.construct_settings(
+                "google.devtools.clouddebugger.v2.Controller2",
+                JSON.parse(f.read),
+                client_config,
+                Google::Gax::Grpc::STATUS_CODE_NAMES,
+                timeout,
+                errors: Google::Gax::Grpc::API_ERRORS,
+                kwargs: headers
+              )
+            end
+            @controller2_stub = Google::Gax::Grpc.create_stub(
+              service_path,
+              port,
+              chan_creds: chan_creds,
+              channel: channel,
+              scopes: scopes,
+              &Google::Devtools::Clouddebugger::V2::Controller2::Stub.method(:new)
+            )
+
+            @register_debuggee = Google::Gax.create_api_call(
+              @controller2_stub.method(:register_debuggee),
+              defaults["register_debuggee"]
+            )
+            @list_active_breakpoints = Google::Gax.create_api_call(
+              @controller2_stub.method(:list_active_breakpoints),
+              defaults["list_active_breakpoints"]
+            )
+            @update_active_breakpoint = Google::Gax.create_api_call(
+              @controller2_stub.method(:update_active_breakpoint),
+              defaults["update_active_breakpoint"]
+            )
+          end
+
+          # Service calls
+
+          # Registers the debuggee with the controller service.
+          #
+          # All agents attached to the same application should call this method with
+          # the same request content to get back the same stable +debuggee_id+. Agents
+          # should call this method again whenever +google.rpc.Code.NOT_FOUND+ is
+          # returned from any controller method.
+          #
+          # This allows the controller service to disable the agent or recover from any
+          # data loss. If the debuggee is disabled by the server, the response will
+          # have +is_disabled+ set to +true+.
+          #
+          # @param debuggee [Google::Devtools::Clouddebugger::V2::Debuggee]
+          #   Debuggee information to register.
+          #   The fields +project+, +uniquifier+, +description+ and +agent_version+
+          #   of the debuggee must be set.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @return [Google::Devtools::Clouddebugger::V2::RegisterDebuggeeResponse]
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/debugger/v2/controller2_client"
+          #
+          #   Controller2Client = Google::Cloud::Debugger::V2::Controller2Client
+          #   Debuggee = Google::Devtools::Clouddebugger::V2::Debuggee
+          #
+          #   controller2_client = Controller2Client.new
+          #   debuggee = Debuggee.new
+          #   response = controller2_client.register_debuggee(debuggee)
+
+          def register_debuggee \
+              debuggee,
+              options: nil
+            req = Google::Devtools::Clouddebugger::V2::RegisterDebuggeeRequest.new({
+              debuggee: debuggee
+            }.delete_if { |_, v| v.nil? })
+            @register_debuggee.call(req, options)
+          end
+
+          # Returns the list of all active breakpoints for the debuggee.
+          #
+          # The breakpoint specification (location, condition, and expression
+          # fields) is semantically immutable, although the field values may
+          # change. For example, an agent may update the location line number
+          # to reflect the actual line where the breakpoint was set, but this
+          # doesn't change the breakpoint semantics.
+          #
+          # This means that an agent does not need to check if a breakpoint has changed
+          # when it encounters the same breakpoint on a successive call.
+          # Moreover, an agent should remember the breakpoints that are completed
+          # until the controller removes them from the active list to avoid
+          # setting those breakpoints again.
+          #
+          # @param debuggee_id [String]
+          #   Identifies the debuggee.
+          # @param wait_token [String]
+          #   A wait token that, if specified, blocks the method call until the list
+          #   of active breakpoints has changed, or a server selected timeout has
+          #   expired.  The value should be set from the last returned response.
+          # @param success_on_timeout [true, false]
+          #   If set to +true+, returns +google.rpc.Code.OK+ status and sets the
+          #   +wait_expired+ response field to +true+ when the server-selected timeout
+          #   has expired (recommended).
+          #
+          #   If set to +false+, returns +google.rpc.Code.ABORTED+ status when the
+          #   server-selected timeout has expired (deprecated).
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @return [Google::Devtools::Clouddebugger::V2::ListActiveBreakpointsResponse]
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/debugger/v2/controller2_client"
+          #
+          #   Controller2Client = Google::Cloud::Debugger::V2::Controller2Client
+          #
+          #   controller2_client = Controller2Client.new
+          #   debuggee_id = ''
+          #   response = controller2_client.list_active_breakpoints(debuggee_id)
+
+          def list_active_breakpoints \
+              debuggee_id,
+              wait_token: nil,
+              success_on_timeout: nil,
+              options: nil
+            req = Google::Devtools::Clouddebugger::V2::ListActiveBreakpointsRequest.new({
+              debuggee_id: debuggee_id,
+              wait_token: wait_token,
+              success_on_timeout: success_on_timeout
+            }.delete_if { |_, v| v.nil? })
+            @list_active_breakpoints.call(req, options)
+          end
+
+          # Updates the breakpoint state or mutable fields.
+          # The entire Breakpoint message must be sent back to the controller
+          # service.
+          #
+          # Updates to active breakpoint fields are only allowed if the new value
+          # does not change the breakpoint specification. Updates to the +location+,
+          # +condition+ and +expression+ fields should not alter the breakpoint
+          # semantics. These may only make changes such as canonicalizing a value
+          # or snapping the location to the correct line of code.
+          #
+          # @param debuggee_id [String]
+          #   Identifies the debuggee being debugged.
+          # @param breakpoint [Google::Devtools::Clouddebugger::V2::Breakpoint]
+          #   Updated breakpoint information.
+          #   The field 'id' must be set.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @return [Google::Devtools::Clouddebugger::V2::UpdateActiveBreakpointResponse]
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/debugger/v2/controller2_client"
+          #
+          #   Breakpoint = Google::Devtools::Clouddebugger::V2::Breakpoint
+          #   Controller2Client = Google::Cloud::Debugger::V2::Controller2Client
+          #
+          #   controller2_client = Controller2Client.new
+          #   debuggee_id = ''
+          #   breakpoint = Breakpoint.new
+          #   response = controller2_client.update_active_breakpoint(debuggee_id, breakpoint)
+
+          def update_active_breakpoint \
+              debuggee_id,
+              breakpoint,
+              options: nil
+            req = Google::Devtools::Clouddebugger::V2::UpdateActiveBreakpointRequest.new({
+              debuggee_id: debuggee_id,
+              breakpoint: breakpoint
+            }.delete_if { |_, v| v.nil? })
+            @update_active_breakpoint.call(req, options)
+          end
+        end
+      end
+    end
+  end
+end