lumberjack 1.0.0

data/MIT_LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Brian Durand
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,86 @@
+= Lumberjack
+
+Lumberjack is a simple, powerful, and fast logging implementation in Ruby. It uses nearly the same API as the Logger class in the Ruby standard library and as ActiveSupport::BufferedLogger in Rails.
+
+== Usage
+
+This code aims to be extremely simple to use. The core interface it the Lumberjack::Logger which is used to log messages (which can be any object) with a specified Severity. Each logger has a level associated with it and messages are only written if their severity is greater than or equal to the level.
+
+  logger = Lumberjack::Logger.new("logs/application.log")  # Open a new log file with INFO level
+  logger.info("Begin request")
+  logger.debug(request.params)  # Message not written unless the level is set to DEBUG
+  begin
+    # do something
+  rescue => exception
+    logger.error(exception)
+    raise
+  end
+  logger.info("End request")
+
+This is all you need to know to log messages.
+
+== Features
+
+=== Meta data
+
+When messages are added to the log, additional data about the message is kept in a Lumberjack::LogEntry. This means you don't need to worry about adding the time or process id to your log messages as they will be automatically recorded.
+
+The following information is recorded for each message:
+
+* severity - The severity recorded for the message.
+* time - The time at which the message was recorded.
+* program name - The name of the program logging the message. This can be either set for all messages or customized with each message.
+* process id - The process id (pid) of the process that logged the message.
+* unit of work id - The unique 12 byte hexadecimal number generated for a unit of work.
+
+=== Units Of Work
+
+A unit of work can be used to tie together all log messages within a block. This can be very useful to isolate a group of messages that represent one path through the system. For instance, in a web application, a single request represents a natural unit of work,  and when you are looking through a log file, it is useful to see the entire set of log entries as a unit instead of interspersed with messages from other concurrent requests.
+
+  # All log entries in this block will get a common unit of work id.
+  Lumberjack.unit_of_work do
+    logger.info("Begin request")
+    yield
+    logger.info("End request")
+  end
+
+=== Pluggable Devices
+
+When a Logger logs a LogEntry, it sends it to a Lumberjack::Device. Lumberjack comes with a variety of devices for logging to IO streams or files.
+
+* Lumberjack::Device::Stream - Writes log entries to an IO stream.
+* Lumberjack::Device::LogFile - Writes log entries to a file.
+* Lumberjack::Device::DateRollingLogFile - Writes log entries to a file that will automatically roll itself based on date.
+* Lumberjack::Device::SizeRollingLogFile - Writes log entries to a file that will automatically roll itself based on size.
+* Lumberjack::Device::Null - This device produces no output and is intended for testing environments.
+
+If you'd like to send you log to a different kind of output, you just need to extend the Device class and implement the +write+ method.
+
+=== Customize Formatting
+
+When a message is logged, it is first converted into a string. You can customize how it is converted by adding mappings to a Formatter.
+
+  logger.formatter.add(Hash, :pretty_print)  # use the Formatter::PrettyPrintFormatter for all Hashes
+  logger.formatter.add(MyClass){|obj| "#{obj.class}@#{obj.id}"}  # use a block to provide a custom format
+
+If you use the built in devices, you can also customize the Template used to format the LogEntry.
+  
+  # Change the format of the time in the log
+  Lumberjack::Logger.new("application.log", :time_format => "%m/%d/%Y %H:%M:%S")
+
+  # Use a simple template that only includes the time and the message
+  Lumberjack::Logger.new("application.log", :template => ":time - :message")
+
+  # Use a custom template as a block that only includes the first character of the severity
+  template = lambda{|e| "#{e.severity_label[0, 1]} #{e.time} - #{e.message}"}
+  Lumberjack::Logger.new("application.log", :template => template)
+
+=== Buffered Performance
+
+The built in stream based logging devices use an internal buffer to increase performance by batching physical writes.
+
+=== Automatic Log Rolling
+
+The built in devices include two that can automatically roll log files based either on date or on file size. When a log file is rolled, it will be renamed with a suffix and a new file will be created to receive new log entries. This can keep your log files from growing to unusable sizes and removes the need to schedule an external process to roll the files.
+
+There is a similar feature in the standard library Logger class, but the implementation here is safe to use with multiple processes writing to the same log file.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'RVM likes to call it tests'
+task :tests => :test
+
+begin
+  require 'rspec'
+  require 'rspec/core/rake_task'
+  desc 'Run the unit tests'
+  RSpec::Core::RakeTask.new(:test)
+rescue LoadError
+  task :test do
+    STDERR.puts "You must have rspec 2.0 installed to run the tests"
+  end
+end
+
+desc 'Generate rdoc.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--title' << 'Lumberjack' << '--line-numbers' << '--inline-source' << '--main' << 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+namespace :rbx do
+  desc "Cleanup *.rbc files in lib directory"
+  task :delete_rbc_files do
+    FileList["lib/**/*.rbc"].each do |rbc_file|
+      File.delete(rbc_file)
+    end
+    nil
+  end
+end
+
+spec_file = File.expand_path('../lumberjack.gemspec', __FILE__)
+if File.exist?(spec_file)
+  spec = eval(File.read(spec_file))
+
+  Rake::GemPackageTask.new(spec) do |p|
+    p.gem_spec = spec
+  end
+  Rake.application["package"].prerequisites.unshift("rbx:delete_rbc_files")
+
+  desc "Release to rubygems.org"
+  task :release => :package do
+    require 'rake/gemcutter'
+    Rake::Gemcutter::Tasks.new(spec).define
+    Rake::Task['gem:push'].invoke
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/lumberjack.rb

