right_support 1.1.2 → 1.2.0

data/lib/right_support/log.rb

@@ -32,3 +32,7 @@ end
 require 'right_support/log/system_logger'
 require 'right_support/log/filter_logger'
 require 'right_support/log/tag_logger'
+require 'right_support/log/null_logger'
+require 'right_support/log/multiplexer'
+require 'right_support/log/exception_logger'
+require 'right_support/log/mixin'

data/lib/right_support/log/exception_logger.rb

@@ -0,0 +1,86 @@
+#
+# Copyright (c) 2012 RightScale Inc
+#
+# 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 RightSupport::Log
+  # A logger that prepends a tag to every message that is emitted. Can be used to
+  # correlate logs with a Web session ID, transaction ID or other context.
+  #
+  # The user of this logger is responsible for calling #tag= to set the tag as
+  # appropriate, e.g. in a Web request around-filter.
+  #
+  # This logger uses thread-local storage (TLS) to provide tagging on a per-thread
+  # basis; however, it does not account for EventMachine, neverblock, the use of
+  # Ruby fibers, or any other phenomenon that can "hijack" a thread's call stack.
+  #
+  class ExceptionLogger < FilterLogger
+    # Format exception information
+    #
+    # === Parameters
+    # description(String):: Error description
+    # exception(Exception|String):: Associated exception or other parenthetical error information
+    # backtrace(Symbol):: Exception backtrace extent: :no_trace, :caller, or :trace,
+    #   defaults to :caller
+    #
+    # === Return
+    # (String):: Information about the exception in a format suitable for logging
+    def self.format_exception(description, exception = nil, backtrace = :caller)
+      if exception
+        if exception.respond_to?(:message)
+          description += " (#{exception.class}: #{exception.message}"
+        else
+          description += " (#{exception}"
+        end
+
+        unless exception.respond_to?(:backtrace) && exception.backtrace
+          backtrace = :no_trace
+        end
+
+        case backtrace
+          when :no_trace
+            description += ")"
+          when :caller
+            description += " IN " + exception.backtrace[0] + ")"
+          when :trace
+            description += " IN\n  " + exception.backtrace.join("\n  ") + ")"
+          else
+            raise ArgumentError, "Unknown backtrace value #{backtrace.inspect}"
+        end
+      end
+
+      description
+    end
+
+    # Log information about an exception with ERROR severity.
+    #
+    # === Parameters
+    # description(String):: Error description
+    # exception(Exception|String):: Associated exception or other parenthetical error information
+    # backtrace(Symbol):: Exception backtrace extent: :no_trace, :caller, or :trace,
+    #   defaults to :caller
+    #
+    # === Return
+    # Forwards the return value of its underlying logger's #error method
+    def exception(description, exception = nil, backtrace = :caller)
+      error(self.class.format_exception(description, exception, backtrace))
+    end
+  end
+end

data/lib/right_support/log/filter_logger.rb

@@ -27,7 +27,19 @@ module RightSupport::Log
   # before they are passed to the underlying Logger. Can be used to for various log-
   # processing tasks such as filtering sensitive data or tagging log lines with a
   # context marker.
+  #
+  # FilterLogger implements method_missing and respond_to? and proxies unknown
+  # method calls to its underlying logger; this allows it to be used as a
+  # decorator.
   class FilterLogger < Logger
+    SEVERITY_TO_METHOD = {
+        DEBUG => :debug,
+        INFO  => :info,
+        WARN  => :warn,
+        ERROR => :error,
+        FATAL => :fatal,
+    }
+
     # Initialize a new instance of this class.
     #
     # === Parameters
@@ -35,7 +47,70 @@ module RightSupport::Log
     #
     def initialize(actual_logger)
       @actual_logger = actual_logger
+    end
+
+    def method_missing(meth, *args)
+      return @actual_logger.__send__(meth, *args) if @actual_logger.respond_to?(meth)
+      super
+    end
+
+    def respond_to?(meth)
+      super(meth) || @actual_logger.respond_to?(meth)
+    end
 
