semantic_logger 3.0.1 → 3.1.0

data/lib/semantic_logger/debug_as_trace_logger.rb

@@ -11,8 +11,12 @@ module SemanticLogger
       trace?
     end
 
+    def measure_debug(*args, &block)
+      measure_trace(*args, &block)
+    end
+
     def benchmark_debug(*args, &block)
-      benchmark_trace(*args, &block)
+      measure_trace(*args, &block)
     end
   end
-end
+end

data/lib/semantic_logger/formatters/color.rb

@@ -0,0 +1,66 @@
+# Load AwesomePrint if available
+begin
+  require 'awesome_print'
+rescue LoadError
+end
+
+module SemanticLogger
+  module Formatters
+    class Color
+      # Parameters:
+      #  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={})
+        @ai_options             = options.dup
+        @ai_options[:multiline] = false unless @ai_options.has_key?(:multiline)
+      end
+
+      # Adds color to the default log formatter
+      # Example:
+      #   SemanticLogger.add_appender(io: $stdout, formatter: :color)
+      def call(log, logger)
+        colors      = SemanticLogger::AnsiColors
+        level_color = colors::LEVEL_MAP[log.level]
+
+        # Header with date, time, log level and process info
+        message     = "#{log.formatted_time} #{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.has_payload?
+          payload = log.payload
+          message << ' -- ' <<
+            if !defined?(AwesomePrint) || !payload.respond_to?(:ai)
+              payload.inspect
+            else
+              payload.ai(@ai_options) rescue 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/semantic_logger/formatters/default.rb

@@ -0,0 +1,39 @@
+module SemanticLogger
+  module Formatters
+    class Default
+      # Default log formatter
+      #  Generates logs of the form:
+      #    2011-07-19 14:36:15.660 D [1149:ScriptThreadProcess] Rails -- Hello World
+      def call(log, logger)
+        # Header with date, time, log level and process info
+        message = "#{log.formatted_time} #{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
+

data/lib/semantic_logger/formatters/json.rb

@@ -0,0 +1,16 @@
+require 'json'
+module SemanticLogger
+  module Formatters
+    class Json
+      # Returns log messages in JSON format
+      def call(log, logger)
+        h = log.to_h
+        h.delete(:time)
+        h[:timestamp] = log.time.utc.iso8601(defined?(JRuby) ? 3 : 6)
+        h.to_json
+      end
+
+    end
+  end
+end
+

data/lib/semantic_logger/jruby/garbage_collection_logger.rb

@@ -18,7 +18,7 @@ module SemanticLogger
         gc_info  = info.gc_info
         duration = gc_info.duration
         if duration >= @min_microseconds
-          SemanticLogger['GarbageCollector'].benchmark_warn "Garbage Collection completed: #{info.gc_name} ##{gc_info.id}", duration: duration.to_f / 1000
+          SemanticLogger['GarbageCollector'].measure_warn "Garbage Collection completed: #{info.gc_name} ##{gc_info.id}", duration: duration.to_f / 1000
         end
       end
     end

data/lib/semantic_logger/log.rb

@@ -23,7 +23,7 @@ module SemanticLogger
   #   The time at which the log entry was created
   #
   # duration
-  #   The time taken to complete a benchmark call
+  #   The time taken to complete a measure call
   #
   # tags
   #   Any tags active on the thread when the log call was made
@@ -35,11 +35,15 @@ module SemanticLogger
   #   Ruby Exception object to log
   #
   # metric [Object]
-  #   Object supplied when benchmark_x was called
+  #   Object supplied when measure_x was called
   #
   # backtrace [Array<String>]
   #   The backtrace captured at source when the log level >= SemanticLogger.backtrace_level
