catamaran 0.3.0 → 0.4.0

data/README.md

@@ -6,7 +6,7 @@ I think logging is a powerful and often undervalued tool in software development
 Gemfile
 -------
 
-    gem 'catamaran', '~> 0.2.0'
+    gem 'catamaran', '~> 0.3.0'
 
 Rails-related setup:
 
@@ -15,52 +15,27 @@ Rails-related setup:
 Now modify `development.rb` as needed
 
 Ruby Quickstart
--------------------------------
-    Catamaran::Manager.stderr = true
-    Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::DEBUG 
-    Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
+---------------
+    require 'catamaran'
 
     class FirstRubyDemo
       LOGGER = Catamaran.logger( "FirstRubyDemo" )
 
       def run
-        LOGGER.debug( "Note that DEBUG messages are getting logged" ) if LOGGER.debug?
+        LOGGER.warn( "Note that WARN messages are getting logged" ) if LOGGER.warn?
         LOGGER.trace( "Note that TRACE messages are NOT getting logged" ) if LOGGER.trace?
       end
     end
 
-    class SecondRubyDemo
-      LOGGER = Catamaran.logger( { :class => name(), :file => __FILE__ } )
-
-      def run
-        LOGGER.debug( "Sample DEBUG statement", { :line => __LINE__, :method => 'run'} ) if LOGGER.debug?
-      end
-    end 
-
-    class ThirdRubyDemo
-      LOGGER = Catamaran.logger( "com.mycompany.ThirdRubyDemo", { :class => name(), :file => __FILE__ } )
-
-      def run
-        LOGGER.debug( "Sample DEBUG statement", { :line => __LINE__, :method => 'run'} ) if LOGGER.debug?
-      end
-    end   
-
-
-    puts "Catamaran VERSION = #{Catamaran::VERSION}"
     FirstRubyDemo.new.run
-    SecondRubyDemo.new.run
-    ThirdRubyDemo.new.run
 
 And the output
 
