loggr 1.0.0

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in loggr.gemspec
+gemspec

data/LICENSES.md

@@ -0,0 +1,15 @@
+Simple Logging Facade for Java (SLF4J)
+--------------------------------------
+
+- License: http://www.slf4j.org/license.html, MIT license, (c) by QOS.ch
+- File: lib/slf4j-api-1.6.1.jar
+- URL: http://www.slf4j.org/
+- Source: https://github.com/ceki/slf4j
+
+Logback
+-------
+
+- License: http://logback.qos.ch/license.html, EPL 1.0, (c) by QOS.ch
+- Files: lib/logback-classic-0.9.29.jar, lib/logback-core-0.9.29.jar
+- URL: http://logback.qos.ch/
+- Source: https://github.com/ceki/logback

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Lukas Westermann, at-point ag
+
+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.md

@@ -0,0 +1,230 @@
+Loggr
+=====
+
+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
+- Handles using a Mapped Diagnostic Context (MDC)
+
+**So, why should I use a logger factory instead of just `Logger.new('out.log')`
+or `Rails.logger`?** Deploying the same application to different environments,
+with different logging requirements, might make such a step necessary. Or when
+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
+
+**Documentation** The latest RDocs are available on rubydoc.info.
+
+http://rubydoc.info/github/at-point/loggr/master/frames
+
+Installation
+------------
+
+Like any gem, just add it to the Gemfile:
+
+    # stable version
+    gem 'loggr', '~> 1.0.0'
+    
+    # latest development version
+    gem 'loggr', :git => 'git://github.com/at-point/loggr.git'
+    
+Getting started
+===============
+
+Guides through creating some sample Logger instances and integration with Rails, if interested
+in using the SLF4J Logger directly (without the factory), skip to _The SLF4J Wrapper_.
+
+An example, application runs in development on MRI and production in a Jetty container
+(Java/JRuby), lets assume you want to log there SQL using a logger named `jruby.rails.ActiveRecord`.
+
+    # config/initializers/logging.rb:
+    LoggerFactory.adapter = Rails.env.production? ? :slf4j : :rails
+    ActiveRecord::Base.logger = LoggerFactory.logger 'jruby.rails.ActiveRecord'
+
+Once an adapter has been specified new logger instances can be easily created using:
+
+    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
+adapter supports it, else it just tries to return a logger which has an API compatible with
+those found by Stdlibs Logger.
+
+The LoggerFactory
+------------------
+
+Yap, is responsible for creating new loggers, a logger factory has an adapter, the adapter
+defines how logger instances are really created.
+
+### Creating new loggers
+
+    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>**
+
+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`)
+
+**<code>LoggerFactory.adapter = :buffered</code>**
+
+Creates `ActiveSupport::BufferedLogger` instances and supports the same options
+as the `:base` adapter.
+
+**<code>LoggerFactory.adapter = :rails</code>**
+
+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>**
+
+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
+these options for `LoggerFactory.logger(name, options = {})`:
+
+- `:marker`, String, additional marker logged with each statement (default: `nil`)
+
+### 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
+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):
+
+    # app/controllers/application_controller.rb
+    class ApplicationController < ActionController::Base
+      around_filter :push_ip_to_mdc
+      
+      private        
+        def push_ip_to_mdc
+          LoggerFactory.mdc[:ip] = request.ip
+          yield
+        ensure
+          LoggerFactory.mdc.delete(:ip)
+        end
+    end
+    
+When using SLF4J all statements would now be annotated with the IP from where the request
+was made from.
+
+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
+- SLF4J markers
+- The Mapped Diagnostic Context (MDC)
+- Access to SLF4J & Logback implementation JARs 
+
+The Logger
+----------
+
+Creating a new logger is as simple as creating instances of `Loggr::SLF4J::Logger`:
+
+    # 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"
+
+The MDC
+-------
+
+A wrapper hash for SLF4Js Mapped Diagnostic Context is available using `Loggr::SLF4J::MDC`
+like a hash:
+
+    begin
+      Loggr::SLF4J::MDC[:user] = username
+      do_some_stuff
+    ensure
+      Loggr::SLF4J::MDC.delete(:user)
+    end
+
+It's a good practice to wrap MDC set/get into begin/ensure blocks to ensure the value
+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`
+
+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    
+      def logger(name, options = {})
+        # build logger instances and return it
+      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).
+
+Similar to ActiveModel there are also Lint tests available to verify if your adapter
+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
+       end
+    end
+
+Contribute
+----------
+
+1. Fork this project and hack away
+2. Ensure that the changes are well tested
+3. Send pull request
+
+License & Copyright
+-------------------
+
+Loggr is licensed under the MIT License, (c) 2011 by at-point ag.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+require 'rake/testtask'
+
+# to fix warnings
+include Rake::DSL
+
+Bundler::GemHelper.install_tasks
+
+desc 'Test the loggr gem.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/lib/loggr.rb