-  Log = Struct.new(:level, :thread_name, :name, :message, :payload, :time, :duration, :tags, :level_index, :exception, :metric, :backtrace) do
+  #
+  # metric_amount [Numeric]
+  #   Used for numeric or counter metrics.
+  #   For example, the number of inquiries or, the amount purchased etc.
+  Log = Struct.new(:level, :thread_name, :name, :message, :payload, :time, :duration, :tags, :level_index, :exception, :metric, :backtrace, :metric_amount) do
 
     MAX_EXCEPTIONS_TO_UNWRAP = 5
     # Call the block for exception and any nested exception
@@ -147,12 +151,13 @@ module SemanticLogger
 
     # Return the payload in text form
     # Returns nil if payload is missing or empty
-    def payload_to_s(colorized = false)
-      return if payload.nil? || (payload.respond_to?(:empty?) && payload.empty?)
-      return payload.inspect if !colorized || !defined?(AwesomePrint) || !payload.respond_to?(:ai)
+    def payload_to_s
+      payload.inspect if has_payload?
+    end
 
-      # Colorize the payload if the AwesomePrint gem is loaded
-      payload.ai(multiline: false) rescue payload.inspect
+    # Returns [true|false] whether the log entry has a payload
+    def has_payload?
+      !(payload.nil? || (payload.respond_to?(:empty?) && payload.empty?))
     end
 
     if defined? JRuby

data/lib/semantic_logger/loggable.rb

@@ -9,7 +9,7 @@
 #
 #  require 'semantic_logger'
 #  SemanticLogger.default_level = :debug
-#  SemanticLogger.add_appender(STDOUT)
+#  SemanticLogger.add_appender(io: STDOUT, formatter: :color)
 #
 #  class ExternalSupplier
 #    # Create class and instance logger methods
@@ -19,7 +19,7 @@
 #      logger.debug "Calculating with amount", { amount: amount, name: name }
 #
 #      # Measure and log on completion how long the call took to the external supplier
-#      logger.benchmark_info "Calling external interface" do
+#      logger.measure_info "Calling external interface" do
 #        # Code to call the external supplier ...
 #      end
 #    end

data/lib/semantic_logger/logger.rb

@@ -3,6 +3,8 @@ module SemanticLogger
   # Logger stores the class name to be used for all log messages so that every
   # log message written by this instance will include the class name
   class Logger < Base
+    include SemanticLogger::Concerns::Compatibility
+
     # Returns a Logger instance
     #
     # Return the logger for a specific class, supports class specific log levels
@@ -95,18 +97,27 @@ module SemanticLogger
       queue_size
     end
 
-    # Supply a block to be called whenever a metric is seen during benchmark logging
+    # Supply a block to be called whenever a metric is seen during measure logging
     #
     #  Parameters
     #    block
     #      The block to be called
     #
     # Example:
-    #   SemanticLogger.on_metric do |log_struct|
-    #     puts "#{log_struct.metric} was received. Log Struct: #{log_struct.inspect}"
+    #   SemanticLogger.on_metric do |log|
+    #     puts "#{log.metric} was received. Log Struct: #{log.inspect}"
     #   end
-    def self.on_metric(&block)
-      (@@metric_subscribers ||= Concurrent::Array.new) << block
+    def self.on_metric(object = nil, &block)
+      raise('When supplying an object, it must support the #call method') if object && !object.respond_to?(:call)
+      (@@metric_subscribers ||= Concurrent::Array.new) << (object || block)
+    end
+
+    # Place log request on the queue for the Appender thread to write to each
+    # appender in the order that they were registered
+    def log(log, message = nil, progname = nil, &block)
+      # Compatibility with ::Logger
+      return add(log, message, progname, &block) unless log.is_a?(SemanticLogger::Log)
+      self.class.queue << log if @@appender_thread
     end
 
     private
@@ -120,12 +131,6 @@ module SemanticLogger
       @@queue
     end
 
-    # Place log request on the queue for the Appender thread to write to each
-    # appender in the order that they were registered
-    def log(log)
-      self.class.queue << log if @@appender_thread
-    end
-
     # Internal logger for SemanticLogger
     #   For example when an appender is not working etc..
     #   By default logs to STDERR
