google-cloud-debugger 0.40.0

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

@@ -0,0 +1,222 @@
+# 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 "digest/sha1"
+require "google/cloud/debugger/backoff"
+require "google/cloud/debugger/debuggee/app_uniquifier_generator"
+require "google/cloud/debugger/version"
+require "google/cloud/env"
+require "json"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Debuggee
+      #
+      # Represent a debuggee application. Contains information that identifies
+      # debuggee applications from each other. Maps to gRPC struct
+      # Google::Cloud::Debugger::V2::Debuggee.
+      #
+      # It also automatically loads source context information generated from
+      # Cloud SDK. See [Stackdriver Debugger
+      # doc](https://cloud.google.com/debugger/docs/source-context#app_engine_standard_python)
+      # for more information on how to generate this source context information
+      # when used on Google Container Engine and Google Compute engine. This
+      # step is taken care of if debuggee application is hosted on Google App
+      # Engine Flexibile.
+      #
+      # To ensure the multiple instances of the application are indeed the same
+      # application, the debuggee also compute a "uniquifier" generated from
+      # source context or application source code.
+      #
+      class Debuggee
+        ##
+        # @private The gRPC Service object.
+        attr_reader :service
+
+        ##
+        # Name for the debuggee application
+        # @return [String]
+        attr_reader :service_name
+
+        ##
+        # Version identifier for the debuggee application
+        # @return [String]
+        attr_reader :service_version
+
+        ##
+        # Registered Debuggee ID. Set by Stackdriver Debugger service when
+        # a debuggee application is sucessfully registered.
+        # @return [String]
+        attr_reader :id
+
+        ##
+        # @private Construct a new instance of Debuggee
+        def initialize service, service_name:, service_version:
+          @service = service
+          @service_name = service_name
+          @service_version = service_version
+          @env = Google::Cloud.env
+          @computed_uniquifier = nil
+          @id = nil
+          @register_backoff = Google::Cloud::Debugger::Backoff.new
+        end
+
+        ##
+        # Register the current application as a debuggee with Stackdriver
+        # Debuggee service.
+        # @return [Boolean] True if registered sucessfully; otherwise false.
+        def register
+          # Wait if backoff applies
+          sleep @register_backoff.interval if @register_backoff.backing_off?
+
+          begin
+            response = service.register_debuggee to_grpc
+            @id = response.debuggee.id
+          rescue StandardError
+            revoke_registration
+          end
+
+          registered = registered?
+          registered ? @register_backoff.succeeded : @register_backoff.failed
+
+          registered
+        end
+
+        ##
+        # Check whether this debuggee is currently registered or not
+        # @return [Boolean] True if debuggee is registered; otherwise false.
+        def registered?
+          !id.nil?
+        end
+
+        ##
+        # Revoke the registration of this debuggee
+        def revoke_registration
+          @id = nil
+        end
+
+        ##
+        # Convert this debuggee into a gRPC
+        # Google::Cloud::Debugger::V2::Debuggee struct.
+        def to_grpc
+          source_context = source_context_from_json_file "source-context.json"
+          Google::Cloud::Debugger::V2::Debuggee.new(
+            id: id.to_s,
+            project: project_id_for_request_arg.to_s,
+            description: description.to_s,
+            labels: labels,
+            agent_version: agent_version.to_s
+          ).tap do |d|
+            if source_context
+              d.source_contexts << source_context
+              d.ext_source_contexts << ext_source_context_grpc(source_context)
+            end
+            d.uniquifier = compute_uniquifier d
+          end
+        end
+
+        private
+
+        def source_context_from_json_file file_path
+          json = File.read file_path
+          Devtools::Source::V1::SourceContext.decode_json json
+        rescue StandardError
+          nil
+        end
+
+        def ext_source_context_grpc source_context
+          Devtools::Source::V1::SourceContext.new context: source_context
+        end
+
+        ##
+        # @private Build labels hash for this debuggee
+        def labels
+          {
+            "projectid" => String(project_id),
+            "module" => String(service_name),
+            "version" => String(service_version)
+          }
+        end
+
+        ##
+        # @private Build description string for this debuggee. In
+        # "<module name> - <module version>" format. Or just the module
+        # version if module name is missing.
+        #
+        # @return [String] A compact debuggee description.
+        #
+        def description
+          if service_version.nil? || service_version.empty?
+            service_name
+          else
+            "#{service_name} - #{service_version}"
+          end
+        end
+
+        ##
+        # @private Get debuggee project id
+        def project_id
+          service.project
+        end
+
+        ##
+        # @private
+        # Get project to send as a debuggee argument. This is the numeric
+        # project ID if available (and if it matches the project set in the
+        # configuration). Otherwise, use the configured project.
+        def project_id_for_request_arg
+          if project_id == @env.lookup_metadata("project", "project-id")
+            numeric_id = @env.numeric_project_id
+            return numeric_id.to_s if numeric_id
+          end
+          project_id
+        end
+
+        ##
+        # @private Build debuggee agent version identifier
+        def agent_version
+          "google.com/ruby#{RUBY_VERSION}-#{Google::Cloud::Debugger::VERSION}"
+        end
+
+        ##
+        # @private Generate a debuggee uniquifier from source context
+        # information or application source code
+        def compute_uniquifier partial_debuggee
+          return @computed_uniquifier if @computed_uniquifier
+
+          sha = Digest::SHA1.new
+          sha << partial_debuggee.to_s
+
+          if partial_debuggee.source_contexts.empty? &&
+             partial_debuggee.ext_source_contexts.empty?
+            AppUniquifierGenerator.generate_app_uniquifier sha
+          end
+
+          @computed_uniquifier = sha.hexdigest
+        end
+
+        ##
+        # @private Helper method to parse json file
+        def read_app_json_file file_path
+          JSON.parse File.read(file_path), symbolize_names: true
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/debugger/debuggee/app_uniquifier_generator.rb

