semantic_logger 4.0.0 → 4.1.0

data/lib/semantic_logger/processor.rb

@@ -4,24 +4,43 @@ module SemanticLogger
     # Start the appender thread
     def self.start
       return false if active?
-      @@thread = Thread.new { process_requests }
-      raise 'Failed to start Appender Thread' unless @@thread
+      @thread = Thread.new { process_requests }
+      raise 'Failed to start Appender Thread' unless @thread
       true
     end
 
     # Returns true if the appender_thread is active
     def self.active?
-      @@thread && @@thread.alive?
+      @thread && @thread.alive?
     end
 
-    # Returns [Integer] the number of log entries waiting to be written to the appenders
+    # Returns [Integer] the number of log entries waiting to be written to the appenders.
+    #
+    # When this number grows it is because the logging appender thread is not
+    # able to write to the appenders fast enough. Either reduce the amount of
+    # logging, increase the log level, reduce the number of appenders, or
+    # look into speeding up the appenders themselves
     def self.queue_size
       queue.size
     end
 
-    # Add log request to the queue for processing
+    # Flush all queued log entries disk, database, etc.
+    #  All queued log messages are written and then each appender is flushed in turn.
+    def self.flush
+      submit_request(:flush)
+    end
+
+    # Close all appenders and flush any outstanding messages.
+    def self.close
+      submit_request(:close)
+    end
+
+    # Add log request to the queue for processing.
     def self.<<(log)
-      queue << log if active?
+      return unless active?
+
+      call_log_subscribers(log)
+      queue << log
     end
 
     # Submit command and wait for reply
@@ -47,78 +66,68 @@ module SemanticLogger
     #   SemanticLogger::Logger itself since it is for reporting problems
     #   while trying to log to the various appenders
     def self.logger=(logger)
-      @@logger = logger
+      @logger = logger
     end
 
     # Returns the check_interval which is the number of messages between checks
     # to determine if the appender thread is falling behind
     def self.lag_check_interval
-      @@lag_check_interval
+      @lag_check_interval
     end
 
     # Set the check_interval which is the number of messages between checks
     # to determine if the appender thread is falling behind
     def self.lag_check_interval=(lag_check_interval)
-      @@lag_check_interval = lag_check_interval
+      @lag_check_interval = lag_check_interval
     end
 
     # Returns the amount of time in seconds
     # to determine if the appender thread is falling behind
     def self.lag_threshold_s
-      @@lag_threshold_s
+      @lag_threshold_s
     end
 
-    # Supply a metrics appender to be called whenever a logging metric is encountered
-    #
-    #  Parameters
-    #    appender: [Symbol | Object | Proc]
-    #      [Proc] the block to call.
-    #      [Object] the block on which to call #call.
-    #      [Symbol] :new_relic, or :statsd to forward metrics to
-    #
-    #    block
-    #      The block to be called
-    #
-    # Example:
-    #   SemanticLogger.on_metric do |log|
-    #     puts "#{log.metric} was received. Log: #{log.inspect}"
-    #   end
-    #
-    # Note:
-    # * This callback is called in the logging thread.
-    # * Does not slow down the application.
-    # * Only context is what is passed in the log struct, the original thread context is not available.
     def self.on_metric(options = {}, &block)
       # Backward compatibility
-      options  = options.is_a?(Hash) ? options.dup : {appender: options}
-      appender = block || options.delete(:appender)
+      options    = options.is_a?(Hash) ? options.dup : {appender: options}
+      subscriber = block || options.delete(:appender)
 
       # Convert symbolized metrics appender to an actual object
-      appender = SemanticLogger::Appender.constantize_symbol(appender, 'SemanticLogger::Metrics').new(options) if appender.is_a?(Symbol)
+      subscriber = SemanticLogger::Appender.constantize_symbol(subscriber, 'SemanticLogger::Metrics').new(options) if subscriber.is_a?(Symbol)
+
+      raise('When supplying a metrics subscriber, it must support the #call method') unless subscriber.is_a?(Proc) || subscriber.respond_to?(:call)
+      subscribers = (@metric_subscribers ||= Concurrent::Array.new)
+      subscribers << subscriber unless subscribers.include?(subscriber)
+    end
+
+    def self.on_log(object = nil, &block)
+      subscriber = block || object
 
-      raise('When supplying a metrics appender, it must support the #call method') unless appender.is_a?(Proc) || appender.respond_to?(:call)
-      (@@metric_subscribers ||= Concurrent::Array.new) << appender
+      raise('When supplying an on_log subscriber, it must support the #call method') unless subscriber.is_a?(Proc) || subscriber.respond_to?(:call)
+      subscribers = (@log_subscribers ||= Concurrent::Array.new)
+      subscribers << subscriber unless subscribers.include?(subscriber)
     end
 
     private
 
