catamaran 0.4.0 → 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ce160eae2640b8c7d690d9677b5440892b48dae1
+  data.tar.gz: 70e6fe894ef0216d45e5e0f837b94deb9a912b20
+SHA512:
+  metadata.gz: a4ce49087602bed11ca7f627291829af5561ec6b21b0c46a1f7effac2b2f59ec8c1e34ad18ecc5e83e973c76e08b47efca2077fd55f2fe6685b9c84ea8a3c8b7
+  data.tar.gz: 3e4a99d0e26290c1be952b84d3acdc7a4847885acc3192184133dd8cff07b269f036a82d137c29f5172fd49b3f94b24dbd1ae3656fd5a07a294af8ac1b41f127

data/README.md

@@ -1,18 +1,18 @@
 Catamaran
 =========
 
-I think logging is a powerful and often undervalued tool in software development.  When done right, it's a great way to document code, and it provides a simple & effective way to solve problems when things go awry.  All an important part of maintainable code.
+Logging is a powerful and often undervalued tool in software development.  When done right, it's a great way to document code, and it provides a simple & effective way to solve problems when things go awry.  All an important part of maintainable code.
 
 Gemfile
 -------
 
-    gem 'catamaran', '~> 0.3.0'
+    gem 'catamaran', '~> 0.4.0'
 
 Rails-related setup:
 
     rails g catamaran:install
 
-Now modify `development.rb` as needed
+Now modify `config/initializers/catamaran/development.rb` as needed
 
 Ruby Quickstart
 ---------------
@@ -63,7 +63,7 @@ Load the `index` page and check out your `development.log` file
 Other Ruby Examples
 -------------------
     require 'catamaran'
-    
+
     Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::DEBUG 
     Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
 
@@ -107,11 +107,14 @@ I'm looking for a logging utility that:
 
 Performance Considerations
 --------------------------
+
+### With or without `if LOGGER.debug?`
     require 'catamaran'
     require 'benchmark'
 
     Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::INFO 
     Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
+    Catamaran::Manager.stderr = false
 
     class CatamaranPerformanceTest
       LOGGER = Catamaran.logger( "CatamaranPerformanceTest" )
@@ -123,12 +126,12 @@ Performance Considerations
       Benchmark.bm(7) do |x|
         x.report("warn WITHOUT if LOGGER.warn?  ") {
           n.times do |i|
-            LOGGER.warn "This is a WARN"
+            LOGGER.warn "Based on the current log level, this log is being captured"
           end
         }
         x.report("warn WITH if LOGGER.warn?     ") {
           n.times do |i|
-            LOGGER.warn "This is a WARN" if LOGGER.warn?
+            LOGGER.warn "Based on the current log level, this log is being captured" if LOGGER.warn?
           end
         }
       end
@@ -136,26 +139,91 @@ Performance Considerations
       Benchmark.bm(7) do |x|
         x.report("debug WITHOUT if LOGGER.debug?") {
           n.times do |i|
-            LOGGER.debug "This is a DEBUG"
+            LOGGER.debug "Based on the current log level, this log is NOT being captured"
           end
         }
         x.report("debug WITH if LOGGER.debug?   ") {
           n.times do |i|
-            LOGGER.debug "This is a DEBUG" if LOGGER.debug?       
+            LOGGER.debug "Based on the current log level, this log is NOT being captured" if LOGGER.debug?       
           end
         }
       end 
 
     end
 
-
     #                                     user     system      total        real
-    # warn WITHOUT if LOGGER.warn?    6.520000   0.020000   6.540000 (  6.533741)
-    # warn WITH if LOGGER.warn?       7.110000   0.020000   7.130000 (  7.129708)
+    # warn WITHOUT if LOGGER.warn?    6.940000   0.010000   6.950000 (  6.950691)
+    # warn WITH if LOGGER.warn?       7.650000   0.000000   7.650000 (  7.658004)
     #                                     user     system      total        real