@@ -219,13 +224,13 @@ module SemanticLogger
     end
 
     # Call Metric subscribers
-    def self.call_metric_subscribers(log_struct)
+    def self.call_metric_subscribers(log)
       # If no subscribers registered, then return immediately
       return unless @@metric_subscribers
 
       @@metric_subscribers.each do |subscriber|
         begin
-          subscriber.call(log_struct)
+          subscriber.call(log)
         rescue Exception => exc
           logger.error 'Exception calling metrics subscriber', exc
         end

data/lib/semantic_logger/metrics/new_relic.rb

@@ -0,0 +1,18 @@
+module SemanticLogger
+  module Metrics
+    class NewRelic
+      def call(log)
+        metric = log.metric
+        # Add 'Custom/' prefix for NewRelic
+        metric = "Custom/#{metric}" unless metric.start_with?('Custom')
+
+        if duration = log.duration
+          # Convert duration to seconds
+          ::NewRelic::Agent.record_metric(metric, duration / 1000.0)
+        else
+          ::NewRelic::Agent.increment_metric(metric, log.metric_amount || 1)
+        end
+      end
+    end
+  end
+end

data/lib/semantic_logger/metrics/statsd.rb

@@ -0,0 +1,48 @@
+require 'uri'
+begin
+  require 'statsd-ruby'
+rescue LoadError
+  raise 'Gem statsd-ruby is required for logging metrics. Please add the gem "statsd-ruby" to your Gemfile.'
+end
+
+module SemanticLogger
+  module Metrics
+    class Statsd
+      # Create Statsd metrics subscriber
+      #
+      # Parameters:
+      #   url: [String]
+      #     Valid URL to post to.
+      #     Example:
+      #       udp://localhost:8125
+      #     Example, send all metrics to a particular namespace:
+      #       udp://localhost:8125/namespace
+      #     Default: udp://localhost:8125
+      def initialize(options = {})
+        options = options.dup
+        @url    = options.delete(:url) || 'udp://localhost:8125'
+        uri     = URI.parse(@url)
+        raise('Statsd only supports udp. Example: "udp://localhost:8125"') if uri.scheme != 'udp'
+
+        @statsd           = ::Statsd.new(uri.host, uri.port)
+        path              = uri.path.chomp('/')
+        @statsd.namespace = path.sub('/', '') if path != ''
+      end
+
+      def call(log)
+        metric = log.metric
+        if duration = log.duration
+          $statsd.timing(metric, duration)
+        else
+          amount = (log.metric_amount || 1).round
+          if amount < 0
+            amount.times { $statsd.decrement(metric) }
+          else
+            amount.times { $statsd.increment(metric) }
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/semantic_logger/semantic_logger.rb

@@ -81,40 +81,59 @@ module SemanticLogger
   # more information on custom formatters
   #
   # Parameters