-    @@thread             = nil
-    @@queue              = Queue.new
-    @@lag_check_interval = 5000
-    @@lag_threshold_s    = 30
-    @@metric_subscribers = nil
+    @thread             = nil
+    @queue              = Queue.new
+    @lag_check_interval = 5000
+    @lag_threshold_s    = 30
+    @metric_subscribers = nil
+    @log_subscribers    = nil
 
     # Queue to hold messages that need to be logged to the various appenders
     def self.queue
-      @@queue
+      @queue
     end
 
     # Internal logger for SemanticLogger
     #   For example when an appender is not working etc..
     #   By default logs to STDERR
     def self.logger
-      @@logger ||= begin
-        l      = SemanticLogger::Appender::File.new(STDERR, :warn)
+      @logger ||= begin
+        l      = SemanticLogger::Appender::File.new(io: STDERR, level: :warn)
         l.name = name
         l
       end
@@ -156,6 +165,7 @@ module SemanticLogger
             when :close
               close_appenders
               message[:reply_queue] << true if message[:reply_queue]
+              break
             else
               logger.warn "Appender thread: Ignoring unknown command: #{message[:command]}"
             end
@@ -170,7 +180,7 @@ module SemanticLogger
         end
         retry
       ensure
-        @@thread = nil
+        @thread = nil
         # This block may be called after the file handles have been released by Ruby
         begin
           logger.trace 'Appender thread has stopped'
@@ -183,9 +193,9 @@ module SemanticLogger
     # Call Metric subscribers
     def self.call_metric_subscribers(log)
       # If no subscribers registered, then return immediately
-      return unless @@metric_subscribers
+      return unless @metric_subscribers
 
-      @@metric_subscribers.each do |subscriber|
+      @metric_subscribers.each do |subscriber|
         begin
           subscriber.call(log)
         rescue Exception => exc
@@ -194,6 +204,20 @@ module SemanticLogger
       end
     end
 
+    # Call on_log subscribers
+    def self.call_log_subscribers(log)
+      # If no subscribers registered, then return immediately
+      return unless @log_subscribers
+
+      @log_subscribers.each do |subscriber|
+        begin
+          subscriber.call(log)
+        rescue Exception => exc
+          logger.error 'Exception calling :on_log subscriber', exc
+        end
+      end
+    end
+
     # Call Appenders
     def self.call_appenders(log)
       SemanticLogger.appenders.each do |appender|

data/lib/semantic_logger/semantic_logger.rb

@@ -12,14 +12,14 @@ module SemanticLogger
 
   # Sets the global default log level
   def self.default_level=(level)
-    @@default_level       = level
+    @default_level       = level
     # For performance reasons pre-calculate the level index
-    @@default_level_index = level_to_index(level)
+    @default_level_index = level_to_index(level)
   end
 
   # Returns the global default log level
   def self.default_level
-    @@default_level
+    @default_level
   end
 
   # Sets the level at which backtraces should be captured
@@ -33,45 +33,45 @@ module SemanticLogger
   #   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 self.backtrace_level=(level)
-    @@backtrace_level       = level
+    @backtrace_level       = level
     # For performance reasons pre-calculate the level index
-    @@backtrace_level_index = level.nil? ? 65535 : level_to_index(level)
+    @backtrace_level_index = level.nil? ? 65535 : level_to_index(level)
   end
 
   # Returns the current backtrace level
   def self.backtrace_level
-    @@backtrace_level
+    @backtrace_level
   end
 
   # Returns the current backtrace level index
   # For internal use only
   def self.backtrace_level_index #:nodoc
-    @@backtrace_level_index
+    @backtrace_level_index
   end
 
   # Returns [String] name of this host for logging purposes
   # Note: Not all appenders use `host`
   def self.host
-    @@host ||= Socket.gethostname.force_encoding("UTF-8")
+    @host ||= Socket.gethostname.force_encoding("UTF-8")
   end
 
   # Override the default host name
   def self.host=(host)
-    @@host = host
+    @host = host
   end
 
   # Returns [String] name of this application for logging purposes
   # Note: Not all appenders use `application`
   def self.application
-    @@application
+    @application
   end
 
   # Override the default application
   def self.application=(application)
-    @@application = application
+    @application = application
   end
 
-  @@application = 'Semantic Logger'
+  @application = 'Semantic Logger'
 
   # Add a new logging appender as a new destination for all log messages
   # emitted from Semantic Logger
@@ -154,7 +154,7 @@ module SemanticLogger
   def self.add_appender(options, deprecated_level = nil, &block)
     options  = options.is_a?(Hash) ? options.dup : convert_old_appender_args(options, deprecated_level)
     appender = SemanticLogger::Appender.create(options, &block)