+    # Log a message, filtering the severity and/or message and dispatching
+    # to the corresponding severity-method of the underlying logger.
+    #
+    # See #info for more information.
+    def debug(message = nil, &block)
+      severity, message = filter(DEBUG, message)
+      meth = SEVERITY_TO_METHOD[severity]
+      raise ArgumentError, "Filter emitted unknown severity #{severity.inspect}" unless meth
+      @actual_logger.__send__(meth, message, &block)
+    end
+
+    # Log a message, filtering the severity and/or message and dispatching
+    # to the corresponding severity-method of the underlying logger.
+    #
+    # See #info for more information.
+    def info(message = nil, &block)
+      severity, message = filter(INFO, message)
+      meth = SEVERITY_TO_METHOD[severity]
+      raise ArgumentError, "Filter emitted unknown severity #{severity.inspect}" unless meth
+      @actual_logger.__send__(meth, message, &block)
+    end
+
+    # Log a message, filtering the severity and/or message and dispatching
+    # to the corresponding severity-method of the underlying logger.
+    #
+    # See #info for more information.
+    def warn(message = nil, &block)
+      severity, message = filter(WARN, message)
+      meth = SEVERITY_TO_METHOD[severity]
+      raise ArgumentError, "Filter emitted unknown severity #{severity.inspect}" unless meth
+      @actual_logger.__send__(meth, message, &block)
+    end
+
+    # Log a message, filtering the severity and/or message and dispatching
+    # to the corresponding severity-method of the underlying logger.
+    #
+    # See #info for more information.
+    def error(message = nil, &block)
+      severity, message = filter(ERROR, message)
+      meth = SEVERITY_TO_METHOD[severity]
+      raise ArgumentError, "Filter emitted unknown severity #{severity.inspect}" unless meth
+      @actual_logger.__send__(meth, message, &block)
+    end
+
+    # Log a message, filtering the severity and/or message and dispatching
+    # to the corresponding severity-method of the underlying logger.
+    #
+    # See #info for more information.
+    def fatal(message = nil, &block)
+      severity, message = filter(FATAL, message)
+      meth = SEVERITY_TO_METHOD[severity]
+      raise ArgumentError, "Filter emitted unknown severity #{severity.inspect}" unless meth
+      @actual_logger.__send__(meth, message, &block)
     end
 
     # Add a log line, filtering the severity and message before calling through

data/lib/right_support/log/mixin.rb

@@ -0,0 +1,104 @@
+#
+# Copyright (c) 2012 RightScale Inc
+#
+# 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 RightSupport::Log
+  # A mixin that facilitates access to a logger for classes that want logging functionality.
+  #
+  # === Basic Usage
+  # Your class must opt into logging by including the mixin:
+  #   class AwesomenessProcessor
+  #     include RightSupport::Log::Mixin
+  #
+  # Having opted in, your class now has a #logger instance method, as well as a .logger
+  # class method, which allows logging from either instance or class methods:
+  #
+  #   def self.prepare_awesomeness_for_processing(input)
+  #     logger.info "Preparing a #{input.class.name} for additional awesomeness"
+  #   end
+  #
+  #   def process_awesomeness(input)
+  #     input = self.class.prepare_awesomeness(input)
+  #     logger.info "Processing #{input.size} units of awesomeness"
+  #   end
+  #
+  # === Controlling Where Log Messages Go
+  # By default, your class shares a Logger object with all other classes that include the mixin.
+  # This process-wide default logger can be set or retrieved using module-level accessors:
+  #
+  #   # default_logger starts out as a NullLogger; you probably want to set it to something different
+  #   puts "Current logger: "+ RightSupport::Log::Mixin.default_logger.class
+  #   RightSupport::Log::Mixin.default_logger = SyslogLogger.new('my program')
+  #
+  # It is good form to set the default logger; however, if your class needs additional or different
+  # logging functionality, you can override the logger on a per-class level:
+  #   AwesomenessProcessor.logger = Logger.new(File.open('awesomeness.log', 'w'))
+  #
+  # Finally, you can override the logger on a per-instance level for truly fine-grained control.
+  # This is generally useless, but just in case:
+  #   processor = AwesomenessProcessor.new
+  #   processor.logger = Logger.new(File.open("#{processor.object_id}.log", 'w'))
+  #
+  module Mixin
+    # A decorator class which will be wrapped around any logger that is
+    # provided to any of the setter methods. This ensures that ExceptionLogger's
+    # methods will always be available to anyone who uses this mixin for logging.
+    Decorator = RightSupport::Log::ExceptionLogger
+
+    # Class methods that become available to classes that include Mixin.
+    module ClassMethods
+      def logger
+        @logger || RightSupport::Log::Mixin.default_logger
+      end
+
+      def logger=(logger)
+        logger = Decorator.new(logger) unless logger.nil? || logger.is_a?(Decorator)
+        @logger = logger
+      end
+    end
+
+    # Instance methods that become available to classes that include Mixin.
+    module InstanceMethods
+      def logger
+        @logger || self.class.logger
+      end
+
+      def logger=(logger)
+        logger = Decorator.new(logger) unless logger.nil? || logger.is_a?(Decorator)
+        @logger = logger
+      end
+    end
+
+    def self.default_logger
+      @default_logger ||= Decorator.new(RightSupport::Log::NullLogger.new)
+    end
+
+    def self.default_logger=(logger)
+      logger = Decorator.new(logger) unless logger.nil? || logger.is_a?(Decorator)
+      @default_logger = logger
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.__send__(:include, InstanceMethods)
+    end
+  end
+end

