loggr 1.0.0 → 1.1.0

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
+*.rbc
 .bundle
-Gemfile.lock
+*.lock
 pkg/*
 *.log

data/.travis.yml

@@ -0,0 +1,12 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby
+  - rbx
+  - rbx-2.0
+  - ree
+
+notifications:
+  recipients:
+    - lukas@at-point.ch

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "activesupport-3.0.x" do
+  gem 'activesupport', '~> 3.0.9'
+end
+
+appraise "activesupport-3.1" do
+  gem 'activesupport', '~> 3.1.0'
+end
+
+appraise "activesupport-head" do
+  gem 'activesupport', :path => '../../rails/activesupport/'
+end

data/README.md

@@ -5,7 +5,7 @@ Loggr provides a factory for creating logger instances. It:
 
 - Provides a wrapper for SLF4J (on JRuby)
 - Has adapters for Stdlib Logger and ActiveSupport::BufferedLogger
-- Supports Rails
+- Supports Rails, including the new `tagged` method
 - Handles using a Mapped Diagnostic Context (MDC)
 
 **So, why should I use a logger factory instead of just `Logger.new('out.log')`
@@ -16,11 +16,6 @@ trying to take advante of SLF4J-only features like the MDC or markers.
 Information
 -----------
 
-**Wiki** The Loggr Wiki will hopefully soon be filled with how-to articles and
-frequently asked questions.
-
-https://github.com/at-point/loggr/wiki
-
 **Bug Reports** No software is without bugs, if you discover a problem please report the issue.
 
 https://github.com/at-point/loggr/issues
@@ -29,17 +24,21 @@ https://github.com/at-point/loggr/issues
 
 http://rubydoc.info/github/at-point/loggr/master/frames
 
+**Gem** The latest stable gem is always on rubygems.org.
+
+http://rubygems.org/gems/loggr
+
 Installation
 ------------
 
 Like any gem, just add it to the Gemfile:
 
     # stable version
-    gem 'loggr', '~> 1.0.0'
-    
+    gem 'loggr', '~> 1.1.0'
+
     # latest development version
     gem 'loggr', :git => 'git://github.com/at-point/loggr.git'
-    
+
 Getting started
 ===============
 
@@ -58,7 +57,7 @@ Once an adapter has been specified new logger instances can be easily created us
     def logger
       @logger ||= LoggerFactory.logger 'my.app.SomeClass', :marker => "WORKER"
     end
-    
+
 The adapter then handles creating new logger instances and uses features like the ability
 to set markers (if supported), or setting a logger name. Based on the adapter a new logger
 will be returned with all things defined like the marker, or a custom logger name - if the
@@ -76,33 +75,33 @@ defines how logger instances are really created.
     LoggerFactory.logger 'app'                      # create a logger with named app
     LoggerFactory.logger 'app', :to => 'debug.out'  # write to debug.out
     LoggerFactory.logger 'app', :to => $stderr      # write to stderr
-    
+
 **Note:** not all adapters support all options, so some adapters might just ignore certain
 options, but this is intended :)
 
 ### Bundled Adapters
 
-**<code>LoggerFactory.adapter = :base</code>**
+**LoggerFactory.adapter = :base**
 
 The base adapter creates ruby stdlib `Logger` instances. Supported options for
 `LoggerFactory.logger(name, options = {})` are:
 
 - `:to`, String or IO, where to log should be written to (default: `"#{name}.log"`)
-- `:level`, Fixnum, one of `Logger::Severity`, the minimum severity to log (default: `Logger::Severity::DEBUG`)
+- `:level`, Fixnum, one of `Logger::Severity`, the minimum severity to log (default: `Logger::Severity::INFO`)
 
-**<code>LoggerFactory.adapter = :buffered</code>**
+**LoggerFactory.adapter = :buffered**
 
 Creates `ActiveSupport::BufferedLogger` instances and supports the same options
 as the `:base` adapter.
 
-**<code>LoggerFactory.adapter = :rails</code>**
+**LoggerFactory.adapter = :rails**
 
 This adapter alwasy returns the `Rails.logger`, which is very useful e.g. in development
 environments or testing, where we just care that it's somewhere in our `logs/development.log`.
 *Note:* Rails is automatically detected and the rails adapter is the default adapter when
 `::Rails` is present - else the base adapter is the default.
 
-**<code>LoggerFactory.adapter = :slf4j</code>**
+**LoggerFactory.adapter = :slf4j**
 
 SLF4J only works with JRuby (because it's Java) and you are responsible for a) having an
 SLF4J implementation on the classpath and it's configuration. Furthermore slf4j supports
@@ -112,38 +111,42 @@ these options for `LoggerFactory.logger(name, options = {})`:
 
 ### Using the Mapped Diagnostic Context (MDC)
 
-Some loggers provide a MDC (or mapped diagnostic context), which can be used to annotate
-log outputs with additional bits of information. At the moment only SLF4J really can make
+Some loggers provide a MDC (or mapped diagnostic context) or a similar feature like
+ActiveSupport 3.2s `TaggedLogging#tagged` which can be used to annotate log outputs with
+additional bits of information. At the moment only SLF4J and ActiveSupport 3.2 can make
 use of this. Though, to provide a clean and consistent API all adapters _must_ provide
-access to an MDC, so the MDC can be used in code no matter the adapter, a sample use case
-(in Rails):
+access to an MDC and each logger _must_ respond to both `tagged` and `mapped`, so these
+features can be used in code no matter the adapter.
+
+A sample use case:
 
     # app/controllers/application_controller.rb
     class ApplicationController < ActionController::Base
       around_filter :push_ip_to_mdc
-      
-      private        
+      def logger; @logger ||= LoggerFactory.logger('sample') end
+
+      private
         def push_ip_to_mdc
-          LoggerFactory.mdc[:ip] = request.ip
-          yield
-        ensure
-          LoggerFactory.mdc.delete(:ip)
+          logger.mapped(:ip => request.ip) do
+            yield
+          end
         end
     end
-    
+
 When using SLF4J all statements would now be annotated with the IP from where the request
-was made from.
+was made from, when using Rails 3.2 it would use it's support for `tagged` and add a tag
+named `ip=....`.
 
-The _SLF4J_ Wrapper
-===================
+The SLF4J Wrapper
+=================
 
 Apart from the logger factory, this gem provides a ruby wrapper for logging using SLF4J and
 taking advantage of:
 
-- Same API as exposed by Stdlib Logger or AS::BufferedLogger
+- Same API as exposed by Stdlib Logger, AS::BufferedLogger and AS::TaggedLogging
 - SLF4J markers
 - The Mapped Diagnostic Context (MDC)
-- Access to SLF4J & Logback implementation JARs 
+- Access to SLF4J & Logback implementation JARs
 
 The Logger
 ----------
@@ -152,21 +155,21 @@ Creating a new logger is as simple as creating instances of `Loggr::SLF4J::Logge
 
     # logger named "my.package.App"
     @logger = Loggr::SLF4J::Logger.new 'my.package.App'
-    
+
     # logger named "some.sample.Application" => classes are converted to java notation
     @logger = Loggr::SLF4J::Logger.new Some::Sample::Application
-    
+
     # logger with a default marker named "APP"
     @logger = Loggr::SLF4J::Logger.new 'my.package.App', :marker => 'APP'
-    
+
 Logging events is like using Stdlib Logger:
 
     # log with level INFO
     @logger.info "some info message"
-    
+
     # log with level DEBUG, if enabled
     @logger.debug "verbose information" if @logger.debug?
-    
+
     # log with level DEBUG and marker "QUEUE" (masking as progname)
     @logger.debug "do something", "QUEUE"
 
@@ -187,21 +190,42 @@ It's a good practice to wrap MDC set/get into begin/ensure blocks to ensure the
 is cleared afterwards, even in case of errors. The user is responsible for getting rid
 of these values. To just clear all values use `Loggr::SLF4J::MDC.clear`
 
+Tagging and mapping
+-------------------
+
+As an alternative to using the MDC directly, each logger exposes a method which is more
+ruby-like than setting the MDC and having to handle the `ensure` all by itself.
+
+    logger.mapped(:user => username) do
+      do_some_stuff
+    end
+
+This ensures that the key is cleared at the end, these calls can also be easily nested.
+Starting with ActiveSupport 3.2 there's support for `TaggedLogging`, SLF4J mimics this
+behaviour by using the mapped diagnostic context:
+
+    logger.tagged("some", "values") do
+      do_some_stuff
+    end
+
+Within the block the MDC has been assigned `some, values` to the key `:tags`. Nested values
+are just appended to this key.
+
 Extending & Contributing
 ========================
 
 Of course any custom adapters (e.g. for log4r or the logging gem) are greatly appreciated.
 To write a custom adapter just do something like:
 
-    class MyModule::MyCustomAdapter < Loggr::Adpater::AbstractAdapter    
+    class MyModule::MyCustomAdapter < Loggr::Adpater::AbstractAdapter
       def logger(name, options = {})
         # build logger instances and return it
-      end      
+      end
     end
-    
+
     # use custom adapter
     LoggerFactory.adapter = MyModule::MyCustomAdapter.new
-    
+
 Extending from `Loggr::Adapter::AbstractAdapter` provides the adapter with a default
 MDC implementation (backed by a hash stored in a thread local).
 
@@ -210,7 +234,7 @@ and the logger and mdc returned adhere to the API.
 
     class MyModule::MyCustomAdapterTest < Test::Unit::TestCase
        include Loggr::Lint::Tests
-       
+
        def setup
          # required, so the Lint Tests can pick it up
          @adapter = MyModule::MyCustomAdapter.new

data/Rakefile

@@ -1,11 +1,13 @@
+require 'rubygems'
 require 'bundler'
+require 'appraisal'
 require 'rake/testtask'
 
-# to fix warnings
-include Rake::DSL
-
 Bundler::GemHelper.install_tasks
 
+desc 'Default: run unit tests.'
+task :default => :test
+
 desc 'Test the loggr gem.'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'

data/gemfiles/activesupport-3.0.x.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "http://rubygems.org"
+
+gem "activesupport", "~> 3.0.9"
+
+gemspec :path=>"../"

data/gemfiles/activesupport-3.1.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "http://rubygems.org"
+
+gem "activesupport", "~> 3.1.0"
+
+gemspec :path=>"../"

data/gemfiles/activesupport-head.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "http://rubygems.org"
+
+gem "activesupport", :path=>"../../rails/activesupport/"
+
+gemspec :path=>"../"

data/lib/loggr.rb

@@ -8,10 +8,10 @@
 # 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
@@ -22,16 +22,16 @@
 #++
 
 module Loggr
-  autoload :Adapter,  'loggr/adapter'  
+  autoload :Adapter,  'loggr/adapter'
   autoload :Severity, 'loggr/severity'
   autoload :Lint,     'loggr/lint'
-  
+
   autoload :SLF4J,    'loggr/slf4j'
-  
-  autoload :VERSION,  'loggr/version'
-  
+
+  autoload :GEM_VERSION,  'loggr/version'
+
   # Ensure we've got the Log Levels covered
-  include Loggr::Severity  
+  include Loggr::Severity
 end
 
 # Autoloading the factory into the root.

data/lib/loggr/adapter.rb

@@ -85,7 +85,8 @@ module Loggr
       # Try to get adapter class from Symbol, String or use Object as-is.
       #
       def get_adapter(adp)
-        adp = Loggr::Adapter::SLF4J if adp == :slf4j # okay, this is only because we can't camelize it :)
+        # okay, this is only because we can't camelize it :)
+        adp = Loggr::Adapter::NOP if !adp
         
         # Code adapter from ActiveSupport::Inflector#camelize
         # https://github.com/rails/rails/blob/v3.0.9/activesupport/lib/active_support/inflector/methods.rb#L30
@@ -94,7 +95,7 @@ module Loggr
         clazz = adp
         
         if adp.respond_to?(:to_str)
-          const = begin Loggr::Adapter.const_get(adp.to_s) rescue nil end
+          const = begin Loggr::Adapter.const_get(adp.to_s) rescue begin Loggr::Adapter.const_get(adp.to_s.upcase) rescue nil end end
           unless const
             # code adapter from ActiveSupport::Inflector#constantize
             # https://github.com/rails/rails/blob/v3.0.9/activesupport/lib/active_support/inflector/methods.rb#L107

data/lib/loggr/adapter/abstract.rb

@@ -1,25 +1,25 @@
 module Loggr
   module Adapter
-    
+
     # A basically abstract base class for logger backend
     # implementations, provides a default implementation for MDC (hash & thread local based).
     #
     # Ensure to implement `#logger`.
-    # 
+    #
     class AbstractAdapter
-      
+
       # Implement which creates a new instance of a logger.
       def logger(name, options = {})
         raise "#{self.class.name}#logger is declared `abstract': implement #logger method"
       end
-      
+
       # Use a simple thread local hash as fake MDC, because it's
       # not supported by the logger anyway - but it should be available
       # for consistency and usage.
       def mdc
         mdc_key = "#{self.class.name}.mdc"
         Thread.current[mdc_key] ||= Hash.new
-      end      
+      end
     end
   end
 end

data/lib/loggr/adapter/base.rb

@@ -1,33 +1,34 @@
 require 'loggr/adapter/abstract'
-require 'logger'
+require 'loggr/support/annotations'
 
 module Loggr
   module Adapter
-    
+
     # Default backend which is backed Rubys Stdlib Logger.
     #
     class BaseAdapter < AbstractAdapter
-      
-      # 
+
+      #
       #
       def logger(name, options = {})
         name = normalize_name(name)
         @loggers ||= {}
         @loggers[name] ||= build_new_logger(name, options)
       end
-      
+
       protected
         # Constructs a new logger instance for the supplied options, is called
         # by `#loggers` when no logger with this name already exists - instead of
         # creating a new logger...
         #
         def build_new_logger(name, options = {})
-          ::Logger.new(options[:to] || "#{name.to_s.gsub(/[:\s\/]+/, '_')}.log").tap do |logger|
+          logger = ::Logger.new(options[:to] || "#{name.to_s.gsub(/[:\s\/]+/, '_')}.log").tap do |logger|
             logger.level = options[:level] || Logger::INFO
             logger.progname = name
-          end        
+          end
+          Loggr::Support::Annotations.enhance(logger)
         end
-        
+
         # Because we should also allow using class names, or objects
         # to construct new loggers (like in SLF4J), it makes sense to
         # have a method which normalizes some input, be it a string or
@@ -45,9 +46,9 @@ module Loggr
             when Module then name.name.to_s
             else name.class.name.to_s
           end
-        end        
+        end
     end
-    
+
     # Okay, basically a singleton thus create instance
     Base = BaseAdapter.new
   end