@@ -0,0 +1,76 @@
+# 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 "pathname"
+require "set"
+
+module Google
+  module Cloud
+    module Debugger
+      class Debuggee
+        ##
+        # Generates an application debuggee uniquifier by hashing the
+        # application file stats.
+        #
+        module AppUniquifierGenerator
+          ##
+          # Max number of directory levels the generator looks into.
+          MAX_DEPTH = 10
+
+          ##
+          # Computes the application uniquifier by examine the file stats of
+          # the files in the given application root directory. It only looks at
+          # .rb files and Gemfile.lock
+          #
+          # @param [Digest::SHA] sha A digest SHA object used to add the hashing
+          #   values
+          # @param [String] app_path Application root directory where the Ruby
+          #   application is located.
+          #
+          # @return [NilClass]
+          #
+          def self.generate_app_uniquifier sha, app_path = nil
+            app_path ||= if defined?(::Rack::Directory)
+                           Rack::Directory.new("").root
+                         else
+                           Dir.getwd
+                         end
+
+            process_directory sha, app_path
+
+            nil
+          end
+
+          ##
+          # @private Recursively parse files and directories.
+          def self.process_directory sha, path, depth = 1
+            return if depth > MAX_DEPTH
+
+            pathname = Pathname.new path
+            pathname.each_child do |entry|
+              if entry.directory?
+                process_directory sha, entry, depth + 1
+              else
+                next unless entry.extname == ".rb" ||
+                            entry.basename.to_s == "Gemfile.lock"
+                sha << "#{entry.expand_path}:#{entry.stat.size}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# 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
+      ##
+      # # 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 StandardError
+              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
+        #   log_point = Google::Cloud::Debugger::Logpoint.new
+        #   log_point.format_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

