semantic_logger 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57d9f8129cdac0b2d839354b15da27622c0726a4
-  data.tar.gz: ada6c3c38029da4532ca51f2c5a5f7234f1e1d00
+  metadata.gz: c16da0b153fc6641eb7fc40fdf7cb8ee2ffe74cd
+  data.tar.gz: 4907de6046cbbf1b7c5ea6f513faecc18bea3efb
 SHA512:
-  metadata.gz: b8af90aa234d643efa2ba2a2e26d4c41be20af8b9621d570513e4715061af5d816e005c1d2c3c740a5f5b018b48defff44c259c1d8b3214abdfdea97fa5bbe2d
-  data.tar.gz: 4bde8f95c0524a4b10b1ce800435ea796016d18a923fcdcd9d7e01b32e965c4f34c5703ce81bbab6b5208141f21a46cecb10fcf757d10cc53afac60ec9eecc9b
+  metadata.gz: b145848428794d626f5a5d3cd276c4d4929c868346962a24a502d618274c6cf967a7e6d028017c2c02b25a801b0dba014bb52a6cd29d8ef06153d5e9a9c25df7
+  data.tar.gz: bb09287501c04bb4c6db41231f8e3245a42f8b20d645d3fe63389dc875a27ba0f0187840a02756e05db346168435e755ab7f2a6f88d25340328a77115a1d06cf

data/README.md

@@ -311,20 +311,30 @@ Parameters
     :full
       Log the exception class, message, and backtrace
     :partial
-      Log the exception class and messag
+      Log the exception class and message
       The backtrace will not be logged
     :off
-      Any unhandled exception from the block will not be logged
+      Any unhandled exception raised in the block will not be logged
+    Default: :partial
 
-  :min_duration
+  :min_duration [Float]
     Only log if the block takes longer than this duration in ms
     Default: 0.0
 
-  :payload
+  :payload [Hash]
     Optional, Hash payload
 
-  :exception
+  :exception [Exception]
     Optional, Ruby Exception object to log along with the duration of the supplied block
+
+  :duration [Float]
+    Optional, supply the duration in ms that is logged when a block is not supplied
+    If a block is not supplied then :duration is mandatory
+    If a block is supplied :duration is ignored
+
+  :metric [Object]
+    Optional, when this parameter is supplied all subscribers will be notified of this
+    metric, along with the Log Struct described below
 ```
 
 ### Logging levels
@@ -488,6 +498,9 @@ Sample output:
 2013-11-07 16:26:02.744139 I [35841:User calculation thread 32] (0.0ms) ExternalSupplier -- Calling external interface
 ```
 
+When running JRuby, Thread.current.name will also set the underlying thread name in the JVM
+which is very useful when monitoring the JVM via JMX using tools such as jconsole.
+
 #### NOTE:
 
 Make sure that the assigned thread name is unique otherwise it will be difficult