@@ -0,0 +1,38 @@
+#--
+# Copyright (c) 2011 Lukas Westermann, at-point ag
+#
+# 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.
+#++
+
+module Loggr
+  autoload :Adapter,  'loggr/adapter'  
+  autoload :Severity, 'loggr/severity'
+  autoload :Lint,     'loggr/lint'
+  
+  autoload :SLF4J,    'loggr/slf4j'
+  
+  autoload :VERSION,  'loggr/version'
+  
+  # Ensure we've got the Log Levels covered
+  include Loggr::Severity  
+end
+
+# Autoloading the factory into the root.
+autoload :LoggerFactory, 'loggr/factory'

data/lib/loggr/adapter.rb

@@ -0,0 +1,114 @@
+module Loggr
+  
+  # The factory is responsible for getting Logger instances from
+  # the adapters.
+  #
+  # It delegates both the `logger` and `mdc` calls to the current
+  # adpater.
+  #
+  # The adpater can be changed by setting `adpater = ...`:
+  #
+  #    Loggr.adapter = Loggr::Adapter::SLF4J
+  #
+  # @see #logger, #mdc  
+  module Adapter
+    
+    # An abstract base class, which provides a simple MDC implementation
+    autoload :AbstractAdapter, 'loggr/adapter/abstract'
+    
+    # Adapter for Ruby Stdlib Logger
+    autoload :Base,     'loggr/adapter/base'
+    
+    # Adapter for ActiveSupport::BufferedLogger, requires AS
+    autoload :Buffered, 'loggr/adapter/buffered'
+        
+    # Adapter which uses Rails.logger
+    autoload :Rails,    'loggr/adapter/rails'
+    
+    # Adpater for SLF4J
+    autoload :SLF4J,    'loggr/adapter/slf4j'
+        
+    # Get the backend, if no backend is defined uses the default backend.
+    #
+    # If running in a rails environment, automatically chooses the rails
+    # adapter as a default, else base is used.
+    def adapter
+      @adapter ||= Object.const_defined?(:Rails) ? Loggr::Adapter::Rails : Loggr::Adapter::Base
+    end
+    
+    # Set a new adapter, either as string, class or whatever :)
+    #
+    def adapter=(new_adapter)
+      @adapter = get_adapter(new_adapter)
+    end
+        
+    # Get a new logger instance for supplied named logger or class name.
+    #
+    # All adapters must ensure that they provide the same API for creating
+    # new loggers. Each logger has a name, further possible options are:
+    #
+    # - `:to`, filename or IO, where to write the output to
+    # - `:level`, Fixnum, starting log level, @see `Loggr::Severity`
+    # - `:marker`, String, name of the category/marker
+    #
+    # If an adapter does not support setting a specific option, just
+    # ignore it.
+    def logger(name, options = {}, &block)
+      use_adapter = options.key?(:adapter) ? get_adapter(options.delete(:adapter)) : self.adapter
+      use_adapter.logger(name, options).tap do |logger|
+        yield(logger) if block_given?
+      end
+    end
+    
+    # The Mapped Diagnostic Context is a basically a hash where values
+    # can be stored for certain keys, the context must be stored per thread.
+    #
+    # The most basic MDC implementation is `Thread.local['my_simple_mdc'] ||= Hash.new`.
+    #
+    # If a adapter provides a native MDC implementation ensure it does expose
+    # these methods:
+    #
+    # - `def []=(key, value)`, set a property in the MDC
+    # - `def [](key)`, get a property from the MDC
+    # - `def delete(key)`, delete a property in the MDC
+    # - `def clear()`, deletes all properties from the MDC
+    # - `def to_hash`, access MDC as standard ruby hash (might be clone, though!)
+    #
+    # Well it should basically behave like a Ruby Hash, eventhough not with all
+    # options.
+    def mdc
+      self.adapter.mdc
+    end
+    
+    protected
+    
+      # 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 :)
+        
+        # Code adapter from ActiveSupport::Inflector#camelize
+        # https://github.com/rails/rails/blob/v3.0.9/activesupport/lib/active_support/inflector/methods.rb#L30
+        adp = adp.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase } if adp.is_a?(Symbol)
+        
+        clazz = adp
+        
+        if adp.respond_to?(:to_str)
+          const = begin Loggr::Adapter.const_get(adp.to_s) rescue nil 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
+            names = adp.to_s.split('::')
+            names.shift if names.empty? || names.first.empty?
+            
+            const = ::Object
+            names.each { |n| const = const.const_get(n) }
+          end
+          clazz = const          
+        end
+        
+        raise "#{clazz}: an adapter must implement #logger and #mdc" unless clazz.respond_to?(:logger) && clazz.respond_to?(:mdc)
+        clazz
+      end
+  end
+end