-    @@appenders << appender
+    @appenders << appender
 
     # Start appender thread if it is not already running
     SemanticLogger::Processor.start
@@ -164,7 +164,7 @@ module SemanticLogger
   # Remove an existing appender
   # Currently only supports appender instances
   def self.remove_appender(appender)
-    @@appenders.delete(appender)
+    @appenders.delete(appender)
   end
 
   # Returns [SemanticLogger::Subscriber] a copy of the list of active
@@ -172,31 +172,33 @@ module SemanticLogger
   # Use SemanticLogger.add_appender and SemanticLogger.remove_appender
   # to manipulate the active appenders list
   def self.appenders
-    @@appenders.clone
+    @appenders.clone
   end
 
-  # Wait until all queued log messages have been written and flush all active
-  # appenders
+  # Flush all queued log entries disk, database, etc.
+  #  All queued log messages are written and then each appender is flushed in turn.
   def self.flush
-    SemanticLogger::Logger.flush
+    SemanticLogger::Processor.flush
   end
 
-  # Close and flush all appenders
+  # Close all appenders and flush any outstanding messages.
   def self.close
-    SemanticLogger::Logger.close
+    SemanticLogger::Processor.close
   end
 
   # After forking an active process call SemanticLogger.reopen to re-open
-  # any open file handles etc to resources
+  # any open file handles etc to resources.
   #
-  # Note: Only appenders that implement the reopen method will be called
+  # Note:
+  #   Not all appenders implement reopen.
+  #   Check the code for each appender you are using before relying on this behavior.
   def self.reopen
-    @@appenders.each { |appender| appender.reopen if appender.respond_to?(:reopen) }
-    # After a fork the appender thread is not running, start it if it is not running
+    @appenders.each {|appender| appender.reopen if appender.respond_to?(:reopen)}
+    # After a fork the appender thread is not running, start it if it is not running.
     SemanticLogger::Processor.start
   end
 
-  # Supply a block to be called whenever a metric is seen during measure logging
+  # Supply a metrics appender to be called whenever a logging metric is encountered
   #
   #  Parameters
   #    appender: [Symbol | Object | Proc]
@@ -213,13 +215,41 @@ module SemanticLogger
   #   end
   #
   # Note:
-  # * This callback is called in the logging thread.
+  # * This callback is called in the separate logging thread.
   # * Does not slow down the application.
   # * Only context is what is passed in the log struct, the original thread context is not available.
   def self.on_metric(options = {}, &block)
     SemanticLogger::Processor.on_metric(options, &block)
   end
 
+  # Supply a callback to be called whenever a log entry is created.
+  # Useful for capturing appender specific context information.
+  #
+  #  Parameters
+  #    object: [Object | Proc]
+  #      [Proc] the block to call.
+  #      [Object] any object on which to call #call.
+  #
+  # Example:
+  #   SemanticLogger.on_log do |log|
+  #     log.set_context(:honeybadger, Honeybadger.get_context)
+  #   end
+  #
+  # Example:
+  #   module CaptureContext
+  #     def call(log)
+  #       log.set_context(:honeybadger, Honeybadger.get_context)
+  #     end
+  #   end
+  #   SemanticLogger.on_log(CaptureContext)
+  #
+  # Note:
+  # * This callback is called within the thread of the application making the logging call.
+  # * If these callbacks are slow they will slow down the application.
+  def self.on_log(object = nil, &block)
+    Processor.on_log(object, &block)
+  end
+
   # Add signal handlers for Semantic Logger
   #
   # Two signal handlers will be registered by default:
@@ -285,20 +315,52 @@ module SemanticLogger
   # If the tag being supplied is definitely a string then this fast
   # tag api can be used for short lived tags
   def self.fast_tag(tag)
-    (Thread.current[:semantic_logger_tags] ||= []) << tag
-    yield
-  ensure
-    Thread.current[:semantic_logger_tags].pop
+    return yield if tag.nil? || tag == ''
+
+    t = Thread.current[:semantic_logger_tags] ||= []
+    begin
+      t << tag
+      yield
+    ensure
+      t.pop
+    end
   end
 