data/lib/right_support/log/multiplexer.rb

@@ -0,0 +1,93 @@
+#
+# Copyright (c) 2009-2012 RightScale Inc
+#
+# 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 RightSupport::Log
+  # A log multiplexer that uses method_missing to dispatch method calls to zero or more
+  # target loggers. Caveat emptor: _you_ are responsible for ensuring that all of the targets
+  # respond to all of the messages you care to send; this class will perform no error checking
+  # for you!
+  class Multiplexer
+
+    # Access to underlying list of multiplexed objects
+    attr_reader :targets
+
+    # Prevent Kernel#warn from being called; #warn should be multiplexed to targets.
+    undef warn rescue nil
+
+    # Create a new multiplexer with a default list of targets.
+    #
+    # === Parameters
+    # targets(Object):: Targets that should receive the method calls
+    def initialize(*targets)
+      @targets = targets || []
+    end
+
+    # Add object to list of multiplexed targets
+    #
+    # === Parameters
+    # target(Object):: Add target to list of multiplexed targets
+    #
+    # === Return
+    # self(RightScale::Multiplexer):: self so operation can be chained
+    def add(target)
+      @targets << target unless @targets.include?(target)
+      self
+    end
+
+    # Remove object from list of multiplexed targets
+    #
+    # === Parameters
+    # target(Object):: Remove target from list of multiplexed targets
+    #
+    # === Return
+    # self(RightScale::Multiplexer):: self so operation can be chained
+    def remove(target)
+      @targets.delete_if { |t| t == target }
+      self
+    end
+
+    # Access target at given index
+    #
+    # === Parameters
+    # index(Integer):: Target index
+    #
+    # === Return
+    # target(Object):: Target at index 'index' or nil if none
+    def [](index)
+      target = @targets[index]
+    end
+
+    # Forward any method invocation to targets
+    #
+    # === Parameters
+    # m(Symbol):: Method that should be multiplexed
+    # args(Array):: Arguments
+    #
+    # === Return
+    # res(Object):: Result of first target in list
+    def method_missing(m, *args)
+      res = @targets.inject([]) { |res, t| res << t.__send__(m, *args) }
+      res[0]
+    end
+
+  end
+end

data/lib/right_support/log/null_logger.rb

@@ -0,0 +1,76 @@
+#
+# Copyright (c) 2012 RightScale Inc
+#
+# 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 'logger'
+
+module RightSupport::Log
+  # A logger than does not perform any logging. This is useful to send log entries
+  # to "the bit bucket" or "to /dev/null" -- hence the name.
+  class NullLogger < Logger
+    # Initialize a new instance of this class.
+    #
+    def initialize
+      super(nil)
+    end
+
+    # Do nothing. This method exists for interface compatibility with Logger.
+    #
+    # === Parameters
+    # severity(Integer):: one of the Logger severity constants
+    # message(String):: the message to log, or nil
+    # progname(String):: the program name, or nil
+    #
+    # === Block
+    # If message == nil and a block is given, yields to the block. The block's
+    # output value is ignored.
+    #
+    # === Return
+    # always returns true
+    def add(severity, message = nil, progname = nil, &block)
+      #act like a real Logger w/r/t the block
+      yield if message.nil? && block_given?
+      true
+    end
+
+    # Do nothing. This method exists for interface compatibility with Logger.
+    #
+    # === Parameters
+    # msg(String):: the message to log, or nil
+    #
+    # === Block
+    # If message == nil and a block is given, yields to the block. The block's
+    # output value is ignored.
+    #
+    # === Return
+    def <<(msg)
+      msg.to_s.size
+    end
+
+    # Do nothing. This method exists for interface compatibility with Logger.
+    #
+    # === Return
+    # always returns true
+    def close
+      nil
+    end
+  end
+end