@@ -0,0 +1,39 @@
+require 'rbconfig'
+require 'time'
+require 'thread'
+
+module Lumberjack
+  autoload :Device, File.expand_path("../lumberjack/device.rb", __FILE__)
+  autoload :Formatter, File.expand_path("../lumberjack/formatter.rb", __FILE__)
+  autoload :LogEntry, File.expand_path("../lumberjack/log_entry.rb", __FILE__)
+  autoload :Logger, File.expand_path("../lumberjack/logger.rb", __FILE__)
+  autoload :Rack, File.expand_path("../lumberjack/rack.rb", __FILE__)
+  autoload :Severity, File.expand_path("../lumberjack/severity.rb", __FILE__)
+  autoload :Template, File.expand_path("../lumberjack/template.rb", __FILE__)
+  
+  LINE_SEPARATOR = (Config::CONFIG['host_os'].match(/mswin/i) ? "\r\n" : "\n")
+
+  class << self
+    # Define a unit of work within a block. Within the block supplied to this
+    # method, calling +unit_of_work_id+ will return the same 12 digit hexadecimal number string.
+    # This can then be used for tying together log entries.
+    #
+    # For the common use case of treating a single web request as a unit of work, see the
+    # Lumberjack::Rack::UnitOfWork class.
+    def unit_of_work
+      save_val = Thread.current[:lumberjack_logger_unit_of_work_id]
+      #Thread.current[:lumberjack_logger_unit_of_work_id] = UniqueIdentifier.new
+      Thread.current[:lumberjack_logger_unit_of_work_id] = rand(0xFFFFFFFFFFFF).to_s(16).rjust(12, '0').upcase
+      begin
+        return yield
+      ensure
+        Thread.current[:lumberjack_logger_unit_of_work_id] = save_val
+      end
+    end
+    
+    # Get the UniqueIdentifier for the current unit of work.
+    def unit_of_work_id
+      Thread.current[:lumberjack_logger_unit_of_work_id] 
+    end
+  end
+end

data/lib/lumberjack/device.rb

@@ -0,0 +1,26 @@
+module Lumberjack
+  # This is an abstract class for logging devices. Subclasses must implement the +write+ method and
+  # may implement the +close+ and +flush+ methods if applicable.
+  class Device
+    autoload :DateRollingLogFile, File.expand_path("../device/date_rolling_log_file.rb", __FILE__)
+    autoload :LogFile, File.expand_path("../device/log_file.rb", __FILE__)
+    autoload :Null, File.expand_path("../device/null.rb", __FILE__)
+    autoload :RollingLogFile, File.expand_path("../device/rolling_log_file.rb", __FILE__)
+    autoload :SizeRollingLogFile, File.expand_path("../device/size_rolling_log_file.rb", __FILE__)
+    autoload :Writer, File.expand_path("../device/writer.rb", __FILE__)
+
+    # Subclasses must implement this method to write a LogEntry.
+    def write(entry)
+      raise NotImpelementedError
+    end
+    
+    # Subclasses may implement this method to close the device.
+    def close
+      flush
+    end
+    
+    # Subclasses may implement this method to flush any buffers used by the device.
+    def flush
+    end
+  end
+end

