gruf 1.1.0 → 1.2.0

data/lib/gruf/hooks/base.rb

@@ -17,16 +17,21 @@
 module Gruf
   module Hooks
     ##
-    # Base class for a hook. Define before, around, or after methods to utilize functionality.
+    # Base class for a hook. Define before, around, outer_around, or after methods to utilize functionality.
     #
     class Base
       include Gruf::Loggable
 
-      attr_reader :options, :service
+      # @return [Gruf::Service] service The service to perform the hook against
+      attr_reader :service
+      # @return [Hash] options Options to use for the hook
+      attr_reader :options
 
       ##
-      # @param [Gruf::Service] service
-      # @param [Hash] options
+      # Initialize the hook and run setup
+      #
+      # @param [Gruf::Service] service The gruf service that the hook will perform against
+      # @param [Hash] options (Optional) A hash of options for this hook
       #
       def initialize(service, options = {})
         @service = service
@@ -36,9 +41,26 @@ module Gruf
 
       ##
       # Method that can be used to setup the hook prior to running it
+      #
       def setup
         # noop
       end
+
+      ##
+      # @return [String] Returns the service name as a translated name separated by periods
+      #
+      def service_key
+        service.class.name.underscore.tr('/', '.')
+      end
+
+      ##
+      # Parse the method signature into a service.method name format
+      #
+      # @return [String] The parsed service method name
+      #
+      def method_key(call_signature)
+        "#{service_key}.#{call_signature.to_s.gsub('_without_intercept', '')}"
+      end
     end
   end
 end

data/lib/gruf/hooks/registry.rb

@@ -23,15 +23,19 @@ module Gruf
     # Registry of all hooks added
     #
     class Registry
+      ##
+      # Error class that represents when a gruf hook does not extend the base class
+      #
       class HookDescendantError < StandardError; end
 
       class << self
         ##
         # Add an authentication strategy, either through a class or a block
         #
-        # @param [String] name
-        # @param [Gruf::Hooks::Base|NilClass] hook
-        # @return [Class]
+        # @param [String] name The name to represent the hook as
+        # @param [Gruf::Hooks::Base|NilClass] hook The strategy class to add. If nil, will expect
+        # a block that can be built as a hook instead
+        # @return [Class] The hook that was added
         #
         def add(name, hook = nil, &block)
           base = Gruf::Hooks::Base
@@ -47,7 +51,9 @@ module Gruf
         end
 
         ##
-        # Return a strategy type registry via a hash accessor syntax
+        # Return a hook via a hash accessor syntax
+        #
+        # @return [Gruf::Instrumentation::Base|NilClass] The requested hook, if exists
         #
         def [](name)
           _registry[name.to_sym]
@@ -63,28 +69,28 @@ module Gruf
         end
 
         ##
-        # @return [Hash<Class>]
+        # @return [Hash<Class>] Return the registry represented as a Hash object
         #
         def to_h
           _registry
         end
 
         ##
-        # @return [Boolean]
+        # @return [Boolean] Return true if there are any registered hooks
         #
         def any?
           count > 0
         end
 
         ##
-        # @return [Integer]
+        # @return [Integer] Return the number of registered hooks
         #
         def count
           to_h.keys.count
         end
 
         ##
-        # @return [Hash]
+        # @return [Hash] Clear all existing hooks from the registry
         #
         def clear
           @_registry = {}
@@ -93,7 +99,7 @@ module Gruf
         private
 
         ##
-        # @return [Hash<Class>]
+        # @return [Hash<Class>] Return the current registry
         #
         def _registry
           @_registry ||= {}

data/lib/gruf/instrumentation/base.rb

@@ -14,23 +14,27 @@
 # COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
+require_relative 'request_context'
+
 module Gruf
   module Instrumentation
     ##
-    # Base class for a hook. Define before, around, or after methods to utilize functionality.
+    # Base class for an instrumentation strategy. Define a call method to utilize functionality.
     #
     class Base
       include Gruf::Loggable
 
-      attr_reader :options, :service, :response, :request, :execution_time, :call_signature, :active_call
+      # @return [Gruf::Service] service The service to instrument
+      attr_reader :service
+      # @return [Hash] options Options to use when instrumenting the call
+      attr_reader :options
 
-      def initialize(service, request, response, execution_time, call_signature, active_call, options = {})
+      ##
+      # @param [Gruf::Service] service The service to instrument
+      # @param [Hash] options (Optional) Options to use when instrumenting the call
+      #
+      def initialize(service, options = {})
         @service = service
-        @request = request
-        @response = response
-        @execution_time = execution_time
-        @call_signature = call_signature.to_s.gsub('_without_intercept', '').to_sym
-        @active_call = active_call
         @options = options
         setup
       end
@@ -43,17 +47,68 @@ module Gruf
       end
 
       ##
-      # @return [Boolean]
+      # Was this call a success? If a response is a GRPC::BadStatus object, we assume that it was unsuccessful
       #
-      def success?
+      # @param [Object] response The gRPC response object
+      # @return [Boolean] True if was a successful call
+      #
+      def success?(response)
         !response.is_a?(GRPC::BadStatus)
       end
 
       ##
+      # Abstract method that is required for implementing an instrumentation strategy.
+      #
+      # @abstract
+      # @param [Gruf::Instrumentation::RequestContext] _rc The current request context for the call
       #
-      def call
+      def call(_rc)
         raise NotImplementedError
       end
+
+      ##
+      # Hook into the outer_around call to time the request, and pass that to the call method
+      #
+      # @param [Symbol] call_signature The method being called
+      # @param [Object] request The request object
+      # @param [GRPC::ActiveCall] active_call The gRPC active call object
+      # @param [Proc] &_block The execution block for the call
+      # @return [Object] result The result of the block that was called
+      #
+      def outer_around(call_signature, request, active_call, &_block)
+        timed = Timer.time do
+          yield
+        end
+        rc = RequestContext.new(
+          service: service,
+          request: request,
+          response: timed.result,
+          execution_time: timed.time,
+          call_signature: call_signature,
+          active_call: active_call
+        )
+        call(rc)
+        raise rc.response unless rc.success?
+        rc.response
+      end
+
+      ##
+      # @return [String] Returns the service name as a translated name separated by periods
+      #
+      def service_key
+        service.class.name.underscore.tr('/', '.')
+      end
+
+      ##
+      # Parse the method signature into a service.method name format
+      #
+      # @param [Symbol] call_signature The method call signature
+      # @param [String] delimiter The delimiter to separate service and method keys
+      # @return [String] The parsed service method name
+      #
+      def method_key(call_signature, delimiter: '.')
+        "#{service_key}#{delimiter}#{call_signature}"
+      end
     end
   end
 end

data/lib/gruf/instrumentation/output_metadata_timer.rb

@@ -23,14 +23,17 @@ module Gruf
       ##
       # Handle the instrumented response. Note: this will only instrument timings of _successful_ responses.
       #
-      def call
-        active_call.output_metadata.update(metadata_key => execution_time.to_s)
+      # @param [Gruf::Instrumentation::RequestContext] rc The current request context for the call
+      # @return [Hash] The resulting output metadata with the timer attached
+      #
+      def call(rc)
+        rc.active_call.output_metadata.update(metadata_key => rc.execution_time.to_s)
       end
 
       private
 
       ##
-      # @return [Symbol]
+      # @return [Symbol] The metadata key that the time result should be set to
       #
       def metadata_key
         options.fetch(:output_metadata_timer, {}).fetch(:metadata_key, :timer).to_sym

data/lib/gruf/instrumentation/registry.rb

@@ -17,6 +17,7 @@
 require_relative 'base'
 require_relative 'statsd'
 require_relative 'output_metadata_timer'
+require_relative 'request_logging/hook'
 
 module Gruf
   module Instrumentation
@@ -24,29 +25,37 @@ module Gruf
     # Registry of all hooks added
     #
     class Registry
-      class HookDescendantError < StandardError; end
+      ##
+      # Error class that represents when a instrumentation strategy does not extend the base class
+      #
+      class StrategyDescendantError < StandardError; end
 
       class << self
         ##
         # Add an authentication strategy, either through a class or a block
         #
-        # @param [String] name
-        # @param [Gruf::Hooks::Base|NilClass] hook
-        # @return [Class]
+        #   Gruf::Instrumentation::Registry.add(:my_instrumentor, MyInstrumentor)
         #
-        def add(name, hook = nil, &block)
+        # @param [String] name The name to represent the strategy as
+        # @param [Gruf::Hooks::Base|NilClass] strategy (Optional) The strategy class to add. If nil, will expect
+        # a block that can be built as a strategy instead
+        # @return [Class] The strategy that was added
+        #
+        def add(name, strategy = nil, &block)
           base = Gruf::Instrumentation::Base
-          hook ||= Class.new(base)
-          hook.class_eval(&block) if block_given?
+          strategy ||= Class.new(base)
+          strategy.class_eval(&block) if block_given?
 
-          raise HookDescendantError, "Hooks must descend from #{base}" unless hook.ancestors.include?(base)
+          raise StrategyDescendantError, "Hooks must descend from #{base}" unless strategy.ancestors.include?(base)
 
-          _registry[name.to_sym] = hook
+          _registry[name.to_sym] = strategy
         end
 
         ##
         # Return a strategy type registry via a hash accessor syntax
         #
+        # @return [Gruf::Instrumentation::Base|NilClass] The requested strategy, if exists
+        #
         def [](name)
           _registry[name.to_sym]
         end
@@ -61,21 +70,21 @@ module Gruf
         end
 
         ##
-        # @return [Hash<Class>]
+        # @return [Hash<Class>] Return the registry represented as a Hash object
         #
         def to_h
           _registry
         end
 
         ##
-        # @return [Boolean]
+        # @return [Boolean] Return true if there are any registered instrumentation strategies
         #
         def any?
           to_h.keys.count > 0
         end
 
         ##
-        # @return [Hash]
+        # @return [Hash] Clear all existing strategies from the registry
         #
         def clear
           @_registry = {}
@@ -84,7 +93,7 @@ module Gruf
         private
 
         ##
-        # @return [Hash<Class>]
+        # @return [Hash<Class>] Return the current registry
         #
         def _registry
           @_registry ||= {}

data/lib/gruf/instrumentation/request_context.rb

@@ -0,0 +1,66 @@
+module Gruf
+  module Instrumentation
+    ##
+    # Represents a request context for a given incoming gRPC request. This represents an injection layer that is used
+    # to pass to instrumentation strategies safely across thread boundaries.
+    #
+    class RequestContext
+      # @return [Gruf::Service] service The service to instrument
+      attr_reader :service
+      # @return [Object] request The protobuf request object
+      attr_reader :request
+      # @return [Object] response The protobuf response object
+      attr_reader :response
+      # @return [Symbol] call_signature The gRPC method on the service that was called
+      attr_reader :call_signature
+      # @return [GRPC::ActiveCall] active_call The gRPC core active call object, which represents marshalled data for
+      # the call itself
+      attr_reader :active_call
+      # @return [Time] execution_time The execution time, in ms, of the request
+      attr_reader :execution_time
+
+      ##
+      # Initialize the request context given the request and response
+      #
+      def initialize(
+        service:,
+        request:,
+        response:,
+        call_signature:,
+        active_call:,
+        execution_time: 0.00
+      )
+        @service = service
+        @request = request
+        @response = response
+        @call_signature = call_signature
+        @active_call = active_call
+        @execution_time = execution_time
+      end
+
+      ##
+      # @return [Boolean] True if the response is successful
+      #
+      def success?
+        !response.is_a?(GRPC::BadStatus)
+      end
+
+      ##
+      # @return [String] Return the response class name
+      #
+      def response_class_name
+        response.class.name
+      end
+
+      ##
+      # Return the execution time rounded to a specified precision
+      #
+      # @param [Integer] precision The amount of decimal places to round to
+      # @return [Float] The execution time rounded to the appropriate decimal point
+      #
+      def execution_time_rounded(precision: 2)
+        execution_time.to_f.round(precision)
+      end
+    end
+  end
+end

data/lib/gruf/instrumentation/request_logging/formatters/base.rb

@@ -0,0 +1,38 @@
+# coding: utf-8
+# Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Gruf
+  module Instrumentation
+    module RequestLogging
+      module Formatters
+        ##
+        # Base class for request log formatting
+        #
+        class Base
+          ##
+          # Format the parameters into a loggable string. Must be implemented in every derivative class
+          #
+          # @param [Hash] _payload The incoming request payload
+          # @return [String] The formatted string
+          #
+          def format(_payload)
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end