-  #   appender [String|IO|SemanticLogger::Appender::Base|::Logger]
-  #     Filename to write log messages to
-  #        Or,
-  #     STDOUT, STDERR, or any IO stream to write log messages to
-  #        Or,
-  #     Any SemanticLogger::Appender instance such as
-  #       SemanticLogger::Appender::File
-  #       SemanticLogger::Appender::Wrapper
-  #       SemanticLogger::Appender::Mongodb
-  #        Or,
-  #     A custom appender derived from SemanticLogger::Appender::Base
-  #        Or,
-  #     Ruby built-in Logger, or any logger that implements the following methods:
-  #       :debug, :info, :warn, :error, :fatal
-  #
-  #   level [Symbol]
-  #     Optional
-  #     By setting the level higher than the SemanticLogger::default_level
-  #     this appender can exclude lower level log messages
-  #     Any one of SemanticLogger::LEVELS. For example: :trace, :debug, :info, :warn, :error, :fatal
+  #   file_name: [String]
+  #     File name to write log messages to.
+  #
+  #   Or,
+  #   io: [IO]
+  #     An IO Stream to log to.
+  #     For example STDOUT, STDERR, etc.
+  #
+  #   Or,
+  #   appender: [Symbol|SemanticLogger::Appender::Base]
+  #     A symbol identifying the appender to create.
+  #     For example:
+  #       :bugsnag, :elasticsearch, :graylog, :http, :mongodb, :new_relic, :splunk_http, :syslog, :wrapper
+  #          Or,
+  #     An instance of an appender derived from SemanticLogger::Appender::Base
+  #     For example:
+  #       SemanticLogger::Appender::Http.new(url: 'http://localhost:8088/path')
+  #
+  #   Or,
+  #   logger: [Logger|Log4r]
+  #     An instance of a Logger or a Log4r logger.
+  #
+  #   level: [:trace | :debug | :info | :warn | :error | :fatal]
+  #     Override the log level for this appender.
+  #     Default: SemanticLogger.default_level
+  #
+  #   formatter: [Symbol|Object|Proc]
+  #     Any of the following symbol values: :default, :color, :json
+  #       Or,
+  #     An instance of a class that implements #call
+  #       Or,
+  #     A Proc to be used to format the output from this appender
+  #     Default: :default
+  #
+  #   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.
   #
   # Examples:
   #
   #   # Send all logging output to Standard Out (Screen)
-  #   SemanticLogger.add_appender(STDOUT)
+  #   SemanticLogger.add_appender(io: STDOUT)
   #
   #   # Send all logging output to a file
-  #   SemanticLogger.add_appender('logfile.log')
+  #   SemanticLogger.add_appender(file_name: 'logfile.log')
   #
   #   # Send all logging output to a file and only :info and above to standard output
-  #   SemanticLogger.add_appender('logfile.log')
-  #   SemanticLogger.add_appender(STDOUT, :info)
+  #   SemanticLogger.add_appender(file_name: 'logfile.log')
+  #   SemanticLogger.add_appender(io: STDOUT, level: :info)
   #
-  # Log to an existing logger:
+  # Log to log4r, Logger, etc.:
   #
   #   # Send Semantic logging output to an existing logger
   #   require 'logger'
@@ -125,37 +144,19 @@ module SemanticLogger
   #   log.level = Logger::DEBUG
   #
   #   SemanticLogger.default_level = :debug
-  #   SemanticLogger.add_appender(log)
+  #   SemanticLogger.add_appender(logger: log)
   #
   #   logger = SemanticLogger['Example']
   #   logger.info "Hello World"
   #   logger.debug("Login time", user: 'Joe', duration: 100, ip_address: '127.0.0.1')
-  #
-  def self.add_appender(appender, level=nil, &block)
-    appender_instance =
-      if appender.is_a?(String) || appender.is_a?(IO)
-        # $stderr, STDOUT, other IO, or a filename
-        SemanticLogger::Appender::File.new(appender, level, &block)
-      elsif appender.is_a? Appender::Base
-        # Already an instance of an appender
-        appender.level     = level if level
-        appender.formatter = block if block
-        appender
-      else
-        # Check if the custom appender responds to all the log levels. For example Ruby ::Logger
-        if does_not_implement = LEVELS[1..-1].find { |i| !appender.respond_to?(i) }
-          raise "Supplied appender does not implement:#{does_not_implement}. It must implement all of #{LEVELS[1..-1].inspect}"
-        end
-
-        raise "Change the log level to #{level}, update the log level directly against the supplied appender" if level
-        SemanticLogger::Appender::Wrapper.new(appender, &block)
-      end
-    @@appenders << appender_instance
+  def self.add_appender(options, deprecated_level = nil, &block)
+    options  = options.is_a?(Hash) ? options.dup : convert_old_appender_args(options, deprecated_level)
+    appender = appender_from_options(options, &block)
+    @@appenders << appender
 
     # Start appender thread if it is not already running
     SemanticLogger::Logger.start_appender_thread
-
-    appender_instance
+    appender
   end
 
   # Remove an existing appender
