madvertise-logging 0.1.0 → 0.2.0

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/Gemfile

@@ -6,5 +6,9 @@ gemspec
 group :test do
   gem 'rspec'
   gem 'simplecov'
+  gem 'ruby2ruby', '=1.3.0' # 1.3.1 is broken :(
+  gem 'reek'
+  gem 'yard'
+  gem 'redcarpet'
   gem 'syslogger', :require => false
 end

data/README.md

@@ -1,6 +1,10 @@
 # Madvertise::Logging
 
-TODO: Write a gem description
+The madvertise-logging gem is a collection of classes for logging related
+tasks. The main class (`ImprovedLogger`) is an improved version of DaemonKits
+`AbstractLogger` class including token support, buffer backend and more.
+
+[![Build Status](https://secure.travis-ci.org/madvertise/logging.png)](http://travis-ci.org/madvertise/logging)
 
 ## Installation
 
@@ -18,7 +22,7 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Please refer to the [API documentation](http://rubydoc.info/gems/madvertise-logging/frames).
 
 ## Contributing
 

data/lib/madvertise/logging/improved_logger.rb

@@ -3,12 +3,22 @@ require 'stringio'
 
 module Madvertise
   module Logging
+
+    ##
+    # ImprovedLogger is an enhanced version of DaemonKits AbstractLogger class
+    # with token support, buffer backend and more.
+    #
     class ImprovedLogger
 
+      # Write a copy of all log messages to STDOUT.
       attr_accessor :copy_to_stdout
-      attr_accessor :transaction_token
+
+      # Program name prefix. Used as ident for syslog backends.
       attr_accessor :progname
 
+      # Arbitrary token to prefix log messages with.
+      attr_accessor :token
+
       @severities = {
         :debug   => Logger::DEBUG,
         :info    => Logger::INFO,
@@ -21,217 +31,211 @@ module Madvertise
       @silencer = true
 
       class << self
+        # Hash of Symbol/Fixnum pairs to map Logger levels.
         attr_reader :severities
+
+        # Enable/disable the silencer on a global basis. Useful for debugging
+        # otherwise silenced code blocks.
         attr_accessor :silencer
       end
 
       def initialize(logfile = nil, progname = nil)
         @copy_to_stdout = false
         @progname = progname || File.basename($0)
-        self.logger = logfile || STDERR
+        self.logger = logfile
       end
 
-      # Silence the logger for the duration of the block.
-      def silence(temporary_level = :error)
-        if self.class.silencer
-          begin
-            old_level, self.level = self.level, temporary_level
-            yield self
-          ensure
-            self.level = old_level
-          end
-        else
-          yield self
-        end
+      # Get the backend logger.
+      #
+      # @return [Logger] The currently active backend logger object.
+      def logger
+        @logger ||= create_backend
       end
 
-      def debug(msg)
-        add(:debug, msg)
+      # Set a different backend.
+      #
+      # @param [Symbol, String, Logger] value  The new logger backend. Either a
+      #   Logger object, a String containing the logfile path or a Symbol to
+      #   create a default backend for :syslog or :buffer
+      # @return [Logger] The newly created backend logger object.
+      def logger=(value)
+        @logger.close rescue nil
+        @logfile = value.is_a?(String) ? value : nil
+        @backend = value.is_a?(Symbol) ? value : :logger
+        @logger = value.is_a?(Logger) ? value : create_backend
       end
 
-      def debug?
-        self.level == :debug
+      # Close any connections/descriptors that may have been opened by the
+      # current backend.
+      def close
+        logger.close rescue nil
+        @logger = nil
       end
 
-      def info(msg)
-        add(:info, msg)
+      # Retrieve the current buffer in case this instance is a buffered logger.
+      #
+      # @return [String] Contents of the buffer.
+      def buffer
+        @logfile.string if @backend == :buffer
+      end
+
+      # Get the current logging level.
+      #
+      # @return [Symbol] Current logging level.
+      def level
+        self.class.severities.invert[@logger.level]
       end
 
-      def info?
-        self.level == :info
+      # Set the logging level.
+      #
+      # @param [Symbol, Fixnum] level  New level as Symbol or Fixnum from Logger class.
+      # @return [Fixnum] New level converted to Fixnum from Logger class.
+      def level=(level)
+        level = level.is_a?(Symbol) ? self.class.severities[level] : level
+        logger.level = level
       end
 
-      def warn(msg)
-        add(:warn, msg)
+      # Log a debug level message.
+      def debug(msg)
+        add(:debug, msg)
       end
 
-      def warn?
-        self.level == :warn
+      # Log an info level message.
+      def info(msg)
+        add(:info, msg)
       end
 
-      def error(msg)
-        add(:error, msg)
+      # Log a warning level message.
+      def warn(msg)
+        add(:warn, msg)
       end
 
-      def error?
-        self.level == :error
+      # Log an error level message.
+      def error(msg)
+        add(:error, msg)
       end
 
+      # Log a fatal level message.
       def fatal(msg)
         add(:fatal, msg)
       end
 
-      def fatal?
-        self.level == :fatal
-      end
-
+      # Log a message with unknown level.
       def unknown(msg)
         add(:unknown, msg)
       end
 
-      def unknown?
-        self.level == :unknown
-      end
-
-      def exception(e)
-        if e.is_a?(::Exception)
-          message = "EXCEPTION: #{e.message}: #{clean_trace(e.backtrace)}"
+      # Log an exception with error level.
+      #
+      # @param [Exception, String] exc  The exception to log. If exc is a
+      #   String no backtrace will be generated.
+      def exception(exc)
+        if exc.is_a?(::Exception)
+          message = "EXCEPTION: #{exc.message}: #{clean_trace(exc.backtrace)}"
         else
-          message = e
+          message = exc
         end
         add(:error, message, true)
       end
 
-      def add(severity, message, skip_caller = false)
-        message = "#{called(caller)}: #{message}" unless skip_caller
-        message = "[#{@transaction_token}] #{message}" if @transaction_token
-
-        self.logger.add(self.class.severities[severity]) { message }
-
-        STDOUT.puts(message) if self.copy_to_stdout && self.class.severities[severity] >= self.logger.level
-      end
-
-      def level
-        self.class.severities.invert[@logger.level]
-      end
-
-      def level=(level)
-        level = (Symbol === level ? self.class.severities[level] : level)
-        self.logger.level = level
-      end
-
-      def new_transaction(v)
-        @transaction_token = v
-      end
-
-      def end_transaction
-        @transaction_token = nil
-      end
-
-      def save_transaction(obj)
-        if @transaction_token && obj
-          @transactions ||= {}
-          @transactions[obj.object_id] = @transaction_token
+      # Save the current token and associate it with obj#object_id.
+      def save_token(obj)
+        if @token
+          @tokens ||= {}
+          @tokens[obj.object_id] = @token
         end
       end
 
-      def restore_transaction(obj)
-        @transactions ||= {}
-        @transaction_token = @transactions.delete(obj.object_id) if obj
-      end
-
-      def logger
-        @logger ||= create_logger
+      # Restore the token that has been associated with obj#object_id.
+      def restore_token(obj)
+        @tokens ||= {}
+        @token = @tokens.delete(obj.object_id)
       end
 
-      def logger=(value)
-        @logger.close rescue nil
-
-        if value.is_a?(Logger)
-          @backend = :logger
-          @logger = value
-        elsif value.is_a?(Symbol)
-          @backend = value
-          @logger = create_logger
+      # Silence the logger for the duration of the block.
+      def silence(temporary_level = :error)
+        if self.class.silencer
+          begin
+            old_level, self.level = self.level, temporary_level
+            yield self
+          ensure
+            self.level = old_level
+          end
         else
-          @backend = :logger
-          @logfile = value
-          @logger = create_logger
+          yield self
         end
       end
 
+      # Remove references to the madvertise-logging gem from exception
+      # backtraces.
+      #
+      # @private
       def clean_trace(trace)
-        trace = trace.map { |l| l.gsub(ROOT, '') }
-        trace = trace.reject { |l| l =~ /gems\/madvertise-logging/ }
-        trace = trace.reject { |l| l =~ /vendor\/madvertise-logging/ }
-        trace
-      end
-
-      def close
-        case @backend
-        when :logger
-          self.logger.close
-          @logger = nil
-        end
-      end
-
-      def buffer
-        if @backend == :buffer && @buffer
-          @buffer.string
+        trace.map do |line|
+          line.gsub(ROOT, '')
+        end.reject do |line|
+          line =~ /(gems|vendor)\/madvertise-logging/
         end
       end
 
       private
 
-      def called(trace)
-        l = trace.detect('unknown:0') do |l|
-          l.index(File.basename(__FILE__)).nil?
+      # Return the first callee outside the madvertise-logging gem. Used in add
+      # to figure out where in the source code a message has been produced.
+      def called_from
+        location = caller.detect('unknown:0') do |line|
+          line.match(/(improved_logger|multi_logger)\.rb/).nil?
         end
 
-        file, num, _ = l.split(':')
+        file, num, discard = location.split(':')
         [ File.basename(file), num ].join(':')
       end
 
-      def create_logger
+      def add(severity, message, skip_caller = false)
+        severity = self.class.severities[severity]
+        message = "#{called_from}: #{message}" unless skip_caller
+        message = "[#{@token}] #{message}" if @token
+
+        logger.add(severity) { message }
+
+        STDOUT.puts(message) if self.copy_to_stdout && severity >= @logger.level
+      end
+
+      def create_backend
         case @backend
         when :buffer
-          create_buffering_logger
+          create_buffering_backend
         when :syslog
-          create_syslog_logger
+          create_syslog_backend
         else
-          create_standard_logger
+          create_standard_backend
         end
       end
 
-      def create_buffering_logger
-        @buffer = StringIO.new
-        Logger.new(@buffer).tap do |l|
-          l.formatter = Formatter.new
-          l.progname = progname
-        end
+      def create_buffering_backend
+        @logfile = StringIO.new
+        create_logger
       end
 
-      def create_standard_logger
-        @logfile ||= STDERR
-
-        if @logfile.is_a?(String)
-          logdir = File.dirname(@logfile)
-
-          begin
-            FileUtils.mkdir_p(logdir)
-          rescue
-            STDERR.puts "#{logdir} not writable, using STDERR for logging"
-            @logfile = STDERR
-          end
+      def create_standard_backend
+        begin
+          FileUtils.mkdir_p(File.dirname(@logfile))
+        rescue
+          STDERR.puts "#{@logfile} not writable, using STDERR for logging" if @logfile
+          @logfile = STDERR
         end
 
-        Logger.new(@logfile).tap do |l|
-          l.formatter = Formatter.new
-          l.progname = progname
+        create_logger
+      end
+
+      def create_logger
+        Logger.new(@logfile).tap do |logger|
+          logger.formatter = Formatter.new
+          logger.progname = progname
         end
       end
 
-      def create_syslog_logger
+      def create_syslog_backend
         begin
           require 'syslogger'
           Syslogger.new(progname, Syslog::LOG_PID, Syslog::LOG_LOCAL1)
@@ -241,23 +245,25 @@ module Madvertise
         end
       end
 
+      ##
+      # The Formatter class is responsible for formatting log messages. The
+      # default format is:
+      #
+      #   YYYY:MM:DD HH:MM:SS.MS daemon_name(pid) level: message
+      #
       class Formatter
 
-        # YYYY:MM:DD HH:MM:SS.MS daemon_name(pid) level: message
         @format = "%s %s(%d) [%s] %s\n"
 
         class << self
+          # Format string for log messages.
           attr_accessor :format
         end
 
+        # @private
         def call(severity, time, progname, msg)
-          self.class.format % [format_time( time ), progname, $$, severity, msg.to_s]
-        end
-
-        private
-
-        def format_time(time)
-          time.strftime("%Y-%m-%d %H:%M:%S.") + time.usec.to_s
+          time = time.strftime("%Y-%m-%d %H:%M:%S.") + time.usec.to_s
+          self.class.format % [time, progname, $$, severity, msg.to_s]
         end
       end
     end

data/lib/madvertise/logging/multi_logger.rb

@@ -1,22 +1,32 @@
 module Madvertise
   module Logging
+
+    ##
+    # MultiLogger is a simple class for multiplexing ImprovedLogger objects. It
+    # support attach/detach to send messages to any number of loggers.
+
     class MultiLogger
       def initialize(*loggers)
         @loggers = loggers
       end
 
+      # Attach an ImprovedLogger object.
       def attach(logger)
-        logger.new_transaction(@loggers.first.transaction_token)
+        logger.token = @loggers.first.token
         @loggers << logger
       end
 
+      # Detach an ImprovedLogger object.
       def detach(logger)
         @loggers.delete(logger)
       end
 
+      # Delegate all method calls to all attached loggers.
+      #
+      # @private
       def method_missing(name, *args)
-        @loggers.each do |l|
-          l.send(name, *args)
+        @loggers.each do |logger|
+          logger.send(name, *args)
         end
       end
     end

data/lib/madvertise/logging/version.rb

@@ -1,5 +1,6 @@
 module Madvertise
   module Logging
-    VERSION = "0.1.0"
+    # @private
+    VERSION = "0.2.0"
   end
 end

data/spec/improved_logger_spec.rb

@@ -39,62 +39,32 @@ describe ImprovedLogger do
     @logfile.should have_received_message(/\[DEBUG\].*Debug test/)
   end
 
-  it "should return true if debug level is set" do
-    @logger.level = :debug
-    @logger.debug?.should be true
-  end
-
   it "should log info level messages" do
     @logger.info("Info test")
     @logfile.should have_received_message(/\[INFO\].*Info test/)
   end
 
-  it "should return true if info level is set" do
-    @logger.level = :info
-    @logger.info?.should be true
-  end
-
   it "should log warn level messages" do
     @logger.warn("Warn test")
     @logfile.should have_received_message(/\[WARN\].*Warn test/)
   end
 
-  it "should return true if warn level is set" do
-    @logger.level = :warn
-    @logger.warn?.should be true
-  end
-
   it "should log error level messages" do
     @logger.error("Err test")
     @logfile.should have_received_message(/\[ERROR\].*Err test/)
   end
 
-  it "should return true if error level is set" do
-    @logger.level = :error
-    @logger.error?.should be true
-  end
-
   it "should log fatal level messages" do
     @logger.fatal("Fatal test")
 
     @logfile.should have_received_message(/\[FATAL\].*Fatal test/)
   end
 
-  it "should return true if fatal level is set" do
-    @logger.level = :fatal
-    @logger.fatal?.should be true
-  end
-
   it "should log unknown level messages" do
     @logger.unknown("Unknown test")
     @logfile.should have_received_message(/\[ANY\].*Unknown test/)
   end
 
-  it "should return true if unknown level is set" do
-    @logger.level = :unknown
-    @logger.unknown?.should be true
-  end
-
   it "should log the caller file and line number" do
     f = File.basename(__FILE__)
     l = __LINE__ + 2
@@ -164,40 +134,39 @@ describe ImprovedLogger do
     ImprovedLogger.silencer = true
   end
 
-  it "should support a transaction token" do
+  it "should support a token" do
     token = "3d5e27f7-b97c-4adc-b1fd-adf1bd4314e0"
 
-    @logger.new_transaction(token)
-    @logger.info "This should include a transaction token"
+    @logger.token = token
+    @logger.info "This should include a token"
     @logfile.should have_received_message(token)
 
-    @logger.end_transaction
-    @logger.info "This should not include a transaction token"
+    @logger.token = nil
+    @logger.info "This should not include a token"
     @logfile.should_not have_received_message(token)
   end
 
-  it "should support save/restore on transaction tokens" do
+  it "should support save/restore on tokens" do
     token1 = "3d5e27f7-b97c-4adc-b1fd-adf1bd4314e0"
     token2 = "1bdef605-34b9-4ec7-9a1c-cb58efc8a635"
 
-    obj1 = Object.new
+    obj = Object.new
 
-    @logger.new_transaction(token1)
-    @logger.info "This should include transaction token1"
+    @logger.token = token1
+    @logger.info "This should include token1"
     @logfile.should have_received_message(token1)
 
-    @logger.save_transaction(obj1)
-    @logger.new_transaction(token2)
-    @logger.info "This should include transaction token2"
+    @logger.save_token(obj)
+    @logger.token = token2
+    @logger.info "This should include token2"
     @logfile.should have_received_message(token2)
-    @logger.end_transaction
 
-    @logger.restore_transaction(obj1)
-    @logger.info "This should include transaction token1"
+    @logger.restore_token(obj)
+    @logger.info "This should include token1"
     @logfile.should have_received_message(token1)
 
-    @logger.end_transaction
-    @logger.info "This should not include a transaction token"
+    @logger.token = nil
+    @logger.info "This should not include a token"
     @logfile.should_not have_received_message(token1)
     @logfile.should_not have_received_message(token2)
   end
@@ -224,6 +193,7 @@ describe ImprovedLogger do
     syslogger_paths = $:.select { |p| p.match(/gems\/.*syslogger-/) }
     $:.replace($: - syslogger_paths)
 
+    STDERR.should_receive(:puts).with(/using STDERR for logging/)
     STDERR.should_receive(:write).with(/reverting to standard logger/)
     @logger = ImprovedLogger.new(:syslog)
     @logger.logger.should be_instance_of(Logger)

data/tasks/reek.rake

@@ -0,0 +1,5 @@
+require 'reek/rake/task'
+
+Reek::Rake::Task.new do |t|
+  t.fail_on_error = false
+end

data/tasks/rspec.rake

@@ -1,20 +1,7 @@
-begin
-  require 'rspec'
-rescue LoadError
-  require 'rubygems'
-  require 'rspec'
-end
-
-begin
-  require 'rspec/core/rake_task'
+require 'rspec'
+require 'rspec/core/rake_task'
 
-  desc "Run the specs"
-  RSpec::Core::RakeTask.new do |t|
-    t.rspec_opts = ['--options', "spec/spec.opts"]
-  end
-rescue LoadError
-  puts <<-EOS
-To use rspec for testing you must install rspec gem:
-    gem install rspec
-EOS
+desc "Run the specs"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ['--options', "spec/spec.opts"]
 end

data/tasks/yard.rake

@@ -0,0 +1,5 @@
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb', 'README.rdoc']
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: madvertise-logging
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-19 00:00:00.000000000 Z
+date: 2012-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &15364280 !ruby/object:Gem::Requirement
+  requirement: &14192340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *15364280
+  version_requirements: *14192340
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &15363560 !ruby/object:Gem::Requirement
+  requirement: &14191540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *15363560
+  version_requirements: *14191540
 description: Advanced logging classes with buffer backend, transactions, multi logger,
   etc
 email:
@@ -43,6 +43,8 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rvmrc
+- .travis.yml
+- .yardopts
 - Gemfile
 - LICENSE
 - README.md
@@ -56,7 +58,9 @@ files:
 - spec/multi_logger_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- tasks/reek.rake
 - tasks/rspec.rake
+- tasks/yard.rake
 homepage: https://github.com/madvertise/logging
 licenses: []
 post_install_message: 
@@ -71,7 +75,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3354586897547183297
+      hash: 3732635707387209248
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -80,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3354586897547183297
+      hash: 3732635707387209248
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10
@@ -93,3 +97,4 @@ test_files:
 - spec/multi_logger_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+has_rdoc: