lumberjack 1.0.0 → 1.0.1

data/README.rdoc

@@ -48,7 +48,7 @@ A unit of work can be used to tie together all log messages within a block. This
 
 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::Writer - 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.
@@ -77,7 +77,17 @@ If you use the built in devices, you can also customize the Template used to for
 
 === Buffered Performance
 
-The built in stream based logging devices use an internal buffer to increase performance by batching physical writes.
+The logger has hooks for devices that support buffering to increase performance by batching physical writes. Log entries are not guaranteed to be written until the Lumberjack::Logger#flush method is called.
+
+You can use the <tt>:flush_seconds</tt> option on the logger to periodically flush the log. This is usually a good idea so you can more easily debug hung processes. Without periodic flushing, a process that hangs may never write anything to the log because the messages are sitting in a buffer. By turning on periodic flushing, the logged messages will be written which can greatly aid in debugging the problem.
+
+The built in stream based logging devices use an internal buffer. The size of the buffer (in bytes) can be set with the <tt>:buffer_size</tt> options when initializing a logger. The default behavior is to not to buffer.
+
+  # Set buffer to flush after 8K has been written to the log.
+  logger = Lumberjack::Logger.new("application.log", :buffer_size => 8192)
+  
+  # Turn off buffering so entries are immediately written to disk.
+  logger = Lumberjack::Logger.new("application.log", :buffer_size => 0)
 
 === Automatic Log Rolling
 

data/Rakefile

@@ -1,7 +1,7 @@
 require 'rubygems'
 require 'rake'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
+require 'rubygems/package_task'
+require 'rdoc/task'
 
 desc 'Default: run unit tests.'
 task :default => :test
@@ -42,7 +42,7 @@ 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|
+  Gem::PackageTask.new(spec) do |p|
     p.gem_spec = spec
   end
   Rake.application["package"].prerequisites.unshift("rbx:delete_rbc_files")

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

data/lib/lumberjack/device/writer.rb

@@ -1,12 +1,13 @@
 module Lumberjack
   class Device
-    # This logging device writes log entries as strings to an IO stream.
+    # This logging device writes log entries as strings to an IO stream. By default, messages will be buffered
+    # and written to the stream in a batch when the buffer is full or when +flush+ is called.
     class Writer < Device
       DEFAULT_FIRST_LINE_TEMPLATE = "[:time :severity :progname(:pid) #:unit_of_work_id] :message".freeze
       DEFAULT_ADDITIONAL_LINES_TEMPLATE = "#{Lumberjack::LINE_SEPARATOR}> [#:unit_of_work_id] :message".freeze
 
       # The size of the internal buffer. Defaults to 32K.
-      attr_accessor :buffer_size
+      attr_reader :buffer_size
       
       # Internal buffer to batch writes to the stream.
       class Buffer # :nodoc:
@@ -49,12 +50,14 @@ module Lumberjack
       # The default template is <tt>"[:time :severity :progname(:pid) #:unit_of_work_id] :message"</tt>
       # with additional lines formatted as <tt>"\n [#:unit_of_work_id] :message"</tt>. The unit of
       # work id will only appear if it is present.
+      #
+      # The size of the internal buffer in bytes can be set by providing <tt>:buffer_size</tt> (defaults to 32K).
       def initialize(stream, options = {})
         @lock = Mutex.new
         @stream = stream
         @stream.sync = true if @stream.respond_to?(:sync=)
         @buffer = Buffer.new
-        @buffer_size = (options[:buffer_size] || 32 * 1024)
+        @buffer_size = (options[:buffer_size] || 0)
         template = (options[:template] || DEFAULT_FIRST_LINE_TEMPLATE)
         if template.respond_to?(:call)
           @template = template
@@ -64,6 +67,13 @@ module Lumberjack
         end
       end
       
+      # Set the buffer size in bytes. The device will only be physically written to when the buffer size
+      # is exceeded.
+      def buffer_size=(value)
+        @buffer_size = value
+        flush
+      end
+      
       # Write an entry to the stream. The entry will be converted into a string using the defined template.
       def write(entry)
         string = @template.call(entry)

data/lib/lumberjack/logger.rb

@@ -114,7 +114,7 @@ module Lumberjack
     
     alias_method :log, :add
     
-    # Flush the logging device.
+    # Flush the logging device. Messages are not guaranteed to be written until this method is called.
     def flush
       device.flush
       @last_flushed_at = Time.now

data/spec/device/rolling_log_file_spec.rb

@@ -13,7 +13,7 @@ describe Lumberjack::Device::RollingLogFile do
   let(:entry){ Lumberjack::LogEntry.new(Time.now, 1, "New log entry", nil, $$, nil) }
 
   it "should check for rolling the log file on flush" do
-    device = Lumberjack::Device::RollingLogFile.new(File.join(tmp_dir, "test.log"))
+    device = Lumberjack::Device::RollingLogFile.new(File.join(tmp_dir, "test.log"), :buffer_size => 32767)
     device.write(entry)
     device.should_receive(:roll_file?).twice.and_return(false)
     device.flush