@@ -188,18 +189,18 @@ module SemanticLogger
     SemanticLogger::Logger.start_appender_thread
   end
 
-  # Supply a block to be called whenever a metric is seen during benchmark logging
+  # Supply a block to be called whenever a metric is seen during measure logging
   #
   #  Parameters
   #    block
   #      The block to be called
   #
   # Example:
-  #   SemanticLogger.on_metric do |log_struct|
-  #     puts "#{log_struct.metric} was received. Log Struct: #{log_struct.inspect}"
+  #   SemanticLogger.on_metric do |log|
+  #     puts "#{log.metric} was received. Log Struct: #{log.inspect}"
   #   end
-  def self.on_metric(&block)
-    SemanticLogger::Logger.on_metric(&block)
+  def self.on_metric(object = nil, &block)
+    SemanticLogger::Logger.on_metric(object, &block)
   end
 
   # Add signal handlers for Semantic Logger
@@ -279,7 +280,7 @@ module SemanticLogger
   end
 
   # Returns the symbolic level for the supplied level index
-  def index_to_level(level_index)
+  def self.index_to_level(level_index)
     LEVELS[level_index]
   end
 
@@ -309,6 +310,72 @@ module SemanticLogger
     index
   end
 
+  # Backward compatibility
+  def self.convert_old_appender_args(appender, level)
+    options         = {}
+    options[:level] = level if level
+
+    if appender.is_a?(String)
+      options[:file_name] = appender
+    elsif appender.is_a?(IO)
+      options[:io] = appender
+    elsif appender.is_a?(Symbol) || appender.is_a?(Appender::Base)
+      options[:appender] = appender
+    else
+      options[:logger] = appender
+    end
+    warn "[DEPRECATED] SemanticLogger.add_appender parameters have changed. Please use: #{options.inspect}"
+    options
+  end
+
+  # Returns [SemanticLogger::Appender::Base] appender for the supplied options
+  def self.appender_from_options(options, &block)
+    if options[:io] || options[:file_name]
+      SemanticLogger::Appender::File.new(options, &block)
+    elsif appender = options.delete(:appender)
+      if appender.is_a?(Symbol)
+        named_appender(appender).new(options)
+      elsif appender.is_a?(Appender::Base)
+        appender
+      else
+        raise(ArgumentError, "Parameter :appender must be either a Symbol or an object derived from SemanticLogger::Appender::Base, not: #{appender.inspect}")
+      end
+    elsif options[:logger]
+      SemanticLogger::Appender::Wrapper.new(options, &block)
+    end
+  end
+
+  def self.named_appender(appender)
+    appender = appender.to_s
+    klass    = appender.respond_to?(:camelize) ? appender.camelize : camelize(appender)
+    klass    = "SemanticLogger::Appender::#{klass}"
+    begin
+      appender.respond_to?(:constantize) ? klass.constantize : eval(klass)
+    rescue NameError
+      raise(ArgumentError, "Could not find appender class: #{klass} for #{appender}")
+    end
+  end
+
+  def self.named_formatter(formatter)
+    formatter = formatter.to_s
+    klass     = formatter.respond_to?(:camelize) ? formatter.camelize : camelize(formatter)
+    klass     = "SemanticLogger::Formatters::#{klass}"
+    begin
+      formatter.respond_to?(:constantize) ? klass.constantize : eval(klass)
+    rescue NameError => exc
+      raise(ArgumentError, "Could not find formatter class: #{klass} for #{appender}")
+    end
+  end
+
+  # Borrow from Rails, when not running Rails
+  def self.camelize(term)
+    string = term.to_s
+    string = string.sub(/^[a-z\d]*/) { |match| match.capitalize }
+    string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{inflections.acronyms[$2] || $2.capitalize}" }
+    string.gsub!('/'.freeze, '::'.freeze)
+    string
+  end
+
   # Initial default Level for all new instances of SemanticLogger::Logger
   @@default_level         = :info
   @@default_level_index   = level_to_index(@@default_level)