gruf 1.1.0 → 1.2.0

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

@@ -0,0 +1,40 @@
+# 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.
+#
+require 'json'
+
+module Gruf
+  module Instrumentation
+    module RequestLogging
+      module Formatters
+        ##
+        # Formats logging for gruf services into a Logstash-friendly JSON format
+        #
+        class Logstash < Base
+          ##
+          # Format the request into a JSON-friendly payload
+          #
+          # @param [Hash] payload The incoming request payload
+          # @return [String] The JSON representation of the payload
+          #
+          def format(payload)
+            payload.merge(format: 'json').to_json
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# 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
+        ##
+        # Formats the request into plaintext logging
+        #
+        class Plain < Base
+          ##
+          # Format the request by only outputting the message body and params (if set to log params)
+          #
+          # @param [Hash] payload The incoming request payload
+          # @return [String] The formatted string
+          #
+          def format(payload)
+            time = payload.fetch(:duration, 0)
+            grpc_status = payload.fetch(:grpc_status, 'GRPC::Ok')
+            route_key = payload.fetch(:method, 'unknown')
+            body = payload.fetch(:message, '')
+
+            msg = "[#{grpc_status}] (#{route_key}) [#{time}ms] #{body}".strip
+            msg += " Parameters: #{payload[:params].to_h}" if payload.key?(:params)
+            msg.strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gruf/instrumentation/request_logging/hook.rb

@@ -0,0 +1,145 @@
+# 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.
+#
+require 'socket'
+require_relative 'formatters/base'
+require_relative 'formatters/logstash'
+require_relative 'formatters/plain'
+
+module Gruf
+  module Instrumentation
+    module RequestLogging
+      ##
+      # Represents an error if the formatter does not extend the base formatter
+      #
+      class InvalidFormatterError < StandardError; end
+
+      ##
+      # Handles Rails-style request logging for gruf services.
+      #
+      # This is added by default to gruf servers; if you have `Gruf.use_default_hooks = false`, you can add it back
+      # manually by doing:
+      #
+      #   Gruf::Instrumentation::Registry.add(:request_logging, Gruf::Instrumentation::RequestLogging::Hook)
+      #
+      class Hook < ::Gruf::Instrumentation::Base
+
+        ###
+        # Log the request, sending it to the appropriate formatter
+        #
+        # @param [Gruf::Instrumentation::RequestContext] rc The current request context for the call
+        # @return [String]
+        #
+        def call(rc)
+          if rc.success?
+            type = :info
+            status_name = 'GRPC::Ok'
+          else
+            type = :error
+            status_name = rc.response_class_name
+          end
+
+          payload = {}
+          payload[:params] = sanitize(rc.request.to_h) if options.fetch(:log_parameters, false)
+          payload[:message] = message(rc)
+          payload[:service] = service_key
+          payload[:method] = rc.call_signature
+          payload[:action] = rc.call_signature
+          payload[:grpc_status] = status_name
+          payload[:duration] = rc.execution_time_rounded
+          payload[:status] = status(rc.response, rc.success?)
+          payload[:thread_id] = Thread.current.object_id
+          payload[:time] = Time.now.to_s
+          payload[:host] = Socket.gethostname
+
+          ::Gruf.logger.send(type, formatter.format(payload))
+        end
+
+        private
+
+        ##
+        # Return an appropriate log message dependent on the status
+        #
+        # @param [RequestContext] rc The current request context
+        # @return [String] The appropriate message body
+        #
+        def message(rc)
+          if rc.success?
+            "[GRPC::Ok] (#{service_key}.#{rc.call_signature})"
+          else
+            "[#{rc.response_class_name}] (#{service_key}.#{rc.call_signature}) #{rc.response.message}"
+          end
+        end
+
+        ##
+        # Return the proper status code for the response
+        #
+        # @param [Object] response The response object
+        # @param [Boolean] successful If the response was successful
+        # @return [Boolean] The proper status code
+        #
+        def status(response, successful)
+          successful ? GRPC::Core::StatusCodes::OK : response.code
+        end
+
+        ##
+        # Determine the appropriate formatter for the request logging
+        #
+        # @return [Gruf::Instrumentation::RequestLogging::Formatters::Base]
+        #
+        def formatter
+          unless @formatter
+            fmt = options.fetch(:formatter, :plain)
+            @formatter = case fmt
+              when Symbol
+                klass = "Gruf::Instrumentation::RequestLogging::Formatters::#{fmt.to_s.capitalize}"
+                fmt = klass.constantize.new
+              when Class
+                fmt = fmt.new
+              else
+                fmt
+            end
+            raise Gruf::Instrumentation::RequestLogging::InvalidFormatterError unless fmt.is_a?(Gruf::Instrumentation::RequestLogging::Formatters::Base)
+          end
+          @formatter
+        end
+
+        ##
+        # Redact any blacklisted params and return an updated hash
+        #
+        # @param [Hash] params The hash of parameters to sanitize
+        # @return [Hash] The sanitized params in hash form
+        #
+        def sanitize(params = {})
+          blacklist = options.fetch(:blacklist, []).map(&:to_s)
+          redacted_string = options.fetch(:redacted_string, 'REDACTED')
+          params.each do |param, _value|
+            params[param] = redacted_string if blacklist.include?(param.to_s)
+          end
+        end
+
+        ##
+        # Fetch the options for this hook
+        #
+        # @return [Hash] Return a hash of options for this hook
+        #
+        def options
+          super().fetch(:request_logging, {})
+        end
+      end
+    end
+  end
+end