@@ -22,7 +22,7 @@ describe Lumberjack::Device::RollingLogFile do
   
   it "should roll the file by archiving the existing file and opening a new stream and calling after_roll" do
     log_file = File.join(tmp_dir, "test_2.log")
-    device = Lumberjack::Device::RollingLogFile.new(log_file, :template => ":message")
+    device = Lumberjack::Device::RollingLogFile.new(log_file, :template => ":message", :buffer_size => 32767)
     device.should_receive(:roll_file?).and_return(false, true)
     device.should_receive(:after_roll)
     device.stub!(:archive_file_suffix).and_return("rolled")
@@ -59,7 +59,7 @@ describe Lumberjack::Device::RollingLogFile do
     
     process_count.times do
       Process.fork do
-        device = Lumberjack::Device::SizeRollingLogFile.new(log_file, :max_size => max_size, :template => ":message")
+        device = Lumberjack::Device::SizeRollingLogFile.new(log_file, :max_size => max_size, :template => ":message", :buffer_size => 32767)
         threads = []
         thread_count.times do
           threads << Thread.new do
@@ -95,7 +95,7 @@ describe Lumberjack::Device::RollingLogFile do
   
   it "should only keep a specified number of archived log files" do
     log_file = File.join(tmp_dir, "test_5.log")
-    device = Lumberjack::Device::RollingLogFile.new(log_file, :template => ":message", :keep => 2)
+    device = Lumberjack::Device::RollingLogFile.new(log_file, :template => ":message", :keep => 2, :buffer_size => 32767)
     device.should_receive(:roll_file?).and_return(false, true, true, true)
     device.stub!(:archive_file_suffix).and_return("delete", "another", "keep")
     t = Time.now

data/spec/device/writer_spec.rb

@@ -8,7 +8,7 @@ describe Lumberjack::Device::Writer do
   let(:entry){ Lumberjack::LogEntry.new(time, Lumberjack::Severity::INFO, "test message", "app", 12345, "ABCD") }
   
   it "should buffer output and not write directly to the stream" do
-    device = Lumberjack::Device::Writer.new(stream, :template => ":message")
+    device = Lumberjack::Device::Writer.new(stream, :template => ":message", :buffer_size => 32767)
     device.write(entry)
     stream.string.should == ""
     device.flush
@@ -34,7 +34,7 @@ describe Lumberjack::Device::Writer do
     def io.sync; @sync; end
     io.init
     
-    device = Lumberjack::Device::Writer.new(io, :template => ":message")
+    device = Lumberjack::Device::Writer.new(io, :template => ":message", :buffer_size => 32767)
     device.write(entry)
     io.string.should == ""
     device.flush
@@ -49,9 +49,9 @@ describe Lumberjack::Device::Writer do
     device.buffer_size.should == 100
   end
   
-  it "should have a default buffer size of 32K" do
+  it "should have a default buffer size of 0" do
     device = Lumberjack::Device::Writer.new(stream)
-    device.buffer_size.should == 32768
+    device.buffer_size.should == 0
   end
   
   it "should write entries out to the stream with a default template" do

data/spec/logger_spec.rb

@@ -173,7 +173,7 @@ describe Lumberjack::Logger do
   context "flushing" do
     it "should autoflush the buffer if it hasn't been flushed in a specified number of seconds" do
       output = StringIO.new
-      logger = Lumberjack::Logger.new(output, :flush_seconds => 0.1, :level => Lumberjack::Severity::INFO, :template => ":message")
+      logger = Lumberjack::Logger.new(output, :flush_seconds => 0.1, :level => Lumberjack::Severity::INFO, :template => ":message", :buffer_size => 32767)
       logger.info("message 1")
       logger.info("message 2")
       output.string.should == ""
@@ -187,7 +187,7 @@ describe Lumberjack::Logger do
     
     it "should write the log entries to the device on flush and update the last flushed time" do
       output = StringIO.new
-      logger = Lumberjack::Logger.new(output, :level => Lumberjack::Severity::INFO, :template => ":message")
+      logger = Lumberjack::Logger.new(output, :level => Lumberjack::Severity::INFO, :template => ":message", :buffer_size => 32767)
       logger.info("message 1")
       output.string.should == ""
       last_flushed_at = logger.last_flushed_at
@@ -198,7 +198,7 @@ describe Lumberjack::Logger do
     
     it "should flush the buffer and close the devices" do
       output = StringIO.new
-      logger = Lumberjack::Logger.new(output, :level => Lumberjack::Severity::INFO, :template => ":message")
+      logger = Lumberjack::Logger.new(output, :level => Lumberjack::Severity::INFO, :template => ":message", :buffer_size => 32767)
       logger.info("message 1")
       output.string.should == ""
       logger.close

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: lumberjack
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 1
   - 0
-  - 0
-  version: 1.0.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Brian Durand
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-11 00:00:00 -06:00
+date: 2011-06-23 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -120,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.0
+rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
 summary: A simple, powerful, and very fast logging utility that can be a drop in replacement for Logger or ActiveSupport::BufferedLogger.