data/lib/lumberjack/device/date_rolling_log_file.rb

@@ -0,0 +1,58 @@
+require 'date'
+
+module Lumberjack
+  class Device
+    # This log device will append entries to a file and roll the file periodically by date. Files
+    # are rolled at midnight and can be rolled daily, weekly, or monthly. Archive file names will
+    # have the date appended to them in the format ".YYYY-MM-DD" for daily, ".week-of-YYYY-MM-DD" for weekly
+    # and ".YYYY-MM" for monthly. It is not guaranteed that log messages will break exactly on the
+    # roll period as buffered entries will always be written to the same file.
+    class DateRollingLogFile < RollingLogFile
+      # Create a new logging device to the specified file. The period to roll the file is specified
+      # with the <tt>:roll</tt> option which may contain a value of <tt>:daily</tt>, <tt>:weekly</tt>,
+      # or <tt>:monthly</tt>.
+      def initialize(path, options = {})
+        @file_date = Date.today
+        if options[:roll] && options[:roll].to_s.match(/(daily)|(weekly)|(monthly)/i)
+          @roll_period = $~[0].downcase.to_sym
+          options.delete(:roll)
+        else
+          raise ArgumentError.new("illegal value for :roll (#{options[:roll].inspect})")
+        end
+        super
+      end
+
+      def archive_file_suffix
+        case @roll_period
+        when :weekly
+          "#{@file_date.strftime('week-of-%Y-%m-%d')}"
+        when :monthly
+          "#{@file_date.strftime('%Y-%m')}"
+        else
+          "#{@file_date.strftime('%Y-%m-%d')}"
+        end
+      end
+
+      def roll_file?
+        date = Date.today
+        if date.year > @file_date.year
+          true
+        elsif @roll_period == :daily && date.yday > @file_date.yday
+          true
+        elsif @roll_period == :weekly && date.cweek > @file_date.cweek
+          true
+        elsif @roll_period == :monthly && date.month > @file_date.month
+          true
+        else
+          false
+        end
+      end
+      
+      protected
+      
+      def after_roll
+        @file_date = Date.today
+      end
+    end
+  end
+end

data/lib/lumberjack/device/log_file.rb

@@ -0,0 +1,18 @@
+require 'fileutils'
+
+module Lumberjack
+  class Device
+    # This is a logging device that appends log entries to a file.
+    class LogFile < Writer
+      # The absolute path of the file being logged to.
+      attr_reader :path
+      
+      # Create a logger to the file at +path+. Options are passed through to the Writer constructor.
+      def initialize(path, options = {})
+        @path = File.expand_path(path)
+        FileUtils.mkdir_p(File.dirname(@path))
+        super(File.new(@path, 'a'), options)
+      end
+    end
+  end
+end

data/lib/lumberjack/device/null.rb

@@ -0,0 +1,15 @@
+require 'date'
+
+module Lumberjack
+  class Device
+    # This is a logging device that produces no output. It can be useful in
+    # testing environments when log file output is not useful.
+    class Null < Device
+      def initialize(*args)
+      end
+      
+      def write(entry)
+      end
+    end
+  end
+end

data/lib/lumberjack/device/rolling_log_file.rb