@@ -499,6 +512,45 @@ For example, use the current thread object_id to ensure uniqueness:
 Thread.current.name = "Worker Thread:#{Thread.current.object_id}"
 ```
 
+### Metrics integration
+
+In production environments it is often necessary to not only measure the performance of a
+block of code using for example:
+
+```ruby
+logger.benchmark_info "Calling external interface" do
+  # Code to call the external supplier ...
+end
+```
+
+Sending the performance information gathered above to something like NewRelic
+is also very useful, and we can end up with:
+
+```ruby
+logger.benchmark_info "Calling external interface" do
+  self.class.trace_execution_scoped(['Custom/slow_action/beginning_work']) do
+    # Code to call the external supplier ...
+  end
+end
+```
+
+Rather than wrapping the code everywhere with two blocks, a single subscriber can
+be setup in config/initializers/semantic_logger_metrics.rb:
+
+```ruby
+SemanticLogger.on_metric do |log_struct|
+  ::NewRelic::Agent.record_metric(log_struct.metric, log_struct.duration)
+end
+```
+
+Then update the log entry as follows:
+
+```ruby
+logger.benchmark_info "Calling external interface", :metric => 'Custom/slow_action/beginning_work' do
+  # Code to call the external supplier ...
+end
+```
+
 ## Standalone SemanticLogger
 
 When using SemanticLogger inside of Rails all we need to do is include the
@@ -843,6 +895,11 @@ Once the logging data is in the NOSQL data store it can be queried quickly and
 efficiently. Some SQL data stores also allow complex data types that could be used
 for storing and querying the logging data
 
+Before writing SemanticLogger all of the following logging frameworks were thoroughly
+evaluated. None of them met the above Semantic requirements, or the performance requirements
+of hundreds of threads all logging at the same time:
+logback, logging, log4r, central_logger, whoops
+
 ## Architecture & Performance
 
 In order to ensure that logging does not hinder the performance of the application
@@ -931,7 +988,7 @@ To log to MongoDB, it also needs the Ruby Mongo Driver
 
 - Add support for a configuration file that can set log level by class name
 - Configuration file to support adding appenders
-- Based on end-user demand add appenders for: Syslog, hadoop, redis, etc..
+- Based on end-user demand add appenders for: hadoop, redis, etc..
 
 Meta
 ----

data/lib/semantic_logger/appender/base.rb

@@ -36,7 +36,7 @@ module SemanticLogger
 
           message = log.message.to_s.dup
           message << " -- " << log.payload.inspect if log.payload
-          message << " -- " << "#{log.exception.class}: #{log.exception.message}\n#{(log.exception.backtrace || []).join("\n")}" if log.exception
+          message << " -- Exception: " << "#{log.exception.class}: #{log.exception.message}\n#{(log.exception.backtrace || []).join("\n")}" if log.exception
 
           duration_str = log.duration ? "(#{'%.1f' % log.duration}ms) " : ''
 
@@ -56,7 +56,7 @@ module SemanticLogger
 
           message = log.message.to_s.dup
           message << " -- " << log.payload.inspect if log.payload
-          message << " -- " << "#{colors::BOLD}#{log.exception.class}: #{log.exception.message}#{colors::CLEAR}\n#{(log.exception.backtrace || []).join("\n")}" if log.exception
+          message << " -- Exception: " << "#{colors::BOLD}#{log.exception.class}: #{log.exception.message}#{colors::CLEAR}\n#{(log.exception.backtrace || []).join("\n")}" if log.exception
 
           duration_str = log.duration ? "(#{colors::BOLD}#{'%.1f' % log.duration}ms#{colors::CLEAR}) " : ''
 

data/lib/semantic_logger/base.rb

@@ -70,28 +70,9 @@ module SemanticLogger
     #
     SemanticLogger::LEVELS.each_with_index do |level, index|
       class_eval <<-EOT, __FILE__, __LINE__
-        def #{level}(message=nil, payload=nil, exception=nil)
+        def #{level}(message=nil, payload=nil, exception=nil, &block)
           if @level_index <= #{index}
-            if exception.nil? && payload && payload.is_a?(Exception)
-              exception = payload
-              payload = nil
-            end
-
-            if block_given? && (result = yield)
-              if result.is_a?(String)
-                message = message.nil? ? result : "\#{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
-            log Log.new(:#{level}, Thread.current.name, name, message, payload, Time.now, nil, tags, #{index}, exception)
+            log_internal(:#{level}, #{index}, message, payload, exception, &block)
             true
           else
             false
@@ -102,41 +83,11 @@ module SemanticLogger
           @level_index <= #{index}
         end
 
-        def benchmark_#{level}(message, params = nil)
-          raise "Mandatory block missing" unless block_given?
+        def benchmark_#{level}(message, params = {}, &block)
           if @level_index <= #{index}
-            log_exception = params.nil? ? :partial : (params[:log_exception] || :partial)
-            min_duration  = params.nil? ? 0.0      : (params[:min_duration] || 0.0)
-            payload       = params.nil? ? nil      : params[:payload]
-            exception     = params.nil? ? nil      : params[:exception]
-            start         = Time.now
-            begin
-              yield
-            rescue Exception => exc
-              exception = exc
-            ensure
-              end_time = Time.now
-              duration = 1000.0 * (end_time - start)
-
-              # Add scoped payload
-              if self.payload
-                payload = payload.nil? ? self.payload : self.payload.merge(payload)
-              end
-              if exception
-                case log_exception
-                when :full
-                  log Log.new(:#{level}, Thread.current.name, name, message, payload, end_time, duration, tags, #{index}, exception)
-                when :partial
-                  log Log.new(:#{level}, Thread.current.name, name, "\#{message} -- Exception: \#{exception.class}: \#{exception.message}", payload, end_time, duration, tags, #{index}, nil)
-                end
-                raise exception
-              elsif duration >= min_duration
-                # Only log if the block took longer than 'min_duration' to complete
-                log Log.new(:#{level}, Thread.current.name, name, message, payload, end_time, duration, tags, #{index}, nil)
-              end
-            end
+            benchmark_internal(:#{level}, #{index}, message, params, &block)
           else
-            yield
+            block.call(params) if block
           end
         end
       EOT
@@ -213,8 +164,6 @@ module SemanticLogger
     alias :unknown :error
     alias :unknown? :error?
 
-    # #TODO implement a thread safe #silence method
-
     # DEPRECATED See SemanticLogger.default_level=
     def self.default_level=(level)
       warn "[DEPRECATION] `SemanticLogger::Logger.default_level=` is deprecated.  Please use `SemanticLogger.default_level=` instead."
@@ -272,7 +221,10 @@ module SemanticLogger
     #
     # level_index
     #   Internal index of the log level
-    Log = Struct.new(:level, :thread_name, :name, :message, :payload, :time, :duration, :tags, :level_index, :exception)
+    #
+    # metric [Object]
+    #   Object supplied when benchmark_x was called
+    Log = Struct.new(:level, :thread_name, :name, :message, :payload, :time, :duration, :tags, :level_index, :exception, :metric)
 
     # Internal method to return the log level as an internal index
     # Also supports mapping the ::Logger levels to SemanticLogger levels
@@ -297,5 +249,70 @@ module SemanticLogger
       index
     end
 
+    # Log message at the specified level
+    def log_internal(level, index, message=nil, payload=nil, exception=nil, &block)
+      if exception.nil? && payload && payload.is_a?(Exception)
+        exception = payload
+        payload = nil
+      end
+
+      if block && (result = block.call)
+        if result.is_a?(String)
+          message = message.nil? ? result : "#{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
+      log Log.new(level, Thread.current.name, name, message, payload, Time.now, nil, tags, index, exception)
+    end
+
+    # Measure the supplied block and log the message
+    def benchmark_internal(level, index, message, params, &block)
+      start     = Time.now
+      begin
+        rc = block.call(params) if block
+        exception = params[:exception]
+        rc
+      rescue Exception => exc
+        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
+        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] || raise("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
+          case log_exception
+          when :full
+            log Log.new(level, Thread.current.name, name, message, payload, end_time, duration, tags, index, exception, metric)
+          when :partial
+            log Log.new(level, Thread.current.name, name, "#{message} -- Exception: #{exception.class}: #{exception.message}", payload, end_time, duration, tags, index, nil, metric)
+          end
+          raise exception
+        elsif duration >= min_duration
+          # Only log if the block took longer than 'min_duration' to complete
+          log Log.new(level, Thread.current.name, name, message, payload, end_time, duration, tags, index, nil, metric)
+        end
+      end
+    end
+
   end
 end

data/lib/semantic_logger/core_ext/thread.rb

@@ -2,12 +2,9 @@ require 'thread'
 class Thread
   # Returns the name of the current thread
   # Default:
-  #    JRuby: The Java thread name
+  #    JRuby: The underlying Java thread name
   #    Other: String representation of this thread's object_id
   if defined? JRuby
-    # Design Note:
-    #   In JRuby with "thread.pool.enabled=true" each Ruby Thread instance is
-    #   new, even though the Java threads are being re-used from the pool
     def name
       @name ||= JRuby.reference(self).native_thread.name
     end
@@ -17,8 +14,15 @@ class Thread
     end
   end
 
-  # Set the name of this thread for logging and debugging purposes
-  def name=(name)
-    @name = name.to_s
+  # Set the name of this thread
+  #   On JRuby it also sets the underlying Java Thread name
+  if defined? JRuby
+    def name=(name)
+      JRuby.reference(self).native_thread.name = @name = name.to_s
+    end
+  else
+    def name=(name)
+      @name = name.to_s
+    end
   end
 end

data/lib/semantic_logger/logger.rb

@@ -105,11 +105,26 @@ module SemanticLogger
       queue_size
     end
 
+    # Supply a block to be called whenever a metric is seen during benchmark 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}"
+    #   end
+    def self.on_metric(&block)
+      (@@metric_subscribers  ||= ThreadSafe::Array.new) << block
+    end
+
     ############################################################################
     protected
 
-    @@appender_thread = nil
-    @@queue           = Queue.new
+    @@appender_thread    = nil
+    @@queue              = Queue.new
+    @@metric_subscribers = nil
 
     # Queue to hold messages that need to be logged to the various appenders
     def self.queue
@@ -167,6 +182,7 @@ module SemanticLogger
                 logger.error "Appender thread: Failed to log to appender: #{appender.inspect}", exc
               end
             end
+            call_metric_subscribers(message) if message.metric
             count += 1
             # Check every few log messages whether this appender thread is falling behind
             if count > lag_check_interval
@@ -180,7 +196,7 @@ module SemanticLogger
             when :flush
               SemanticLogger.appenders.each do |appender|
                 begin
-                  logger.info "Appender thread: Flushing appender: #{appender.name}"
+                  logger.debug "Appender thread: Flushing appender: #{appender.name}"
                   appender.flush
                 rescue Exception => exc
                   logger.error "Appender thread: Failed to flush appender: #{appender.inspect}", exc
@@ -188,7 +204,7 @@ module SemanticLogger
               end
 
               message[:reply_queue] << true if message[:reply_queue]
-              logger.info "Appender thread: All appenders flushed"
+              logger.debug "Appender thread: All appenders flushed"
             else
               logger.warn "Appender thread: Ignoring unknown command: #{message[:command]}"
             end
@@ -213,5 +229,19 @@ module SemanticLogger
       end
     end
 
+    # Call Metric subscribers
+    def self.call_metric_subscribers(log_struct)
+      # If no subscribers registered, then return immediately
+      return unless @@metric_subscribers
+
+      @@metric_subscribers.each do |subscriber|
+        begin
+          subscriber.call(log_struct)
+        rescue Exception => exc
+          logger.error "Exception calling subscriber", exc
+        end
+      end
+    end
+
   end
 end

data/lib/semantic_logger/semantic_logger.rb

@@ -102,13 +102,12 @@ module SemanticLogger
 
     # Start appender thread if it is not already running
     SemanticLogger::Logger.start_appender_thread
-    
+
     appender_instance
   end
 
   # Remove an existing appender
   # Currently only supports appender instances
-  # TODO allow removing by filename, STDOUT etc..
   def self.remove_appender(appender)
     @@appenders.delete(appender)
   end
@@ -137,6 +136,20 @@ module SemanticLogger
     SemanticLogger::Logger.start_appender_thread
   end
 
+  # Supply a block to be called whenever a metric is seen during benchmark 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}"
+  #   end
+  def self.on_metric(&block)
+    SemanticLogger::Logger.on_metric(&block)
+  end
+
   ############################################################################
   protected
 

data/lib/semantic_logger/version.rb

@@ -1,3 +1,3 @@
 module SemanticLogger #:nodoc
-  VERSION = "2.6.1"
+  VERSION = "2.7.0"
 end

data/test/appender_file_test.rb

@@ -39,7 +39,7 @@ class AppenderFileTest < Test::Unit::TestCase
 
       should "handle message, payload, and exception" do
         @appender.debug 'hello world', @hash, StandardError.new("StandardError")
-        assert_match /\d+-\d+-\d+ \d+:\d+:\d+.\d+ D \[\d+:#{@thread_name}\] SemanticLogger::Appender::File -- hello world -- #{@hash_str} -- StandardError: StandardError\n\n/, @io.string
+        assert_match /\d+-\d+-\d+ \d+:\d+:\d+.\d+ D \[\d+:#{@thread_name}\] SemanticLogger::Appender::File -- hello world -- #{@hash_str} -- Exception: StandardError: StandardError\n\n/, @io.string
       end
     end
 

data/test/logger_test.rb

@@ -17,10 +17,16 @@ class LoggerTest < Test::Unit::TestCase
       @mock_logger = MockLogger.new
       SemanticLogger.add_appender(@mock_logger)
 
+      # Add mock metric subscriber
+      $last_metric = nil
+      SemanticLogger.on_metric do |log_struct|
+        $last_metric = log_struct.dup
+      end
+
       # Use this test's class name as the application name in the log output
-      @logger            = SemanticLogger::Logger.new(self.class, :trace)
-      @hash              = { :session_id => 'HSSKLEU@JDK767', :tracking_number => 12345 }
-      @hash_str          = @hash.inspect.sub("{", "\\{").sub("}", "\\}")
+      @logger   = SemanticLogger::Logger.new(self.class, :trace)
+      @hash     = { :session_id => 'HSSKLEU@JDK767', :tracking_number => 12345 }
+      @hash_str = @hash.inspect.sub("{", "\\{").sub("}", "\\}")
       assert_equal [], @logger.tags
     end
 
@@ -120,6 +126,14 @@ class LoggerTest < Test::Unit::TestCase
             SemanticLogger.flush
             assert_match /\d+-\d+-\d+ \d+:\d+:\d+.\d+ \w \[\d+:.+\] \(\d+\.\dms\) LoggerTest -- hello world -- Exception: RuntimeError: Test -- #{@hash_str}/, @mock_logger.message
           end
+
+          should "log #{level} info with metric" do
+            metric_name = '/my/custom/metric'
+            assert_equal "result", @logger.send("benchmark_#{level}".to_sym, 'hello world', metric: metric_name) { "result" } # Measure duration of the supplied block
+            SemanticLogger.flush
+            assert_match /\d+-\d+-\d+ \d+:\d+:\d+.\d+ \w \[\d+:.+\] \(\d+\.\dms\) LoggerTest -- hello world/, @mock_logger.message
+            assert metric_name, $last_metric.metric
+          end
         end
 
         should "log when the block performs a return" do

metadata

@@ -1,41 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: semantic_logger
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Reid Morrison
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-11 00:00:00.000000000 Z
+date: 2014-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sync_attr
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
   name: thread_safe
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
 description: Semantic Logger takes logging in Ruby to a new level by adding several
@@ -46,6 +46,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/semantic_logger.rb
 - lib/semantic_logger/appender/base.rb
 - lib/semantic_logger/appender/file.rb
 - lib/semantic_logger/appender/mongodb.rb
@@ -57,10 +61,6 @@ files:
 - lib/semantic_logger/logger.rb
 - lib/semantic_logger/semantic_logger.rb
 - lib/semantic_logger/version.rb
-- lib/semantic_logger.rb
-- LICENSE.txt
-- Rakefile
-- README.md
 - test/appender_file_test.rb
 - test/appender_mongodb_test.rb
 - test/appender_syslog_test.rb
@@ -78,17 +78,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
 summary: Improved logging for Ruby