semantic_logger 2.0.0 → 2.1.0

data/Rakefile

@@ -2,6 +2,7 @@ lib = File.expand_path('../lib/', __FILE__)
 $:.unshift lib unless $:.include?(lib)
 
 require 'rubygems'
+require 'rubygems/package'
 require 'rake/clean'
 require 'rake/testtask'
 require 'date'
@@ -19,13 +20,13 @@ task :gem  do |t|
     spec.date        = Date.today.to_s
     spec.summary     = "Improved logging for Ruby"
     spec.description = "Semantic Logger takes logging in Ruby to a new level by adding several new capabilities to the commonly used Logging API"
-    spec.files       = FileList["./**/*"].exclude(/.gem$/, /.log$/,/^nbproject/).map{|f| f.sub(/^\.\//, '')}
+    spec.files       = FileList["./**/*"].exclude(/\.gem$/, /\.log$/,/nbproject/).map{|f| f.sub(/^\.\//, '')}
+    spec.license     = "Apache License V2.0"
     spec.has_rdoc    = true
-    spec.add_dependency 'sync_attr'
-    spec.add_dependency 'thread_safe'
-    spec.add_development_dependency 'shoulda'
+    spec.add_dependency 'sync_attr', '>= 1.0'
+    spec.add_dependency 'thread_safe', '>= 0.1.0'
   end
-  Gem::Builder.new(gemspec).build
+  Gem::Package.build gemspec
 end
 
 desc "Run Test Suite"

data/lib/semantic_logger.rb

@@ -1,6 +1,7 @@
 # Place requires here to prevent issues on JRuby with global.require.lock=true
 require 'thread'
 require 'semantic_logger/version'
+require 'semantic_logger/semantic_logger'
 
 module SemanticLogger
   autoload :Base,      'semantic_logger/base'
@@ -13,7 +14,4 @@ module SemanticLogger
     autoload :Wrapper, 'semantic_logger/appender/wrapper'
     autoload :MongoDB, 'semantic_logger/appender/mongodb'
   end
-
-  # Logging levels in order with most detailed logging first
-  LEVELS = [:trace, :debug, :info, :warn, :error, :fatal]
 end

data/lib/semantic_logger/appender/file.rb

@@ -12,15 +12,15 @@ module SemanticLogger
       #    require 'semantic_logger'
       #
       #    # Enable trace level logging
-      #    SemanticLogger::Logger.level = :info
+      #    SemanticLogger.default_level = :info
       #
       #    # Log to screen
-      #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new(STDOUT)
+      #    SemanticLogger.add_appender(STDOUT)
       #
       #    # And log to a file at the same time
-      #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new('application.log')
+      #    SemanticLogger::Logger.add_appender('application.log')
       #
-      #    logger =  SemanticLogger::Logger.new('test')
+      #    logger = SemanticLogger['test']
       #    logger.info 'Hello World'
       #
       # Example 2. To log all levels to file and only :info and above to screen:
@@ -28,19 +28,19 @@ module SemanticLogger
       #    require 'semantic_logger'
       #
       #    # Enable trace level logging
-      #    SemanticLogger::Logger.level = :trace
+      #    SemanticLogger.default_level = :trace
       #
       #    # Log to screen but only display :info and above
-      #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new(STDOUT, :info)
+      #    SemanticLogger.add_appender(STDOUT, :info)
       #
       #    # And log to a file at the same time, including all :trace level data
-      #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new('application.log')
+      #    SemanticLogger.add_appender('application.log')
       #
-      #    logger =  SemanticLogger::Logger.new('test')
+      #    logger =  SemanticLogger['test']
       #    logger.info 'Hello World'
       #
       def initialize(filename, level=nil, &block)
-        raise "logger cannot be null when initializing the SemanticLogging::Appender::Logger" unless filename
+        raise "filename cannot be null when initializing the SemanticLogging::Appender::File" unless filename
         @filename = filename
         @log = if filename.respond_to?(:write) and filename.respond_to?(:close)
           filename

data/lib/semantic_logger/appender/wrapper.rb

@@ -13,22 +13,22 @@ module SemanticLogger
       #    require 'logger'
       #    require 'semantic_logger'
       #    ruby_logger = Logger.new(STDOUT)
-      #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::Wrapper.new(ruby_logger)
-      #    logger =  SemanticLogger::Logger.new('test')
+      #    SemanticLogger.add_appender(ruby_logger)
+      #    logger =  SemanticLogger['test']
       #    logger.info('Hello World', :some => :payload)
       #
       # Enhance the Rails Logger
       #    # Add the Rails logger to the list of appenders
-      #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::Wrapper.new(Rails.logger)
-      #    Rails.logger = SemanticLogger::Logger.new('Rails')
+      #    SemanticLogger.add_appender(Rails.logger)
+      #    Rails.logger = SemanticLogger['Rails']
       #
       #    # Make ActiveRecord logging include its class name in every log entry
-      #    ActiveRecord::Base.logger = SemanticLogger::Logger.new('ActiveRecord')
+      #    ActiveRecord::Base.logger = SemanticLogger['ActiveRecord']
       #
       # Note: Since the log level is controlled by setting the Ruby or Rails logger directly
       #   the level is ignored for this appender
       def initialize(logger, &block)
-        raise "logger cannot be null when initiailizing the SemanticLogging::Appender::Logger" unless logger
+        raise "logger cannot be null when initiailizing the SemanticLogging::Appender::Wrapper" unless logger
         @logger = logger
 
         # Set the formatter to the supplied block

data/lib/semantic_logger/base.rb

@@ -17,9 +17,9 @@ module SemanticLogger
     #
     # Note: This level is only for this particular appender. It does not override
     #   the log level in any logging instance or the default log level
-    #   SemanticLogger::Logger.level
+    #   SemanticLogger.default_level
     #
-    # Must be one of the values in SemanticLogger::Logger::LEVELS
+    # Must be one of the values in SemanticLogger::LEVELS
     def level=(level)
       @level_index = self.class.map_level_to_index(level)
       @level = level
@@ -51,15 +51,15 @@ module SemanticLogger
     #    require 'semantic_logger'
     #
     #    # Enable trace level logging
-    #    SemanticLogger::Logger.level = :info
+    #    SemanticLogger.default_level = :info
     #
     #    # Log to screen
-    #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new(STDOUT)
+    #    SemanticLogger.add_appender(STDOUT)
     #
     #    # And log to a file at the same time
-    #    SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new('application.log')
+    #    SemanticLogger.add_appender('application.log')
     #
-    #    logger = SemanticLogger::Logger.new('MyApplication')
+    #    logger = SemanticLogger['MyApplication']
     #    logger.debug("Only display this if log level is set to Debug or lower")
     #
     #    # Log semantic information along with a text message
@@ -204,19 +204,16 @@ module SemanticLogger
 
     # #TODO implement a thread safe #silence method
 
-    # Initial default Level for all new instances of SemanticLogger::Logger
-    @@default_level = :info
-
-    # Allow for setting the global default log level
-    # This change only applies to _new_ loggers, existing logger levels
-    # will not be changed in any way
+    # DEPRECATED See SemanticLogger.default_level=
     def self.default_level=(level)
-      @@default_level = level
+      warn "[DEPRECATION] `SemanticLogger::Logger.default_level=` is deprecated.  Please use `SemanticLogger.default_level=` instead."
+      SemanticLogger.default_level = level
     end
 
-    # Returns the global default log level for new Logger instances
+    # DEPRECATED See SemanticLogger.default_level
     def self.default_level
-      @@default_level
+      warn "[DEPRECATION] `SemanticLogger::Logger.default_level` is deprecated.  Please use `SemanticLogger.default_level` instead."
+      SemanticLogger.default_level
     end
 
     ############################################################################
@@ -224,7 +221,7 @@ module SemanticLogger
 
     def initialize(klass, level=nil)
       @name = klass.is_a?(String) ? klass : klass.name
-      self.level = level || self.class.default_level
+      self.level = level || SemanticLogger.default_level
     end
 
     # Write log data to underlying data storage

data/lib/semantic_logger/loggable.rb

@@ -10,9 +10,11 @@ require 'sync_attr'
 # Example
 #
 #  require 'semantic_logger'
+#  SemanticLogger.default_level = :debug
+#  SemanticLogger.add_appender(STDOUT)
 #
 #  class ExternalSupplier
-#    # Lazy load 'logger' class variable on first use
+#    # Create class and instance logger methods
 #    include SemanticLogger::Loggable
 #
 #    def call_supplier(amount, name)
@@ -33,14 +35,64 @@ module SemanticLogger
         include SyncAttr
 
         sync_cattr_reader :logger do
-          SemanticLogger::Logger.new(self)
+          SemanticLogger[self]
         end
       end
     end
 
     # Also make the logger available as an instance method MixIn
+    # The class logger can be replaced using an instance specific #logger= below
     def logger
-      self.class.logger
+      @semantic_logger ||= self.class.logger
+    end
+
+    # Set instance specific logger
+    #
+    # By default instances of the class will use the class logger. Sometimes it
+    # is useful to be able to add instance specific logging data to the class name.
+    #
+    # For example, server or host_name that the class instance is using.
+    #
+    # Example:
+    #   require 'semantic_logger'
+    #   SemanticLogger.default_level = :debug
+    #   SemanticLogger.add_appender(STDOUT)
+    #
+    #   class MyClass
+    #     include SemanticLogger::Loggable
+    #
+    #     def self.my_name=(my_name)
+    #       # Use class level logger that only logs class name
+    #       logger.info "My name is changed to #{my_name}"
+    #
+    #       @@my_name = my_name
+    #     end
+    #
+    #     def initialize(host_name)
+    #       # Add host_name to every log entry in this logging instance
+    #       self.logger = SemanticLogger["#{self.class.name} [#{host_name}]"]
+    #
+    #       logger.info "Started server"
+    #     end
+    #
+    #     def check
+    #       logger.debug "Checking..."
+    #     end
+    #   end
+    #
+    #   MyClass.my_name = "Joe"
+    #
+    #   mine = MyClass.new('server.com')
+    #   mine.check
+    #
+    # # Generates the following log output:
+    #
+    # 2013-04-02 15:08:42.368574 I [37279:70198560687720] MyClass -- My name is changed to Joe
+    # 2013-04-02 15:08:42.369934 I [37279:70198560687720] MyClass [server.com] -- Started server
+    # 2013-04-02 15:08:42.371171 D [37279:70198560687720] MyClass [server.com] -- Checking...
+    #
+    def logger=(logger)
+      @semantic_logger = logger
     end
 
   end

data/lib/semantic_logger/logger.rb

@@ -1,43 +1,9 @@
 require 'thread_safe'
 
-# Logger is the interface used by
-#
-# Logger maintains the logging name to be used for all log entries generated
-# by the invoking classes or modules
-#
-# It is recommended to create an instance of the class for every class or
-# module so that it can be uniquely identified and searched on
-#
-# Example, log to Logger:
-#   require 'logger'
-#   require 'semantic_logger'
-#   log = Logger.new(STDOUT)
-#   log.level = Logger::DEBUG
-#
-#   SemanticLogger::Logger.appenders << SemanticLogger::Appender::Logger.new(log)
-#
-#   logger = SemanticLogger::Logger.new("my.app.class")
-#   logger.debug("Login time", :user => 'Joe', :duration => 100, :ip_address=>'127.0.0.1')
-#
-#   # Now log to the Logger above as well as MongoDB at the same time
-#
-#   db = Mongodb::Connection.new['production_logging']
-#
-#   SemanticLogger::Logger.appenders << SemanticLogger::Appender::MongoDB.new(
-#     :db              => db,
-#     :collection_size => 25.gigabytes
-#   )
-# ...
-#   # This will be logged to both the Ruby Logger and MongoDB
-#   logger.debug("Login time", :user => 'Mary', :duration => 230, :ip_address=>'192.168.0.1')
-#
+# 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
 module SemanticLogger
   class Logger < Base
-    # Add or remove logging appenders to the thread-safe appenders Array
-    # Appenders will be written to in the order that they appear in this list
-    def self.appenders
-      @@appenders
-    end
 
     # Returns a Logger instance
     #
@@ -53,11 +19,11 @@ module SemanticLogger
     #
     #  level
     #    The initial log level to start with for this logger instance
-    #    Default: SemanticLogger::Logger.default_level
+    #    Default: SemanticLogger.default_level
     #
     def initialize(klass, level=nil)
       @name = klass.is_a?(String) ? klass : klass.name
-      self.level = level || self.class.default_level
+      self.level = level || SemanticLogger.default_level
     end
 
     # Returns [Integer] the number of log entries that have not been written
@@ -71,12 +37,6 @@ module SemanticLogger
       queue.size
     end
 
-    # DEPRECATED: Please use queue_size instead.
-    def self.cache_count
-      warn "[DEPRECATION] 'SemanticLogger::Logger.cache_count' is deprecated.  Please use 'SemanticLogger::Logger.queue_size' instead."
-      queue_size
-    end
-
     # 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
@@ -121,11 +81,21 @@ module SemanticLogger
       @@logger = logger
     end
 
+    # DEPRECATED See SemanticLogger.add_appender
+    def self.appenders
+      warn "[DEPRECATION] `SemanticLogger::Logger.appenders` is deprecated.  Please use `SemanticLogger.add_appender` instead."
+      SemanticLogger.appenders
+    end
+
+    # DEPRECATED: Please use queue_size instead.
+    def self.cache_count
+      warn "[DEPRECATION] 'SemanticLogger::Logger.cache_count' is deprecated.  Please use 'SemanticLogger::Logger.queue_size' instead."
+      queue_size
+    end
 
     ############################################################################
     protected
 
-    @@appenders       = ThreadSafe::Array.new
     @@appender_thread = nil
     @@queue           = Queue.new
 
@@ -177,7 +147,7 @@ module SemanticLogger
         count = 0
         while message = queue.pop
           if message.is_a? Log
-            appenders.each do |appender|
+            SemanticLogger.appenders.each do |appender|
               begin
                 appender.log(message)
               rescue Exception => exc
@@ -195,7 +165,7 @@ module SemanticLogger
           else
             case message[:command]
             when :flush
-              appenders.each do |appender|
+              SemanticLogger.appenders.each do |appender|
                 begin
                   logger.info "Appender thread: Flushing appender: #{appender.name}"
                   appender.flush

data/lib/semantic_logger/semantic_logger.rb

@@ -0,0 +1,135 @@
+require 'thread_safe'
+module SemanticLogger
+  # Logging levels in order of most detailed to most severe
+  LEVELS = [:trace, :debug, :info, :warn, :error, :fatal]
+
+  # Return a logger for the supplied class or class_name
+  def self.[](klass)
+    SemanticLogger::Logger.new(klass)
+  end
+
+  # Allow for setting the global default log level
+  # This change only applies to _new_ loggers, existing logger levels
+  # will not be changed in any way
+  def self.default_level=(level)
+    @@default_level = level
+  end
+
+  # Returns the global default log level for new Logger instances
+  def self.default_level
+    @@default_level
+  end
+
+  # Add a new logging appender as a new destination for all log messages
+  # emitted from Semantic Logger
+  #
+  # Appenders will be written to in the order that they are added
+  #
+  # If a block is supplied then it will be used to customize the format
+  # of the messages sent to that appender. See SemanticLogger::Logger.new for
+  # 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
+  #
+  #   log_level [Symbol]
+  #     Optional
+  #     By setting the log_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
+  #
+  # Examples:
+  #
+  #   # Send all logging output to Standard Out (Screen)
+  #   SemanticLogger.add_appender(STDOUT)
+  #
+  #   # Send all logging output to a file
+  #   SemanticLogger.add_appender('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)
+  #
+  # Log to an existing logger:
+  #
+  #   # Send Semantic logging output to an existing logger
+  #   require 'logger'
+  #   require 'semantic_logger'
+  #
+  #   # Built-in Ruby logger
+  #   log = Logger.new(STDOUT)
+  #   log.level = Logger::DEBUG
+  #
+  #   SemanticLogger.default_level = :debug
+  #   SemanticLogger.add_appender(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, log_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, log_level, &block)
+    elsif appender.is_a? Appender::Base
+      # Already an instance of an appender
+      appender.log_level = log_level if log_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 #{log_level}, update the log level directly against the supplied appender" if log_level
+      SemanticLogger::Appender::Wrapper.new(appender, &block)
+    end
+    @@appenders << 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
+
+  # Returns [SemanticLogger::Appender::Base] a copy of the list of active
+  # appenders for debugging etc.
+  # Use SemanticLogger.add_appender and SemanticLogger.remove_appender
+  # to manipulate the active appenders list
+  def self.appenders
+    @@appenders.dup
+  end
+
+  # Wait until all queued log messages have been written and flush all active
+  # appenders
+  def self.flush
+    SemanticLogger::Logger.flush
+  end
+
+  ############################################################################
+  protected
+
+  @@appenders     = ThreadSafe::Array.new
+
+  ############################################################################
+  private
+
+  # Initial default Level for all new instances of SemanticLogger::Logger
+  @@default_level = :info
+end