data/lib/gruf/instrumentation/statsd.rb

@@ -23,10 +23,14 @@ module Gruf
       ##
       # Push data to StatsD, only doing so if a client is set
       #
-      def call
+      # @param [Gruf::Instrumentation::RequestContext] rc The current request context for the call
+      #
+      def call(rc)
         if client
-          client.increment(route_key)
-          client.timing(route_key, execution_time)
+          rk = route_key(rc.call_signature)
+          client.increment(rk)
+          client.increment("#{rk}.#{postfix(rc.success?)}")
+          client.timing(rk, rc.execution_time)
         else
           Gruf.logger.error 'Statsd module loaded, but no client configured!'
         end
@@ -35,21 +39,23 @@ module Gruf
       private
 
       ##
-      # @return [String]
+      # @param [Boolean] successful Whether or not the request was successful
+      # @return [String] The appropriate postfix for the key dependent on response status
       #
-      def route_key
-        "#{key_prefix}#{service_key}.#{call_signature}"
+      def postfix(successful)
+        successful ? 'success' : 'failure'
       end
 
       ##
-      # @return [String]
+      # @param [Symbol] call_signature The method call signature for the handler
+      # @return [String] Return a composed route key that is used in the statsd metric
       #
-      def service_key
-        service.class.name.underscore.tr('/', '.')
+      def route_key(call_signature)
+        "#{key_prefix}#{method_key(call_signature)}"
       end
 
       ##
-      # @return [String]
+      # @return [String] Return the sanitized key prefix for the statsd metric key
       #
       def key_prefix
         prefix = options.fetch(:prefix, '').to_s
@@ -57,17 +63,17 @@ module Gruf
       end
 
       ##
-      # @return [::Statsd]
+      # @return [::Statsd] Return the given StatsD client
       #
       def client
         @client ||= options.fetch(:client, nil)
       end
 
       ##
-      # @return [Hash]
+      # @return [Hash] Return a hash of options for this hook
       #
       def options
-        @options.fetch(:statsd, {})
+        super().fetch(:statsd, {})
       end
     end
   end

data/lib/gruf/loggable.rb

@@ -15,9 +15,12 @@
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Gruf
+  ##
+  # Mixin that allows any Gruf class to have easy access to the Gruf logger
+  #
   module Loggable
     ##
-    # @return [Logger]
+    # @return [Logger] The set logger for Gruf
     #
     def logger
       Gruf.logger

data/lib/gruf/logging.rb