-    # debug WITHOUT if LOGGER.debug?  0.610000   0.010000   0.620000 (  0.623714)
-    # debug WITH if LOGGER.debug?     0.530000   0.010000   0.540000 (  0.544295)
+    # debug WITHOUT if LOGGER.debug?  0.660000   0.010000   0.670000 (  0.665775)
+    # debug WITH if LOGGER.debug?     0.560000   0.010000   0.570000 (  0.574397)
+
+#### Summary
+
+* For log messages that are usually *disabled* in the production environment ( TRACE, DEBUG ), it's generally better to invoke the log only after confirming that the log level is enabled 
+
+ex:
+
+    LOGGER.trace "This is a TRACE log" if LOGGER.trace?
+    LOGGER.debug "This is a DEBUG log" if LOGGER.debug?
+
+* For log messages that are usually *enabled* in the production environment ( INFO, WARN, ERROR, SEVERE ), it's generally better to invoke the log WITHOUT first testing the log level
+
+ex:
+
+    LOGGER.info "This is a INFO log"
+    LOGGER.warn "This is a WARN log"
+    LOGGER.error "This is a ERROR log" 
+
+### NoCallerFormatter vs CallerFormatter
+
+    require 'catamaran'
+    require 'benchmark'
+
+    Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::INFO 
+    Catamaran::Manager.stderr = false
+
+    class CatamaranPerformanceTest
+      LOGGER = Catamaran.logger( "CatamaranPerformanceTest" )
+
+      n = 500000
+      Benchmark.bm(7) do |x|
+        Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
+        
+        x.report("Using NoCallerFormatter") {
+          n.times do |i|
+            LOGGER.error "This is a ERROR log"
+          end
+        }   
+        
+        Catamaran::Manager.formatter_class = Catamaran::Formatter::CallerFormatter
+        
+        x.report("Using CallerFormatter") {
+          n.times do |i|
+            LOGGER.error "This is a ERROR log"
+          end
+        }
+      end
+    end
+                             
+
+    #                              user     system      total        real
+    # Using NoCallerFormatter  6.850000   0.010000   6.860000 (  6.864649)
+    # Using CallerFormatter   14.700000   0.150000  14.850000 ( 14.867592)
+
+#### Summary
+
+`CallerFormatter` is slower but contains more details in the log statements as compared to `NoCallerFormatter`
+
+##### Sample log from NoCallerFormatter
+
+    WARN pid-4407 [2013-12-26 14:18:19:697]                                   FirstRubyDemo - Note that WARN messages are getting logged
+
+##### Sample log from CallerFormatter
+
+    WARN pid-4410 [2013-12-26 14:18:38:276]                                   FirstRubyDemo - Note that WARN messages are getting logged (catamaran_ruby_demos.rb:12:in `run')
 
+Because of this performance difference, `NoCallerFormatter` is the Catamaran default.  Though `CallerFormatter` tends to be especially useful in the development and test environments when debugging problems during the course of functional testing.
 
 
 Ideas around what's next

data/lib/catamaran/logger.rb

@@ -297,11 +297,66 @@ module Catamaran
       retval
     end
 
-    def reset
-      _reset()
-      Catamaran.debugging( "Catamaran::Logger#reset() - Reset complete." )  if Catamaran.debugging?
+
+    ##
+    # I used to delete the root level logger, but now I reset it instead.  
+    # Among other reasons, the CatLogger constant now works
+
+    def reset( opts = {} )
+      remove_instance_variable(:@memoized_log_level) if instance_variable_defined?( :@memoized_log_level )      
+      remove_instance_variable(:@log_level) if instance_variable_defined?( :@log_level )      
+
+      self.name = @initialized_name
+      self.path = @initialized_path_so_far ? @initialized_path_so_far.dup : []
+
+      if @initialized_name && @initialized_name.length > 0  # Root logger has no name
+        self.path << @initialized_name
+      end
+
+      @parent = @initialized_parent
+
+
+
+      if opts[:hard_reset]
+        ##
+        # Hard reset - delete the sub-loggers by removing references to them
+
+        # @sub_loggers already exist, iterate through each and undefine the associated method missing
+        @sub_loggers.keys.each do |method_name_as_symbol|
+          Catamaran.debugging( "Catamaran::Logger#reset() - Attempting to remove dynamically created method: #{method_name_as_symbol}" )  if Catamaran.debugging?
+          singleton = class << self; self end
+          singleton.send :remove_method, method_name_as_symbol 
+        end if @sub_loggers
+
+        @sub_loggers = {}
+        Catamaran.debugging( "Catamaran::Logger#reset() - Hard reset complete for #{self}." )  if Catamaran.debugging?
+      else
+        ##
+        # Soft reset - reset each of the sub-loggers
+
+        # @sub_loggers already exist, iterate through each and reset them
+        @sub_loggers.values.each do |logger|
+          logger.reset()
+        end if @sub_loggers
+        Catamaran.debugging( "Catamaran::Logger#reset() - Soft reset complete for #{self}." )  if Catamaran.debugging?        
+      end
+    end
+
+    def soft_reset( opts = {} )
+      # This is a soft reset 
+      opts = opts.dup
+      opts[:hard_reset] = false      
+      reset( opts )
     end
 
+    def hard_reset( opts = {} )
+      # This is a hard reset 
+      opts = opts.dup
+      opts[:hard_reset] = true
+      reset( opts )
+    end
+
+
     def depth 
       @depth
     end
@@ -345,35 +400,6 @@ module Catamaran
 
     private
 
-    ##
-    # I used to delete the root level logger, but now I reset it instead.  
-    # Among other reasons, the CatLogger constant now works
-
-    def _reset
-      remove_instance_variable(:@memoized_log_level) if instance_variable_defined?( :@memoized_log_level )      
-      remove_instance_variable(:@log_level) if instance_variable_defined?( :@log_level )      
-
-      self.name = @initialized_name
-      self.path = @initialized_path_so_far ? @initialized_path_so_far.dup : []
-
-      if @initialized_name && @initialized_name.length > 0  # Root logger has no name
-        self.path << @initialized_name
-      end
-
-      @parent = @initialized_parent
-
-      # @sub_loggers already exist, iterate through each and undefine the associated method missing
-      if @sub_loggers
-        @sub_loggers.keys.each do |method_name_as_symbol|
-          Catamaran.debugging( "Catamaran::Logger#_reset() - Attempting to remove dynamically created method: #{method_name_as_symbol}" )  if Catamaran.debugging?
-
-          singleton = class << self; self end
-          singleton.send :remove_method, method_name_as_symbol 
-        end
-      end
-
-      @sub_loggers = {}
-    end
 
     ##
     # All log statements eventually call _write_to_log
@@ -405,7 +431,10 @@ module Catamaran
         @depth = 0
       end
 
-      _reset()
+      # Create the hash of sub_loggers as needed
+      @sub_loggers ||= {}
+
+      reset()
 
       Catamaran.debugging( "Catamaran::Logger#initialize() - I am #{self.to_s}" )  if Catamaran.debugging?
     end

data/lib/catamaran/manager.rb

@@ -37,15 +37,15 @@ module Catamaran
     ##
     # Used to reset Catamaran
 
-    def self.reset
-      Catamaran.debugging( "Catamaran::Manager#reset - Resetting Catamaran" ) if Catamaran.debugging?                  
+    def self.reset( opts = {} )
+      Catamaran.debugging( "Catamaran::Manager#reset - Resetting Catamaran with opts = #{opts}" ) if Catamaran.debugging?                  
 
       # Old way.   I used to null-out the old logger.   But resetting it is better for using the CatLogger constant
       # self.send( :_root_logger_instance=, nil )
 
       # New way
       root_logger = self.send( :_root_logger_instance )
-      root_logger.reset if root_logger
+      root_logger.reset( opts ) if root_logger
 
       # Also reset the default log level
       Catamaran::LogLevel::reset
@@ -56,6 +56,15 @@ module Catamaran
       # self.send( :_output_files=, nil )
     end
 
+    def self.hard_reset( opts = {} )
+      opts = opts.dup
+      opts[:hard_reset] = true      
+      self.reset( opts )
+    end
+
+
+
+
     ##
     # Allow the client to access the root logger
 

data/lib/catamaran/version.rb

@@ -1,4 +1,4 @@
 module Catamaran
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end
 

data/spec/catamaran_spec.rb

@@ -39,8 +39,9 @@ describe Catamaran do
   it "should provide access to loggers after a reset" do
     logger = Catamaran.logger.Company.Product.App.Model.User
     Catamaran::Manager.reset
-    logger = Catamaran.logger.Company.Product.App.Model.User
-    logger.should be_instance_of( Catamaran::Logger )
+    logger2 = Catamaran.logger.Company.Product.App.Model.User
+    logger2.should be_instance_of( Catamaran::Logger )
+    logger2.object_id.should == logger.object_id
   end
 
   it "should create a new loggers for each point in the path" do
@@ -92,7 +93,7 @@ describe Catamaran do
     Catamaran.logger.Company.Product.App.Model.User
   end
 
-  context "after a reset" do
+  context "after a (soft) reset" do
     it "should have a default log level of INFO" do
       logger = Catamaran.logger
       logger.log_level.should == Catamaran::LogLevel::INFO
@@ -102,13 +103,13 @@ describe Catamaran do
       logger.log_level.should == Catamaran::LogLevel::INFO      
     end
 
-    it "should return the number of loggers to 1" do
+    it "should keep the number of loggers unchanged" do
       Catamaran.logger
       Catamaran::Manager.num_loggers.should == 1
       Catamaran.logger.Company.Product.App.Model.User
       Catamaran::Manager.num_loggers.should == 6 
       Catamaran::Manager.reset
-      Catamaran::Manager.num_loggers.should == 1      
+      Catamaran::Manager.num_loggers.should == 6      
     end
 
     it "should have the same root logger object before and after the reset" do
@@ -116,6 +117,44 @@ describe Catamaran do
       Catamaran::Manager.reset
       Catamaran.logger.object_id.should == before_logger.object_id        
     end
+
+    it "should reuse the same logger non-root logger instance" do
+      before_logger = Catamaran.logger.Company.Product.App.Model.User
+      Catamaran::Manager.reset
+      before_logger.object_id.should == Catamaran.logger.Company.Product.App.Model.User.object_id   
+    end      
+  end
+
+  context "after a hard reset" do
+    it "should have a default log level of INFO" do
+      logger = Catamaran.logger
+      logger.log_level.should == Catamaran::LogLevel::INFO
+      logger.log_level = Catamaran::LogLevel::ERROR
+      logger.log_level.should == Catamaran::LogLevel::ERROR
+      Catamaran::Manager.hard_reset
+      logger.log_level.should == Catamaran::LogLevel::INFO      
+    end
+
+    it "should reset the number of loggers to 1" do
+      Catamaran.logger
+      Catamaran::Manager.num_loggers.should == 1
+      Catamaran.logger.Company.Product.App.Model.User
+      Catamaran::Manager.num_loggers.should == 6 
+      Catamaran::Manager.hard_reset
+      Catamaran::Manager.num_loggers.should == 1      
+    end
+
+    it "should have the same root logger object before and after the reset" do
+      before_logger = Catamaran.logger
+      Catamaran::Manager.hard_reset
+      Catamaran.logger.object_id.should == before_logger.object_id        
+    end
+
+    it "should NOT reuse the same non-root logger instance" do
+      before_logger = Catamaran.logger.Company.Product.App.Model.User
+      Catamaran::Manager.hard_reset
+      before_logger.object_id.should_not == Catamaran.logger.Company.Product.App.Model.User.object_id   
+    end     
   end
 
   describe Catamaran.logger do
@@ -127,13 +166,10 @@ describe Catamaran do
 
   describe Catamaran::Manager do
     describe "#reset" do
-      it "should reset Catamaran" do
-        before_reset_logger = Catamaran.logger.Company.Product.App.Model.User
-        Catamaran.logger.num_loggers.should == 6
+      it "should call reset on the root logger" do
+        root_logger = Catamaran.logger
+        root_logger.should_receive( :reset ).once
         Catamaran::Manager.reset
-        Catamaran.logger.num_loggers.should == 1
-        after_reset_logger = Catamaran.logger.Company.Product.App.Model.User
-        before_reset_logger.object_id.should_not == after_reset_logger.object_id        
       end
     end
 

data/spec/spec_helper.rb

@@ -5,6 +5,6 @@ RSpec.configure do |config|
   end
  
   config.before(:each) do
-    Catamaran::Manager.reset
+    Catamaran::Manager.hard_reset
   end
 end

metadata

@@ -1,28 +1,22 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: catamaran
-version: !ruby/object:Gem::Version 
-  version: 0.4.0
+version: !ruby/object:Gem::Version
+  version: 0.5.0
 platform: ruby
-authors: 
+authors:
 - Jeano
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2013-12-26 00:00:00 -06:00
-default_executable: 
+date: 2013-12-26 00:00:00.000000000 Z
 dependencies: []
-
 description: A logging utility
-email: 
+email:
 - catamaran@jeano.net
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - README.md
 - catamaran.gemspec
@@ -46,33 +40,27 @@ files:
 - lib/generators/catamaran/templates/catamaran/test.rb
 - spec/catamaran_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: http://github.com/jgithub/catamaran
 licenses: []
-
+metadata: {}
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
+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: 1.3.5
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Catamaran Logger
 test_files: []
-