-     Catamaran VERSION = 0.3.0
-     DEBUG pid-2729 [2013-12-23 19:35:35:732]                                   FirstRubyDemo - Note that DEBUG messages are getting logged
-     DEBUG pid-2729 [2013-12-23 19:35:35:732]                                                 - Sample DEBUG statement (catmaran_ruby_demos.rb:21:in `SecondRubyDemo.run')
-     DEBUG pid-2729 [2013-12-23 19:35:35:732]                     com.mycompany.ThirdRubyDemo - Sample DEBUG statement (catmaran_ruby_demos.rb:29:in `ThirdRubyDemo.run')
+     WARN pid-2729 [2013-12-23 19:35:35:732]                                   FirstRubyDemo - Note that WARN messages are getting logged
 
 
 Rails Quickstart
---------------------------------
+----------------
 
     class PagesController < ApplicationController
       LOGGER = Catamaran.logger.com.mycompany.myrailsapp.app.controllers.PagesController
@@ -85,6 +60,37 @@ Load the `index` page and check out your `development.log` file
     IO pid-86000 [2013-12-17 17:26:39:176] pany.myrailsapp.app.controllers.PagesController - Entering with params = {"controller"=>"pages", "action"=>"index"} (`/myrailsapp/app/controllers/pages_controller.rb:7`:in `index`)
 
 
+Other Ruby Examples
+-------------------
+    require 'catamaran'
+    
+    Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::DEBUG 
+    Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
+
+    class SecondRubyDemo
+      LOGGER = Catamaran.logger( { :class => name(), :file => __FILE__ } )
+
+      def run
+        LOGGER.debug( "Sample DEBUG statement", { :line => __LINE__, :method => 'run'} ) if LOGGER.debug?
+      end
+    end 
+
+    class ThirdRubyDemo
+      LOGGER = Catamaran.logger( "com.mycompany.ThirdRubyDemo", { :class => name(), :file => __FILE__ } )
+
+      def run
+        LOGGER.debug( "Sample DEBUG statement", { :line => __LINE__, :method => 'run'} ) if LOGGER.debug?
+      end
+    end   
+
+    SecondRubyDemo.new.run
+    ThirdRubyDemo.new.run
+
+And the output
+
+     DEBUG pid-2729 [2013-12-23 19:35:35:732]                                                 - Sample DEBUG statement (catamaran_ruby_demos.rb:21:in `SecondRubyDemo.run')
+     DEBUG pid-2729 [2013-12-23 19:35:35:732]                     com.mycompany.ThirdRubyDemo - Sample DEBUG statement (catamaran_ruby_demos.rb:29:in `ThirdRubyDemo.run')
+
 
 Inspiration
 -----------
@@ -98,6 +104,60 @@ I'm looking for a logging utility that:
 * is capable of capturing logs at different log level thresholds from different parts of the app simultaneously
 * readily works with Rails
 
+
+Performance Considerations
+--------------------------
+    require 'catamaran'
+    require 'benchmark'
+
+    Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::INFO 
+    Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
+
+    class CatamaranPerformanceTest
+      LOGGER = Catamaran.logger( "CatamaranPerformanceTest" )
+
+      # NOTE that the log level for this test is set to INFO, 
+      # so 'warn' logs are enabled and 'debug' logs are disabled
+
+      n = 500000
+      Benchmark.bm(7) do |x|
+        x.report("warn WITHOUT if LOGGER.warn?  ") {
+          n.times do |i|
+            LOGGER.warn "This is a WARN"
+          end
+        }
+        x.report("warn WITH if LOGGER.warn?     ") {
+          n.times do |i|
+            LOGGER.warn "This is a WARN" if LOGGER.warn?
+          end
+        }
+      end
+
+      Benchmark.bm(7) do |x|
+        x.report("debug WITHOUT if LOGGER.debug?") {
+          n.times do |i|
+            LOGGER.debug "This is a DEBUG"
+          end
+        }
+        x.report("debug WITH if LOGGER.debug?   ") {
+          n.times do |i|
+            LOGGER.debug "This is a DEBUG" 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)
+    #                                     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)
+
+
+
 Ideas around what's next
 ------------------------
 

data/lib/catamaran/log_level.rb

@@ -1,13 +1,5 @@
 module Catamaran
   class LogLevel
-    TRACE = 1000 
-    DEBUG = 2000
-    INFO = 3000
-    WARN = 4000
-    ERROR = 5000
-    SEVERE = 6000
-    FATAL = 7000
-
     # By default, logger.io messages will be captured when the log level is DEBUG (IO_LESS_CRITICAL_THAN_INFO)
     # If that's too verbose, the level can be changed to IO_LESS_CRITICAL_THAN_DEBUG and logger.io messages won't be
     # visible unless the log level is set to TRACE.  
@@ -15,8 +7,18 @@ module Catamaran
     IO_LESS_CRITICAL_THAN_DEBUG = 1080
     IO_LESS_CRITICAL_THAN_INFO = 2080
 
+
+    TRACE = 1000 
+    DEBUG = 2000
+    INFO = 3000
+    WARN = 4000
+    ERROR = 5000
+    SEVERE = 6000
+    FATAL = 7000
     IO = IO_LESS_CRITICAL_THAN_INFO
 
+    
+
     def self.reset
       @@default_log_level = INFO
 

data/lib/catamaran/version.rb

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

data/lib/catamaran.rb

@@ -46,7 +46,10 @@ end
 # add rails integration
 require('catamaran/integration/rails') if defined?(Rails)
 
-# Catamaran::Manager.stderr = true
+# By default, Catamaran should write messages to STDERR (in addition to anywhere else configured)
+Catamaran::Manager.stderr = true
+
+# By default, Catamaran will not write message to STDOUT
 # Catamaran::Manager.stdout = false
 
 ##

data/lib/generators/catamaran/templates/catamaran/development.rb

@@ -13,3 +13,15 @@ Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::DEBUG
 
 # The NoCallerFormatter is the default.  
 Catamaran::Manager.formatter_class = Catamaran::Formatter::CallerFormatter
+
+# Uncomment to enable Catamaran internal debugging
+# Catamaran::debugging = true
+
+##
+# Detailed log levels
+
+# Uncomment to set the default log level for all models to be TRACE
+# Catamaran.logger.com.mycompany.myrailsapp.app.models = Catamaran::LogLevel::TRACE
+
+# Uncomment to set the default log level for all controllers to be WARN
+# Catamaran.logger.com.mycompany.myrailsapp.app.controllers = Catamaran::LogLevel::WARN

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: catamaran
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Jeano
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-12-23 00:00:00 -06:00
+date: 2013-12-26 00:00:00 -06:00
 default_executable: 
 dependencies: []