@@ -15,19 +15,38 @@
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Gruf
+  ##
+  # Handles internal gruf logging requests
+  #
   module Logger
+    ##
+    # Return the current Gruf logger
+    #
+    # @return [Logger]
+    #
     def logger
       Gruf.logger
     end
   end
 
+  ##
+  # Handles grpc internal logging requests
+  #
   module GrpcLogger
+    ##
+    # Return the current Gruf gRPC core logger
+    #
+    # @return [Logger]
+    #
     def logger
       Gruf.grpc_logger
     end
   end
 end
 
+##
+# Implements gruf's gRPC logger into the gRPC library logger
+#
 module GRPC
   extend Gruf::GrpcLogger
 end

data/lib/gruf/response.rb

@@ -19,11 +19,24 @@ module Gruf
   # Wraps the active call operation to provide metadata and timing around the request
   #
   class Response
-    attr_reader :operation, :metadata, :trailing_metadata, :deadline, :cancelled, :execution_time
+    # @return [GRPC::ActiveCall::Operation] The operation that was executed for the given request
+    attr_reader :operation
+    # @return [Hash] The metadata that was attached to the operation
+    attr_reader :metadata
+    # @return [Hash] The trailing metadata that the service returned
+    attr_reader :trailing_metadata
+    # @return [Time] The set deadline on the call
+    attr_reader :deadline
+    # @return [Boolean] Whether or not the operation was cancelled
+    attr_reader :cancelled
+    # @return [Float] The time that the request took to execute
+    attr_reader :execution_time
 
     ##
-    # @param [GRPC::ActiveCall::Operation] op
-    # @param [Float] execution_time
+    # Initialize a response object with the given gRPC operation
+    #
+    # @param [GRPC::ActiveCall::Operation] op The given operation for the current call
+    # @param [Float] execution_time The amount of time that the response took to occur
     #
     def initialize(op, execution_time = nil)
       @operation = op
@@ -38,6 +51,8 @@ module Gruf
     ##
     # Return the message returned by the request
     #
+    # @return [Object] The protobuf response message
+    #
     def message
       @message ||= op.execute
     end
@@ -45,7 +60,7 @@ module Gruf
     ##
     # Return execution time of the call internally on the server in ms
     #
-    # @return [Integer]
+    # @return [Float] The execution time of the response
     #
     def internal_execution_time
       key = Gruf.instrumentation_options.fetch(:output_metadata_timer, {}).fetch(:metadata_key, 'timer')

data/lib/gruf/serializers/errors/base.rb

@@ -21,24 +21,31 @@ module Gruf
       # Base class for serialization of errors for transport across the grpc protocol
       #
       class Base
+        # @return [Gruf::Error|String] The error being serialized
         attr_reader :error
 
         ##
-        # @param [Gruf::Error|String] err
+        # @param [Gruf::Error|String] err The error to serialize
         #
         def initialize(err)
           @error = err
         end
 
         ##
-        # @return [String]
+        # Must be implemented in a derived class. This method should serialize the error into a transportable String
+        # that can be pushed into GRPC metadata across the wire.
+        #
+        # @return [String] The serialized error
         #
         def serialize
           raise NotImplementedError
         end
 
         ##
-        # @return [Object|Hash]
+        # Must be implemented in a derived class. This method should deserialize the error object that is transported
+        # over the gRPC trailing metadata payload.
+        #
+        # @return [Object|Hash] The deserialized error object
         #
         def deserialize
           raise NotImplementedError

data/lib/gruf/serializers/errors/json.rb

@@ -19,16 +19,19 @@ require 'json'
 module Gruf
   module Serializers
     module Errors
+      ##
+      # Serializes the error via JSON for transport
+      #
       class Json < Base
         ##
-        # @return [String]
+        # @return [String] The serialized JSON string
         #
         def serialize
           @error.to_h.to_json
         end
 
         ##
-        # @return [Object|Hash]
+        # @return [Hash] A hash deserialized from the inputted JSON
         #
         def deserialize
           JSON.parse(@error)