@@ -0,0 +1,200 @@
+# 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 "set"
+
+require "google/cloud/logging/logger"
+require "google/cloud/debugger/request_quota_manager"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # Rack Middleware implementation that supports Stackdriver Debugger Agent
+      # in Rack-based Ruby frameworks. It instantiates a new debugger agent if
+      # one isn't given already. It helps optimize Debugger Agent Tracer
+      # performance by suspending and resuming the tracer between each request.
+      #
+      # To use this middleware, simply install it in your Rack configuration.
+      # The middleware will take care of registering itself with the
+      # Stackdriver Debugger and activating the debugger agent. The location
+      # of the middleware in the middleware stack matters: breakpoints will be
+      # detected in middleware appearing after but not before this middleware.
+      #
+      # For best results, you should also call {Middleware.start_agents}
+      # during application initialization. See its documentation for details.
+      #
+      class Middleware
+        ##
+        # Reset deferred start mechanism.
+        # @private
+        #
+        def self.reset_deferred_start
+          @debuggers_to_start = Set.new
+        end
+
+        reset_deferred_start
+
+        ##
+        # Start the debugger. Either adds it to the deferred list, or, if the
+        # deferred list has already been started, starts immediately.
+        #
+        # @param [Google::Cloud::Debugger::Project] debugger
+        #
+        # @private
+        #
+        def self.deferred_start debugger
+          if @debuggers_to_start
+            @debuggers_to_start << debugger
+          else
+            debugger.start
+          end
+        end
+
+        ##
+        # This should be called once the application determines that it is safe
+        # to start background threads and open gRPC connections. It informs
+        # the middleware system that it can start debugger agents.
+        #
+        # Generally, this matters if the application forks worker processes;
+        # this method should be called only after workers are forked, since
+        # threads and network connections interact badly with fork. For
+        # example, when running Puma in
+        # [clustered mode](https://github.com/puma/puma#clustered-mode), this
+        # method should be called in an `on_worker_boot` block.
+        #
+        # If the application does no forking, this method can be called any
+        # time early in the application initialization process.
+        #
+        # If {Middleware.start_agents} is never called, the debugger agent will
+        # be started when the first request is received. This should be safe,
+        # but it will probably mean breakpoints will not be recognized during
+        # that first request. For best results, an application should call this
+        # method at the appropriate time.
+        #
+        def self.start_agents
+          return unless @debuggers_to_start
+          @debuggers_to_start.each(&:start)
+          @debuggers_to_start = nil
+        end
+
+        ##
+        # Create a new Debugger Middleware.
+        #
+        # @param [Rack Application] app Rack application
+        # @param [Google::Cloud::Debugger::Project] debugger A debugger to be
+        #   used by this middleware. If not given, will construct a new one
+        #   using the other parameters.
+        # @param [Hash] kwargs Hash of configuration settings. Used for backward
+        #   API compatibility. See the [Configuration
+        #   Guide](https://googleapis.dev/ruby/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION.html)
+        #   for the prefered way to set configuration parameters.
+        #
+        # @return [Google::Cloud::Debugger::Middleware] A new
+        #   Google::Cloud::Debugger::Middleware instance
+        #
+        def initialize app, debugger: nil, **kwargs
+          @app = app
+
+          load_config kwargs
+
+          if debugger
+            @debugger = debugger
+          else
+            @debugger =
+              Debugger.new(project_id: configuration.project_id,
+                           credentials: configuration.credentials,
+                           service_name: configuration.service_name,
+                           service_version: configuration.service_version)
+
+            @debugger.agent.quota_manager =
+              Google::Cloud::Debugger::RequestQuotaManager.new
+          end
+
+          Middleware.deferred_start @debugger
+        end
+
+        ##
+        # Rack middleware entry point. In most Rack based frameworks, a request
+        # is served by one thread. It enables/resume the debugger breakpoints
+        # tracing and stops/pauses the tracing afterwards to help improve
+        # debugger performance.
+        #
+        # @param [Hash] env Rack environment hash
+        #
+        # @return [Rack::Response] The response from downstream Rack app
+        #
+        def call env
+          # Ensure the agent is running. (Note the start method is idempotent.)
+          @debugger.start
+
+          # Enable/resume breakpoints tracing
+          @debugger.agent.tracer.start
+
+          # Use Stackdriver Logger for debugger if available
+          if env["rack.logger"].is_a? Google::Cloud::Logging::Logger
+            @debugger.agent.logger = env["rack.logger"]
+          end
+
+          @app.call env
+        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
+
+        ##
+        # Consolidate configurations from various sources. Also set
+        # instrumentation config parameters to default values if not set
+        # already.
+        #
+        def load_config **kwargs
+          project_id = kwargs[:project] || kwargs[:project_id]
+          configuration.project_id = project_id unless project_id.nil?
+
+          creds = kwargs[:credentials] || kwargs[:keyfile]
+          configuration.credentials = creds unless creds.nil?
+
+          service_name = kwargs[:service_name]
+          configuration.service_name = service_name unless service_name.nil?
+
+          service_vers = kwargs[:service_version]
+          configuration.service_version = service_vers unless service_vers.nil?
+
+          init_default_config
+        end
+
+        ##
+        # Fallback to default configuration values if not defined already
+        def init_default_config
+          configuration.project_id ||= Debugger.default_project_id
+          configuration.credentials ||= Debugger.default_credentials
+          configuration.service_name ||= Debugger.default_service_name
+          configuration.service_version ||= Debugger.default_service_version
+        end
+
+        ##
+        # @private Get Google::Cloud::Debugger.configure
+        def configuration
+          Google::Cloud::Debugger.configure
+        end
+      end
+    end
+  end
+end