sapience 0.1.1

data/lib/sapience/base.rb

@@ -0,0 +1,381 @@
+module Sapience
+  class Base
+    # Class name to be logged
+    attr_accessor :name, :filter
+
+    # Set the logging level for this logger
+    #
+    # Note: This level is only for this particular instance. It does not override
+    #   the log level in any logging instance or the default log level
+    #   Sapience.config.default_level
+    #
+    # Must be one of the values in Sapience::LEVELS, or
+    # nil if this logger instance should use the global default level
+    def level=(level)
+      @level_index = Sapience.config.level_to_index(level)
+      @level       = Sapience.config.index_to_level(@level_index)
+    end
+
+    # Returns the current log level if set, otherwise it returns the global
+    # default log level
+    def level
+      @level || Sapience.config.default_level
+    end
+
+    # Implement the log level calls
+    #   logger.debug(message, hash|exception=nil, &block)
+    #
+    # Implement the log level query
+    #   logger.debug?
+    #
+    # Parameters:
+    #   message
+    #     [String] text message to be logged
+    #     Should always be supplied unless the result of the supplied block returns
+    #     a string in which case it will become the logged message
+    #     Default: nil
+    #
+    #   payload
+    #     [Hash|Exception] Optional hash payload or an exception to be logged
+    #     Default: nil
+    #
+    #   exception
+    #     [Exception] Optional exception to be logged
+    #     Allows both an exception and a payload to be logged
+    #     Default: nil
+    #
+    # Examples:
+    #    require 'sapience'
+    #
+    #    # Enable trace level logging
+    #    Sapience.config.default_level = :info
+    #
+    #    # Log to screen
+    #    Sapience.add_appender(:file, io: STDOUT, formatter: :color)
+    #
+    #    # And log to a file at the same time
+    #    Sapience.add_appender(:file, file_name: 'application.log', formatter: :color)
+    #
+    #    logger = Sapience['MyApplication']
+    #    logger.debug("Only display this if log level is set to Debug or lower")
+    #
+    #    # Log information along with a text message
+    #    logger.info("Request received", user: "joe", duration: 100)
+    #
+    #    # Log an exception
+    #    logger.info("Parsing received XML", exc)
+    #
+    Sapience::LEVELS.each_with_index do |level, index|
+      class_eval <<-EOT, __FILE__, __LINE__ + 1
+        def #{level}(message=nil, payload=nil, exception=nil, &block)
+          if level_index <= #{index}
+            log_internal(:#{level}, #{index}, message, payload, exception, &block)
+            true
+          else
+            false
+          end
+        end
+
+        def #{level}?
+          level_index <= #{index}
+        end
+
+        def measure_#{level}(message, params = {}, &block)
+          if level_index <= #{index}
+            measure_internal(:#{level}, #{index}, message, params, &block)
+          else
+            block.call(params) if block
+          end
+        end
+
+        def benchmark_#{level}(message, params = {}, &block)
+          if level_index <= #{index}
+            measure_internal(:#{level}, #{index}, message, params, &block)
+          else
+            block.call(params) if block
+          end
+        end
+      EOT
+    end
+
+    # Dynamically supply the log level with every measurement call
+    def measure(level, message, params = {}, &block)
+      index = Sapience.config.level_to_index(level)
+      if level_index <= index
+        measure_internal(level, index, message, params, &block)
+      else
+        block.call(params) if block
+      end
+    end
+
+    alias_method :benchmark, :measure
+
+    # :nodoc:
+    def tagged(*tags, &block)
+      Sapience.tagged(*tags, &block)
+    end
+
+    # :nodoc:
+    alias_method :with_tags, :tagged
+
+    # :nodoc:
+    def tags
+      Sapience.tags
+    end
+
+    # :nodoc:
+    def push_tags(*tags)
+      Sapience.push_tags(*tags)
+    end
+
+    # :nodoc:
+    def pop_tags(quantity = 1)
+      Sapience.pop_tags(quantity)
+    end
+
+    # :nodoc:
+    def silence(new_level = :error, &block)
+      Sapience.silence(new_level, &block)
+    end
+
+    # :nodoc:
+    def fast_tag(tag, &block)
+      Sapience.fast_tag(tag, &block)
+    end
+
+    # Thread specific context information to be logged with every log entry
+    #
+    # Add a payload to all log calls on This Thread within the supplied block
+    #
+    #   logger.with_payload(tracking_number: 12345) do
+    #     logger.debug('Hello World')
+    #   end
+    #
+    # If a log call already includes a pyload, this payload will be merged with
+    # the supplied payload, with the supplied payload taking precedence
+    #
+    #   logger.with_payload(tracking_number: 12345) do
+    #     logger.debug('Hello World', result: 'blah')
+    #   end
+    def with_payload(payload)
+      current_payload                          = self.payload
+      Thread.current[:sapience_payload] = current_payload ? current_payload.merge(payload) : payload
+      yield
+    ensure
+      Thread.current[:sapience_payload] = current_payload
+    end
+
+    # Returns [Hash] payload to be added to every log entry in the current scope
+    # on this thread.
+    # Returns nil if no payload is currently set
+    def payload
+      Thread.current[:sapience_payload]
+    end
+
+    protected
+
+    # Write log data to underlying data storage
+    def log(_log_)
+      raise NotImplementedError.new('Logging Appender must implement #log(log)')
+    end
+
+    private
+
+    # Initializer for Abstract Class Sapience::Base
+    #
+    # Parameters
+    #  klass [String]
+    #   Name of the class, module, or other identifier for which the log messages
+    #   are being logged
+    #
+    #  level [Symbol]
+    #    Only allow log entries of this level or higher to be written to this appender
+    #    For example if set to :warn, this appender would only log :warn and :fatal
+    #    log messages when other appenders could be logging :info and lower
+    #
+    #  filter [Regexp|Proc]
+    #    RegExp: Only include log messages where the class name matches the supplied
+    #    regular expression. All other messages will be ignored
+    #    Proc: Only include log messages where the supplied Proc returns true
+    #          The Proc must return true or false
+    def initialize(klass, level = nil, filter = nil) # rubocop:disable AbcSize, PerceivedComplexity, CyclomaticComplexity
+      # Support filtering all messages to this logger using a Regular Expression
+      # or Proc
+      raise ':filter must be a Regexp or Proc' unless filter.nil? || filter.is_a?(Regexp) || filter.is_a?(Proc)
+
+      @filter = filter.is_a?(Regexp) ? filter.freeze : filter
+      @name   = klass.is_a?(String) ? klass : klass.name
+      if level.nil?
+        # Allow the global default level to determine this loggers log level
+        @level_index = nil
+        @level       = nil
+      else
+        self.level = level
+      end
+    end
+
+    # Return the level index for fast comparisons
+    # Returns the global default level index if the level has not been explicitly
+    # set for this instance
+    def level_index
+      @level_index || Sapience.config.default_level_index
+    end
+
+    # Whether to log the supplied message based on the current filter if any
+    def include_message?(log)
+      return true if @filter.nil?
+
+      if @filter.is_a?(Regexp)
+        (@filter =~ log.name) != nil
+      elsif @filter.is_a?(Proc)
+        @filter.call(log) == true
+      end
+    end
+
+    # Whether the log message should be logged for the current logger or appender
+    def should_log?(log)
+      # Ensure minimum log level is met, and check filter
+      (level_index <= (log.level_index || 0)) && include_message?(log)
+    end
+
+    # Log message at the specified level
+    def log_internal(level, index, message = nil, payload = nil, exception = nil) # rubocop:disable AbcSize, PerceivedComplexity, CyclomaticComplexity
+      # Exception being logged?
+      if exception.nil? && payload.nil? && message.respond_to?(:backtrace) && message.respond_to?(:message)
+        exception = message
+        message   = nil
+      elsif exception.nil? && payload && payload.respond_to?(:backtrace) && payload.respond_to?(:message)
+        exception = payload
+        payload   = nil
+      end
+
+      # Add result of block as message or payload if not nil
+      if block_given? && (result = yield)
+        if result.is_a?(String)
+          message = message.nil? ? result : "#{message} -- #{result}"
+        elsif message.nil? && result.is_a?(Hash)
+          message = result
+        elsif payload && payload.respond_to?(:merge)
+          payload.merge(result)
+        else
+          payload = result
+        end
+      end
+
+      # Add scoped payload
+      if self.payload
+        payload = payload.nil? ? self.payload : self.payload.merge(payload)
+      end
+
+      # Add caller stack trace
+      backtrace = extract_backtrace if index >= Sapience.config.backtrace_level_index
+
+      log = Log.new(level, Thread.current.name, name, message, payload, Time.now, nil, tags, index, exception, nil, backtrace)
+
+      # Logging Hash only?
+      # logger.info(name: 'value')
+      if payload.nil? && exception.nil? && message.is_a?(Hash)
+        payload           = message.dup
+        min_duration      = payload.delete(:min_duration) || 0.0
+        log.exception     = payload.delete(:exception)
+        log.message       = payload.delete(:message)
+        log.metric        = payload.delete(:metric)
+        log.metric_amount = payload.delete(:metric_amount) || 1
+        if duration = payload.delete(:duration)
+          return false if duration <= min_duration
+          log.duration = duration
+        end
+        log.payload = payload if payload.size > 0
+      end
+
+      self.log(log) if include_message?(log)
+    end
+
+    SELF_PATTERN = File.join('lib', 'sapience')
+
+    # Extract the callers backtrace leaving out Sapience
+    def extract_backtrace
+      stack = caller
+      while (first = stack.first) && first.include?(SELF_PATTERN)
+        stack.shift
+      end
+      stack
+    end
+
+    # Measure the supplied block and log the message
+    def measure_internal(level, index, message, params) # rubocop:disable AbcSize, PerceivedComplexity, CyclomaticComplexity
+      start     = Time.now
+      exception = nil
+      begin
+        if block_given?
+          result    =
+            if silence_level = params[:silence]
+              # In case someone accidentally sets `silence: true` instead of `silence: :error`
+              silence_level = :error if silence_level == true
+              silence(silence_level) { yield(params) }
+            else
+              yield(params)
+            end
+          exception = params[:exception]
+          result
+        end
+      rescue Exception => exc # rubocop:disable RescueException
+        exception = exc
+      ensure
+        end_time           = Time.now
+        # Extract options after block completes so that block can modify any of the options
+        log_exception      = params[:log_exception] || :partial
+        on_exception_level = params[:on_exception_level]
+        min_duration       = params[:min_duration] || 0.0
+        payload            = params[:payload]
+        metric             = params[:metric]
+        duration           =
+          if block_given?
+            1000.0 * (end_time - start)
+          else
+            params[:duration] || fail('Mandatory block missing when :duration option is not supplied')
+          end
+
+        # Add scoped payload
+        if self.payload
+          payload = payload.nil? ? self.payload : self.payload.merge(payload)
+        end
+        if exception
+          logged_exception = exception
+          backtrace        = nil
+          case log_exception
+          when :full
+            # On exception change the log level
+            if on_exception_level
+              level = on_exception_level
+              index = Sapience.config.level_to_index(level)
+            end
+          when :partial
+            # On exception change the log level
+            if on_exception_level
+              level = on_exception_level
+              index = Sapience.config.level_to_index(level)
+            end
+            message          = "#{message} -- Exception: #{exception.class}: #{exception.message}"
+            logged_exception = nil
+            backtrace        = exception.backtrace
+          else
+            # Log the message with its duration but leave out the exception that was raised
+            logged_exception = nil
+            backtrace        = exception.backtrace
+          end
+          log = Log.new(level, Thread.current.name, name, message, payload, end_time, duration, tags, index, logged_exception, metric, backtrace)
+          self.log(log) if include_message?(log)
+          raise exception
+        elsif duration >= min_duration
+          # Only log if the block took longer than 'min_duration' to complete
+          # Add caller stack trace
+          backtrace = extract_backtrace if index >= Sapience.config.backtrace_level_index
+
+          log = Log.new(level, Thread.current.name, name, message, payload, end_time, duration, tags, index, nil, metric, backtrace)
+          self.log(log) if include_message?(log)
+        end
+      end
+    end
+  end
+end

data/lib/sapience/concerns/compatibility.rb

@@ -0,0 +1,53 @@
+# :nodoc:
+module Sapience
+  # :nodoc:
+  module Concerns
+    # :nodoc:
+    module Compatibility
+      #
+      # For compatibility with Ruby Logger only.
+      #
+      def self.included(base)
+        base.class_eval do
+          # Map :unknown to :error
+          alias_method :unknown, :error # :nodoc:
+          alias_method :unknown?, :error? # :nodoc:
+
+          alias_method :<<, :info # :nodoc:
+          # Active Record's Session Store calls silence_logger
+          alias_method :silence_logger, :silence # :nodoc:
+
+          alias_method :progname, :name # :nodoc:
+          alias_method :progname=, :name= # :nodoc:
+
+          alias_method :sev_threshold, :level # :nodoc:
+          alias_method :sev_threshold=, :level= # :nodoc:
+
+          attr_accessor :formatter # :nodoc:
+          attr_accessor :datetime_format # :nodoc:
+        end
+      end
+
+      # :nodoc:
+      def close
+      end
+
+      # :nodoc:
+      def reopen(_logdev = nil)
+      end
+
+      # :nodoc:
+      def add(severity, message = nil, progname = nil, &block)
+        index = Sapience.config.level_to_index(severity)
+        if level_index <= index
+          level = Sapience.config.index_to_level(index)
+          log_internal(level, index, message, progname, &block)
+          true
+        else
+          false
+        end
+      end
+
+    end
+  end
+end

data/lib/sapience/configuration.rb

@@ -0,0 +1,86 @@
+require "ostruct"
+
+module Sapience
+  class Configuration
+    attr_reader :default_level, :backtrace_level, :backtrace_level_index
+    attr_writer :host
+    attr_accessor :application, :ap_options, :appenders
+
+    def initialize
+      # Initial default Level for all new instances of Sapience::Logger
+      self.default_level   = :info
+      self.backtrace_level = :info
+      self.application     = "Sapience"
+      self.host            = nil
+      self.ap_options      = { multiline: false }
+      self.appenders       = [ { file: {io: STDOUT, formatter: :color } } ]
+    end
+
+    # Sets the global default log level
+    def default_level=(level)
+      @default_level       = level
+      # For performance reasons pre-calculate the level index
+      @default_level_index = level_to_index(level)
+    end
+
+    # Returns the symbolic level for the supplied level index
+    def index_to_level(level_index)
+      LEVELS[level_index]
+    end
+
+    # Internal method to return the log level as an internal index
+    # Also supports mapping the ::Logger levels to Sapience levels
+    def level_to_index(level) # rubocop:disable AbcSize, PerceivedComplexity, CyclomaticComplexity
+      return if level.nil?
+
+      index =
+        if level.is_a?(Symbol)
+          LEVELS.index(level)
+        elsif level.is_a?(String)
+          level = level.downcase.to_sym
+          LEVELS.index(level)
+        elsif level.is_a?(Integer) && defined?(::Logger::Severity)
+          # Mapping of Rails and Ruby Logger levels to Sapience levels
+          @@map_levels ||= begin
+            levels = []
+            ::Logger::Severity.constants.each do |constant|
+              levels[::Logger::Severity.const_get(constant)] = LEVELS.find_index(constant.downcase.to_sym) || LEVELS.find_index(:error)
+            end
+            levels
+          end
+          @@map_levels[level]
+        end
+      fail "Invalid level:#{level.inspect} being requested. Must be one of #{LEVELS.inspect}" unless index
+      index
+    end
+
+    def default_level_index
+      Thread.current[:sapience_silence] || @default_level_index
+    end
+
+
+    # Sets the level at which backtraces should be captured
+    # for every log message.
+    #
+    # By enabling backtrace capture the filename and line number of where
+    # message was logged can be written to the log file. Additionally, the backtrace
+    # can be forwarded to error management services such as Bugsnag.
+    #
+    # Warning:
+    #   Capturing backtraces is very expensive and should not be done all
+    #   the time. It is recommended to run it at :error level in production.
+    def backtrace_level=(level)
+      @backtrace_level       = level
+      # For performance reasons pre-calculate the level index
+      @backtrace_level_index = level.nil? ? 65_535 : level_to_index(level)
+    end
+
+    # Returns [String] name of this host for logging purposes
+    # Note: Not all appenders use `host`
+    def host
+      @host ||= Socket.gethostname
+    end
+
+
+  end
+end

data/lib/sapience/core_ext/thread.rb

@@ -0,0 +1,14 @@
+require "thread"
+class Thread
+  # Returns the name of the current thread
+  # Default:
+  #    String representation of this thread's object_id
+  def name
+    @name ||= object_id.to_s
+  end unless defined?(:name)
+
+  # Set the name of this thread
+  def name=(name)
+    @name = name.to_s
+  end unless defined?(:name=)
+end

data/lib/sapience/formatters/base.rb

@@ -0,0 +1,36 @@
+module Sapience
+  module Formatters
+    class Base
+      attr_accessor :time_format, :precision, :log_host, :log_application
+
+      # Parameters
+      #   time_format: [String|Symbol|nil]
+      #     See Time#strftime for the format of this string
+      #     :iso_8601 Outputs an ISO8601 Formatted timestamp
+      #     nil:      Returns Empty string for time ( no time is output ).
+      #     Default: '%Y-%m-%d %H:%M:%S.%6N'
+      def initialize(options = {})
+        options          = options.dup
+        @precision       = 6
+        default_format   = "%Y-%m-%d %H:%M:%S.%#{precision}N"
+        @time_format     = options.key?(:time_format) ? options.delete(:time_format) : default_format
+        @log_host        = options.key?(:log_host) ? options.delete(:log_host) : true
+        @log_application = options.key?(:log_application) ? options.delete(:log_application) : true
+        fail(ArgumentError, "Unknown options: #{options.inspect}") if options.size > 0
+      end
+
+      # Return the Time as a formatted string
+      def format_time(time)
+        case time_format
+        when :iso_8601
+          time.utc.iso8601(precision)
+        when nil
+          ""
+        else
+          time.strftime(time_format)
+        end
+      end
+
+    end
+  end
+end

data/lib/sapience/formatters/color.rb

@@ -0,0 +1,68 @@
+# Load AwesomePrint if available
+begin
+  require "awesome_print"
+rescue LoadError
+end
+
+module Sapience
+  module Formatters
+    class Color < Base
+      # Parameters:
+      #   ap: Any valid AwesomePrint option for rendering data.
+      #       These options can also be changed be creating a `~/.aprc` file.
+      #       See: https://github.com/michaeldv/awesome_print
+      #
+      #       Note: The option :multiline is set to false if not supplied.
+      #       Note: Has no effect if Awesome Print is not installed.
+      def initialize(options = {})
+        options     = options.dup
+        @ai_options = options.delete(:ap) || { multiline: false }
+        super(options)
+      end
+
+      # Adds color to the default log formatter
+      # Example:
+      #   Sapience.add_appender(:file, io: $stdout, formatter: :color)
+      def call(log, _logger) # rubocop:disable AbcSize, PerceivedComplexity, CyclomaticComplexity
+        colors      = Sapience::AnsiColors
+        level_color = colors::LEVEL_MAP[log.level]
+
+        message = time_format.nil? ? "" : "#{format_time(log.time)} "
+
+        # Header with date, time, log level and process info
+        message << "#{level_color}#{log.level_to_s}#{colors::CLEAR} [#{log.process_info}]"
+
+        # Tags
+        message << " " << log.tags.collect { |tag| "[#{level_color}#{tag}#{colors::CLEAR}]" }.join(" ") if log.tags && (log.tags.size > 0)
+
+        # Duration
+        message << " (#{colors::BOLD}#{log.duration_human}#{colors::CLEAR})" if log.duration
+
+        # Class / app name
+        message << " #{level_color}#{log.name}#{colors::CLEAR}"
+
+        # Log message
+        message << " -- #{log.message}" if log.message
+
+        # Payload: Colorize the payload if the AwesomePrint gem is loaded
+        if log.payload?
+          payload = log.payload
+          message << " -- " <<
+            if defined?(AwesomePrint) && payload.respond_to?(:ai)
+              payload.ai(@ai_options) rescue payload.inspect
+            else
+              payload.inspect
+            end
+        end
+
+        # Exceptions
+        if log.exception
+          message << " -- Exception: #{colors::BOLD}#{log.exception.class}: #{log.exception.message}#{colors::CLEAR}\n"
+          message << log.backtrace_to_s
+        end
+        message
+      end
+
+    end
+  end
+end

data/lib/sapience/formatters/default.rb

@@ -0,0 +1,41 @@
+module Sapience
+  module Formatters
+    class Default < Base
+      # Default text log format
+      #  Generates logs of the form:
+      #    2011-07-19 14:36:15.660235 D [1149:ScriptThreadProcess] Rails -- Hello World
+      def call(log, _logger) # rubocop:disable AbcSize, PerceivedComplexity, CyclomaticComplexity
+        # Date & time
+        message = time_format.nil? ? "" : "#{format_time(log.time)} "
+
+        # Log level and process info
+        message << "#{log.level_to_s} [#{log.process_info}]"
+
+        # Tags
+        message << " " << log.tags.collect { |tag| "[#{tag}]" }.join(" ") if log.tags && (log.tags.size > 0)
+
+        # Duration
+        message << " (#{log.duration_human})" if log.duration
+
+        # Class / app name
+        message << " #{log.name}"
+
+        # Log message
+        message << " -- #{log.message}" if log.message
+
+        # Payload
+        if payload = log.payload_to_s
+          message << " -- " << payload
+        end
+
+        # Exceptions
+        if log.exception
+          message << " -- Exception: #{log.exception.class}: #{log.exception.message}\n"
+          message << log.backtrace_to_s
+        end
+        message
+      end
+
+    end
+  end
+end