-  # Add the supplied tags to the list of tags to log for this thread whilst
-  # the supplied block is active.
-  # Returns result of block
-  def self.tagged(*tags)
-    new_tags = push_tags(*tags)
-    yield self
-  ensure
-    pop_tags(new_tags.size)
+  # Add the tags or named tags to the list of tags to log for this thread whilst the supplied block is active.
+  #
+  # Returns result of block.
+  #
+  # Tagged example:
+  #   SemanticLogger.tagged(12345, 'jack') do
+  #     logger.debug('Hello World')
+  #   end
+  #
+  # Named Tags (Hash) example:
+  #   SemanticLogger.tagged(tracking_number: 12345) do
+  #     logger.debug('Hello World')
+  #   end
+  #
+  # Notes:
+  # - Tags should be a list without any empty values, or contain any array.
+  #   - `logger.tagged` is a slower api that will flatten the example below:
+  #     `logger.tagged([['first', nil], nil, ['more'], 'other'])`
+  #   to the equivalent of:
+  #     `logger.tagged('first', 'more', 'other')`
+  def self.tagged(*tags, &block)
+    return yield if tags.empty?
+
+    # Allow named tags to be passed into the logger
+    if tags.size == 1
+      tag = tags[0]
+      return tag.is_a?(Hash) ? named_tagged(tag, &block) : fast_tag(tag, &block)
+    end
+
+    begin
+      push_tags(*tags)
+      yield
+    ensure
+      pop_tags(tags.size)
+    end
   end
 
   # Returns a copy of the [Array] of [String] tags currently active for this thread
@@ -310,13 +372,15 @@ module SemanticLogger
   end
 
   # Add tags to the current scope
-  # Returns the list of tags pushed after flattening them out and removing blanks
+  #
+  # Note:
+  # - This method does not flatten the array or remove any empty elements, or duplicates
+  #   since the performance penalty is excessive.
+  # - To get the flattening behavior use the slower api:
+  #     `logger.push_tags`
   def self.push_tags(*tags)
-    # Need to flatten and reject empties to support calls from Rails 4
-    new_tags                              = tags.flatten.collect(&:to_s).reject(&:empty?)
-    t                                     = Thread.current[:semantic_logger_tags]
-    Thread.current[:semantic_logger_tags] = t.nil? ? new_tags : t.concat(new_tags)
-    new_tags
+    (Thread.current[:semantic_logger_tags] ||= []).concat(tags)
+    tags
   end
 
   # Remove specified number of tags from the current tag list
@@ -325,33 +389,30 @@ module SemanticLogger
     t.pop(quantity) unless t.nil?
   end
 
-  # Add the supplied named tags to the list of tags to log for this thread whilst
-  # the supplied block is active.
-  #
-  # Add a payload to all log calls on This Thread within the supplied block
-  #
-  #   SemanticLogger.named_tagged(tracking_number: 12345) do
-  #     logger.debug('Hello World')
-  #   end
-  #
-  # Returns result of block
+  # :nodoc
   def self.named_tagged(hash)
+    return yield if hash.nil? || hash.empty?
     raise(ArgumentError, '#named_tagged only accepts named parameters (Hash)') unless hash.is_a?(Hash)
-    (Thread.current[:semantic_logger_named_tags] ||= []) << hash
-    yield
-  ensure
-    Thread.current[:semantic_logger_named_tags].pop
+
+    t = Thread.current[:semantic_logger_named_tags] ||= []
+    begin
+      t << hash
+      yield
+    ensure
+      t.pop
+    end
   end
 
-  # Returns a copy of the [Hash] of named tags currently active for this thread
-  # Returns nil if no named tags are set
+  # Returns [Hash] a copy of the named tags currently active for this thread.
   def self.named_tags
     if (list = Thread.current[:semantic_logger_named_tags]) && !list.empty?
       if list.size > 1
-        list.inject({}) { |h, sum| sum.merge(h) }
+        list.reduce({}) {|sum, h| sum.merge(h)}
       else
         list.first.clone
       end
+    else
+      {}
     end
   end
 
@@ -401,10 +462,10 @@ module SemanticLogger
 
   private
 
-  @@appenders = Concurrent::Array.new
+  @appenders = Concurrent::Array.new
 
   def self.default_level_index
-    Thread.current[:semantic_logger_silence] || @@default_level_index
+    Thread.current[:semantic_logger_silence] || @default_level_index
   end
 
   # Returns the symbolic level for the supplied level index
@@ -425,14 +486,14 @@ module SemanticLogger
         LEVELS.index(level)
       elsif level.is_a?(Integer) && defined?(::Logger::Severity)
         # Mapping of Rails and Ruby Logger levels to SemanticLogger levels
-        @@map_levels ||= begin
+        @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]
+        @map_levels[level]
       end
     raise "Invalid level:#{level.inspect} being requested. Must be one of #{LEVELS.inspect}" unless index
     index
@@ -457,8 +518,8 @@ module SemanticLogger
   end
 
   # Initial default Level for all new instances of SemanticLogger::Logger
-  @@default_level         = :info
-  @@default_level_index   = level_to_index(@@default_level)
-  @@backtrace_level       = :error
-  @@backtrace_level_index = level_to_index(@@backtrace_level)
+  @default_level         = :info
+  @default_level_index   = level_to_index(@default_level)
+  @backtrace_level       = :error
+  @backtrace_level_index = level_to_index(@backtrace_level)
 end