@@ -0,0 +1,109 @@
+module Lumberjack
+  class Device
+    # This is an abstract class for a device that appends entries to a file and periodically archives
+    # the existing file and starts a one. Subclasses must implement the roll_file? and archive_file_suffix
+    # methods.
+    #
+    # The <tt>:keep</tt> option can be used to specify a maximum number of rolled log files to keep.
+    # Older files will be deleted based on the time they were created. The default is to keep all files.
+    class RollingLogFile < LogFile
+      attr_reader :path
+      attr_accessor :keep
+      
+      def initialize(path, options = {})
+        @path = File.expand_path(path)
+        @keep = options[:keep]
+        super(path, options)
+        @file_inode = stream.lstat.ino rescue nil
+      end
+      
+      # Returns a suffix that will be appended to the file name when it is archived.. The suffix should
+      # change after it is time to roll the file. The log file will be renamed when it is rolled.
+      def archive_file_suffix
+        raise NotImplementedError
+      end
+      
+      # Return +true+ if the file should be rolled.
+      def roll_file?
+        raise NotImplementedError
+      end
+      
+      protected
+      
+      # This method will be called after a file has been rolled. Subclasses can
+      # implement code to reset the state of the device. This method is thread safe.
+      def after_roll
+      end
+      
+      # Handle rolling the file before flushing.
+      def before_flush # :nodoc:
+        path_inode = File.lstat(path).ino rescue nil
+        if path_inode != @file_inode
+          @file_inode = path_inode
+          reopen_file
+        else
+          roll_file! if roll_file?
+        end
+      end
+
+      private
+
+      def reopen_file
+        old_stream = stream
+        self.stream = File.open(path, 'a')
+        stream.sync = true
+        @file_inode = stream.lstat.ino rescue nil
+        old_stream.close
+      end
+      
+      # Roll the log file by renaming it to the archive file name and then re-opening a stream to the log
+      # file path. Rolling a file is safe in multi-threaded or multi-process environments.
+      def roll_file! #:nodoc:
+        do_once(stream) do
+          archive_file = "#{path}.#{archive_file_suffix}"
+          stream.flush
+          current_inode = File.stat(path).ino rescue nil
+          if @file_inode && current_inode == @file_inode && !File.exist?(archive_file)
+            begin
+              File.rename(path, archive_file)
+              after_roll
+              cleanup_files!
+            rescue SystemCallError
+              # Ignore rename errors since it indicates the file was already rolled
+            end
+          end
+        end
+        reopen_file
+      rescue => e
+        STDERR.write("Failed to roll file #{path}: #{e.inspect}\n#{e.backtrace.join("\n")}\n")
+      end
+    end
+    
+    def cleanup_files!
+      if keep
+        files = Dir.glob("#{path}.*").collect{|f| [f, File.ctime(f)]}.sort{|a,b| b.last <=> a.last}.collect{|a| a.first}
+        if files.size > keep
+          files[keep, files.length].each do |f|
+            File.delete(f)
+          end
+        end
+      end
+    end
+    
+    def do_once(file)
+      begin
+        file.flock(File::LOCK_EX)
+      rescue SystemCallError
+        # Most likely can't lock file because the stream is closed
+        return
+      end
+      begin
+        verify = file.lstat rescue nil
+        # Execute only if the file we locked is still the same one that needed to be rolled
+        yield if verify && verify.ino == @file_inode && verify.size > 0
+      ensure
+        stream.flock(File::LOCK_UN) rescue nil
+      end
+    end
+  end
+end

data/lib/lumberjack/device/size_rolling_log_file.rb

@@ -0,0 +1,58 @@
+module Lumberjack
+  class Device
+    # This is a log device that appends entries to a file and rolls the file when it reaches a specified
+    # size threshold. When a file is rolled, it will have an number extension appended to the file name.
+    # For example, if the log file is named production.log, the first time it is rolled it will be renamed
+    # production.log.1, then production.log.2, etc.
+    class SizeRollingLogFile < RollingLogFile
+      attr_reader :max_size
+      
+      # Create an new log device to the specified file. The maximum size of the log file is specified with
+      # the <tt>:max_size</tt> option. The unit can also be specified: "32K", "100M", "2G" are all valid.
+      def initialize(path, options = {})
+        @max_size = options[:max_size]
+        if @max_size.is_a?(String)
+          if @max_size.match(/^(\d+(\.\d+)?)([KMG])?$/i)
+            @max_size = $~[1].to_f
+            units = $~[3].to_s.upcase
+            case units
+            when "K"
+              @max_size *= 1024
+            when "M"
+              @max_size *= 1024 ** 2
+            when "G"
+              @max_size *= 1024 ** 3
+            end
+            @max_size = @max_size.round
+          else
+            raise ArgumentError.new("illegal value for :max_size (#{@max_size})")
+          end
+        end
+        
+        super
+      end
+
+      def archive_file_suffix
+        next_archive_number.to_s
+      end
+
+      def roll_file?
+        stream.stat.size >= @max_size
+      end
+      
+      protected
+      
+      # Calculate the next archive file name extension.
+      def next_archive_number # :nodoc:
+        max = 0
+        Dir.glob("#{path}.*").each do |filename|
+          if filename.match(/\.\d+$/)
+            suffix = filename.split('.').last.to_i
+            max = suffix if suffix > max
+          end
+        end
+        max + 1
+      end
+    end
+  end
+end