logjam 1.0.0 → 1.1.0

data/README

@@ -1,8 +1,8 @@
-LogJam
-======
-LogJam is a library that attempts to allow for the aggregation the distributing
-logger facilities across a range of classes. Goals in creating this library
-were...
+# LogJam
+
+LogJam is a library that attempts to allow for the aggregation and the
+distribution of logging facilities across a range of classes. Goals in
+creating this library were...
 
    * Easy of use. Fall back on defaults as much as possible and allow the
      functionality to be integrated and used with the least amount of work.
@@ -20,11 +20,11 @@ were...
      wanted to minimize the burden this placed on library users at the same
      time.
 
-Configuration & Setup
----------------------
-The LogJam library is configured through a call to the configure() method on the
-LogJam module. This method accepts a single parameter that may be either a
-String, a Hash, an IO object or nil.
+## Configuration & Setup
+
+To explicitly configure the settings LogJam you make a call to the
+LogJam#configure() method. This method takes a single parameter which should be
+either a String, a Hash, an IO object or nil.
 
 If you pass a String in this is expected to contain the path and name of a file
 that contains the logging configuration. Logging configuration files can be
@@ -32,7 +32,7 @@ provided in either YAML or JSON format. If you pass an IO object this is
 expected to be the source of the configuration and, again, this configuration
 should be in either YAML or JSON format. In either case, where a String or IO
 is specified, the data read must be translatable into a Hash, which brings us
-to the other type that the configure() method accepts as a parameter.
+to the other type that the LogJam#configure() method accepts as a parameter.
 
 A Hash passed to the configure() method is expected to contain a set of values
 that can be converted into a logging set up. Passing an empty Hash will result
@@ -42,37 +42,37 @@ stream being created and used by all classes that have LogJam functionality.
 The Hash passed to the configure() method can contain two keys that the library
 will recognise and use. The first of these is 'loggers', in either Symbol or
 String form. The value under the loggers key is expected to be an Array
-containing zero or more logger definitions. A logger definition is a Hash in
-which the following keys are recognised (either as Strings or Symbols)...
-
-   Key                       Description
-   -----------------------   --------------------------------------------------
-   default                   A boolean indicating whether this logger is the
-                             default (i.e. the one to be used when no other
-                             fits the bill). Only one logger should be declared
-                             as a default.
-   datetime_format           The date/time format to be used by the logger. See
-                             the documentation for the standard Ruby Logger
-                             class for more details.
-   file                      The path and name of the file that logging details
-                             will be written to. Two special values are
-                             recognised in this value. STDOUT and STDERR are
-                             translated to mean the standard output or error
-                             streams respectively.
-   level                     The logging level to set on the logger. If not
-                             explicitly specified this defaults to DEBUG.
-   max_size                  When rotation is set to an integer value this value
-                             can be set to indicate the maximum permitted file
-                             size for a log file.
-   name                      The name to associate with the logger. This allows
-                             loggers to be tied to classes or for the creation
-                             of aliases that tie multiple names to a single
-                             logger. Note that you should always use Strings
-                             (and not Symbols) when specifying aliases.
-   rotation                  The frequency with which the log file is rotated.
-                             This may be an integer to indicate how many old log
-                             files are retained or may be a String such as
-                             "daily", "weekly" or "monthly".
+containing zero or more logger definitions. An individual logger definition is
+itself a Hash in which the following keys are recognised (either as Strings or
+Symbols) - default, datetime_format, file, level, max_size, name and rotation.
+The meanings applied to these keys are as follows...
+
+ * default: A boolean indicating whether this logger is the default (i.e. the
+   one to be used when no other explicitly fits the bill). Only one logger
+   should be declared as a default.
+
+ * datetime_format: The date/time format to be used by the logger. See the
+   documentation for the standard Ruby Logger class for more details.
+
+ * file: The path and name of the file that logging details will be written to.
+   Two special values are recognised in this value. STDOUT and STDERR are
+   translated to mean the standard output or error streams respectively.
+
+ * level: The logging level to set on the logger. Must be one of DEBUG, INFO,
+   WARN, ERROR, FATAL or UNKNOWN. If not explicitly specified this defaults
+   to DEBUG.
+
+ * max_size: When rotation is set to an integer value this value can be set to
+   indicate the maximum permitted file size for a log file.
+
+ * name: The name to associate with the logger. This allows loggers to be tied
+   to classes or for the creation of aliases that tie multiple names to a single
+   logger. Note that you should always use Strings (and not Symbols) when
+   specifying aliases.
+
+ * rotation: The frequency with which the log file is rotated. This may be an
+   integer to indicate how many old log files are retained or may be a String
+   such as "daily", "weekly" or "monthly".
 
 A note on logger names. Logger names (including alias names) aren't hierarchical
 and should be unique.
@@ -84,19 +84,24 @@ alias names and the mapped values are expected to be the name of a logger
 declared in the logger section. An entry in the aliases Hash creates an alias
 for an existing logger under a different name.
 
-If you pass nil to the configure method it behaves in a slightly different
-fashion. In this case the method searches for a configuration file that it can
-use given a default set of files names (basically logging.yaml, logging.yml and
-logging.json in the current working directory and in a subdirectory of the
+The final parameter option when calling LogJam#configure() is to pass a nil to
+the method. If you pass nil to the configure method it behaves in a slightly
+different fashion. In this case the method searches for a configuration file
+that it can use given a default set of files names (logging.yaml, logging.yml
+and logging.json in the current working directory and in a subdirectory of the
 current working directory called config). The first of these files that it finds
 it attempts to use as configuration for the logging set up. If it doesn't find
 a configuration file then this type of call becomes equivalent to passing an
-empty Hash to the configure() method.
+empty Hash to the configure() method. As of version 1.1.0 the library includes
+an implicit call to LogJam#configure(nil) removing the need to do this
+explicitly in your own code.
 
-See the end of this document for some example configurations.
+Note that you can call LogJam#configure multiple times, with each successive
+call overwriting and replacing the details of previous calls. See the end of
+this document for some example configurations.
+
+## Logging With The Library
 
-Logging With The Library
-------------------------
 The stated goals of the LogJam library are to avoid the need to pass Logger
 instances around while still allowing potentially complex configuration with a
 minimum of code. The first step in this process has been covered in the
@@ -105,42 +110,60 @@ from a single Hash or file. This section will provide details on how to deploy
 loggers to various classes.
 
 The LogJam library works by providing an extension to any class that uses it
-that provides access to the logger to be used by the class. To make use of this
-functionality a class must call the apply() method of the LogJam module. A
-typical call to this method might look like...
-
+that provides access to the logger to be used by the class. As of version 1.1.0
+LogJam applies itself as an extension to the Ruby Object class, making the
+logging facilities it provides available in any object. Prior to v1.1.0 you had
+to make a call the apply() method of the LogJam module inside your class
+definition. A typical call of this type might look like...
+
+```
+   # Apply logging facilties to my class.
    LogJam.apply(self, "my_logger")
+```
    
-This line would appear somewhere inside the definition for the class that will
-use logging. The first parameter to the call is the class that is to be extended
-with the LogJam functionality. The second parameter is the name of the logger
-that the class will use. Note that this parameter is optional and, if not
-specified or if a matching logger does not exist, the class will fall back in
-using the default logger.
-
-Once this line has been added to the class definition it will cause the class to
-be extended with three methods - two class level methods (one called log() and
-one called log=()) and an instance level method called log(). The log() methods
-retrieve the Logger instance to be used by the class instances. The log=()
-method allows the Logger instance associated with a class to be altered. Note
-the instance level log() method will only be added if an existing method with
-that name does not already exist on the class.
+This option remains available for backward compatibility but is no longer
+needed. A line like this would appear somewhere inside the definition for the
+class that will use logging. The first parameter to the call is the class that
+is to be extended with the LogJam functionality. The second parameter is the
+name of the logger that the class will use. Note that this parameter is optional
+and, if notspecified or if a matching logger does not exist, the class will fall
+back in using the default logger.
+
+From version 1.1.0 onward you no longer need to call apply. Instead LogJams
+logging facilities are available in all objects. This change means that all
+classes use the default logger as standard. If you want to continue to use an
+explitictly named logger on a per class basis you can make a call to the
+LogJam#set_logger_name() method within your class definitions. This is similar
+in nature to how the apply method was used and so would look something like the
+following...
+
+```
+   # Use an explicitly named logger for my class.
+   set_logger_name "my_logger"
+```
+
+LogJams logging facilities consist of two class level methods (one called log()
+and one called log=()) and an instance level method called log(). The log()
+methods retrieve the Logger instance to be used by the class instances. The
+log=() method allows the Logger instance associated with a class to be altered.
+You should take care when assigning a logger in this fashion as assigning it
+on one class may have an impact on many classes (e.g. if there is only a single
+default logger defined in configuration).
 
 The following complete (although contrived) example gives an overview of how
 this would work...
 
+```
    require 'rubygems'
    require 'logjam'
    
    class Writer
-      LogJam.apply(self, "echo")
-      
       def initialize(stream=STDOUT)
          @stream = stream
       end
       
       def echo(message)
-         Writer.log.debug("Echoed: #{message}")
+         log.debug("Echoed: #{message}")
          @stream.puts message
       end
    end
@@ -154,25 +177,25 @@ this would work...
    rescue => error
       puts "ERROR: #{error}\n" + error.backtrace.join("\n")
    end
+```
 
 In this example we create a Writer class that can echo a String on a stream. In
-doing this it also logs the message echoed at the debug level. We use the
-LogJam.apply() method to extend this class with logging capabilities so that, in
-the echo() method, we can simply call Writer.log() to get the class logger.
+doing this it also logs the message echoed at the debug level. We can simply
+call the log() method to get the class logger.
 
 In the later section of the code we configure the LogJam system to have a single
 Logger that writes to the echo.log file. We then create a Writer instance and
 use it to write a simple message. This message should appear on the standard
 output stream and be logged to the echo.log file.
+ 
+## Advanced Usage
 
-Advanced Usage
---------------
 The hope would be that this library can be used in the creation of other
 libraries and allow for control of the logging generated by those libraries
 without having to dig into the workings of the library or to pass around Logger
-instances are constructor parameters or static data. In this case I recommend
-explicitly declaring logger names when using the apply() method and making the
-name that the library uses available with the library documentation so that the
+instances as constructor parameters or static data. In this case I recommend
+explicitly declaring logger names for your library classes and making the name
+that the library uses available with the library documentation so that the
 libraries logging can be switched off or on as needed.
 
 It's intended that, in general, the configure() method on the LogJam module
@@ -198,8 +221,8 @@ Finally, any logger can be fetched from the library using it's name and making
 a call to the LogJam.get_logger() method. Note if you omit the name or pass in
 nil you will retrieve the libraries default logger.
 
-Example Configurations
-----------------------
+## Example Configurations
+
 This section contains some example configurations. A short explanation is given
 for each configuration and then the configuration itself in Hash, YAML and JSON
 formats is provided.
@@ -209,31 +232,41 @@ to the configure method the system creates a single, default logger that writes
 everything on the standard output stream...
 
 Hash
+```
    {}
-   
+```
+
 YAML
-   ---
+```
    {}
+```
 
 JSON
+```
    {}
+```
 
 The following simple configuration writes all logging output to a file called
 application.log in the current working directory. If a logging level is not
 explicitly specified then DEBUG is the default...
 
 Hash
+```
    {:loggers => [{:default => true, :file => "application.log"}]}
+```
 
 YAML
-   --- 
+```
    :loggers: 
    - :default: true
      :file: application.log
+```
 
 JSON
+```
    {"loggers": {"default": true, "file": "application.log"}}
-   
+```
+
 This configuration declares two loggers. The first is called 'silent' and will
 log nothing. The silent logger is the default and so will be used for any class
 that doesn't have an explicitly named logger. The second is called 'verbose' and
@@ -243,6 +276,7 @@ the verbose logger. An class that declares it uses the 'database' logger will
 generate output while all others will be silenced.
 
 Hash
+```
    {:loggers => [{:default => true,
                   :file    => "STDOUT",
                   :level   => "UNKNOWN",
@@ -250,9 +284,10 @@ Hash
                  {:file    => "STDOUT",
                   :name    => "verbose"}],
     :aliases => {"database" => "verbose"}}
+```
 
 YAML
-   --- 
+```
    :loggers: 
    - :default: true
      :file: STDOUT
@@ -262,8 +297,10 @@ YAML
      :name: verbose
    :aliases: 
      database: verbose
+```
 
 JSON
+```
    {"loggers": [{"default":true,
                  "file": "STDOUT",
                  "level": "UNKNOWN",
@@ -271,6 +308,7 @@ JSON
                 {"file": "STDOUT",
                  "name": "verbose"}],
     "aliases": {"database":"verbose"}}
+```
 
 The following configuration can be used as an example of how to drive logging
 from different parts of the code to different destinations. The configuration
@@ -279,6 +317,7 @@ then declares aliases for those loggers that can be used to divide up the
 logging coming from different areas of the code.
 
 Hash
+```
    {:loggers => [{:default => true,
                   :file    => "./log/main.log",
                   :name    => "main"},
@@ -287,9 +326,10 @@ Hash
     :aliases => {"database"   => "secondary",
                  "model"      => "secondary",
                  "controller" => "main"}}
+```
 
 YAML
-   --- 
+```
    :loggers: 
    - :default: true
      :file: ./log/main.log
@@ -300,8 +340,10 @@ YAML
      database: secondary
      model: secondary
      controller: main
+```
 
 JSON
+```
    {"loggers": [{"default":true,
                  "file": "./log/main.log",
                  "name": "main"},
@@ -310,12 +352,24 @@ JSON
     "aliases": {"database":"secondary",
                 "model": "secondary",
                 "controller": "main"}}
+```
+
+## Testing
 
-Testing
--------
-LogJam uses the test-unit Ruby library for testing. The best approach to running
+LogJam uses the minitest Ruby library for testing. The best approach to running
 the tests are to create a new gemset (assuming you're using RVM), do a bundle
 install on this gemset from within the LogJam root directory and then use a
 command such as the following to run the tests...
 
-    $> ruby -I./lib -I./test ./test/unit/test_logjam.rb
+```
+    $> rake test:unit
+```
+
+Individual tests can be run by including a definition for TESTS which contains
+a comma separated_list of the tests to be run. For example...
+
+```
+   $> rake test:unit TESTS=object,apply
+```
+
+...would run only the object and apply tests.

data/lib/logjam/logjam.rb

@@ -27,8 +27,9 @@ module LogJam
                                 ".#{File::SEPARATOR}config#{File::SEPARATOR}logging.json"]
 
    # Module static properties.
-   @@logjam_modules = {}
-   @@logjam_loggers = {}
+   @@logjam_modules  = {}
+   @@logjam_loggers  = {}
+   @@logjam_contexts = {}
    
    # This method is used to configure the LogJam module with the various loggers
    # it will use.
@@ -64,11 +65,14 @@ module LogJam
    # classes that use the same logger.
    #
    # ==== Parameters
-   # target::  The target class that is to be extended.
-   # name::    The name of the logger to be used by the class. Defaults to nil
-   #           to indicate use of the default logger.
-   def self.apply(target, name=nil)
-      target.extend(LogJam.get_module(name))
+   # target::   The target class that is to be extended.
+   # name::     The name of the logger to be used by the class. Defaults to nil
+   #            to indicate use of the default logger.
+   # context::  A Hash of additional parameters that are specific to the class
+   #            to which LogJam is being applied.
+   def self.apply(target, name=nil, context={})
+      @@logjam_contexts[target] = {}.merge(context)
+      target.extend(LogJam.get_module(name, @@logjam_contexts[target]))
       target.send(:define_method, :log) {LogJam.get_logger(name)} if !target.method_defined?(:log)
    end
 
@@ -100,8 +104,9 @@ module LogJam
    # not exist the default module is returned instead.
    #
    # ==== Parameters
-   # name:: The name associated with the module to return.
-   def self.get_module(name)
+   # name::     The name associated with the module to return.
+   # context::  The context that applies to the module to be retrieved.
+   def self.get_module(name, context={})
       LogJam.create_module(name)
    end
 

data/lib/logjam/logjam_logger2.rb

@@ -0,0 +1,68 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module LogJam
+   # This class represents a specialization of the Ruby Logger class. The class
+   # retains a Ruby Logger instance within itself and delegates all standard
+   # logger calls to this instance. This allows for changes to the underlying
+   # logger without changing the containing one, thus bypassing people caching
+   # an instance.
+   class LogJamLogger < Logger
+      # Constructor for the LogJamLogger class. All parameters are passed
+      # straight through to create a standard Ruby Logger instance except
+      # when the first parameter is a Logger instance. In this case the
+      # Logger passed in is used rather than creating a new one.
+      #
+      # ==== Parameters
+      # logdev::      The log device to be used by the logger. This should
+      #               either be a String containing a file path/name or an IO
+      #               object that the logging details will be written to.
+      # shift_age::   The maximum number of old log files to retain or a String
+      #               containing the rotation frequency for the log.
+      # shift_size::  The maximum size that the loggin output will be allowed
+      #               to grow to before rotation occurs.
+      def initialize(logdev, shift_age=0, shift_size=1048576)
+         @log           = (logdev.kind_of?(Logger) ? logdev : Logger.new(logdev, shift_age, shift_size))
+         @name          = nil
+         @prefixes      = {}
+         self.formatter = @log.formatter
+      end
+      
+      # Attribute accessor/mutator declaration.
+      attr_accessor :name, :prefixes
+
+      # A definition of the method_missing method that passes all otherwise
+      # undefined method calls on to the contained logger instance.
+      #
+      # ==== Parameters
+      # method::      A Symbol containing the name of the method that was
+      #               invoked but found to be missing.
+      # *arguments::  An array containing the arguments that were passed
+      #               to the method call.
+      # &block::      Any block passed to the method call.
+      def method_missing(method, *arguments, &block)
+         if @log.responds_to? method
+            @log.send(method, *arguments, &block)
+         else
+            super
+         end
+      end
+
+      # This method replaces the formatter assignment method on the logger
+      # to allow the addition of custom fields.
+      #
+      # ==== Parameters
+      # &block::  The block that contains the standard formatter to be
+      #           set on the logger.
+      def formatter=(&block)
+         @log.formatter = proc do |severity, timestamp, program, message|
+            if @prefixes.include?(severity) || @prefixes.include?(:default)
+               message = "[#{(@prefixes[severity] || @prefixes[:default])}] #{message}"
+            end
+            block.call(severity, timestamp, program, message)
+         end
+      end
+   end
+end

data/lib/logjam/object.rb

@@ -0,0 +1,33 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2013 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+class Object
+   # This method provides an instance level accessor to obtain a logger. Unless
+   # a name is specified the logger returned is the default one.
+   def log
+      LogJam.get_logger
+   end
+
+   # This method provides a class level accessor to obtain a logger. Unless a
+   # name is specified the logger returned is the default one.
+   def self.log
+      LogJam.get_logger
+   end
+
+   def self.log=(logger)
+      LogJam.get_logger.logger = logger
+   end
+
+   # This method allows a class to specify the name of the logger that it uses
+   # once, generally within the class definition.
+   #
+   # ==== Parameters
+   # name::     The name of the logger used by the class.
+   # context::  A Hash of additional parameters that are specific to the class
+   #            to which LogJam is being applied.
+   def self.set_logger_name(name, context={})
+      LogJam.apply(self, name, context)
+   end
+end

data/lib/logjam/version.rb

@@ -1,3 +1,3 @@
 module LogJam
-   VERSION="1.0.0"
+   VERSION="1.1.0"
 end

data/lib/logjam.rb

@@ -8,4 +8,6 @@ require 'logjam/version'
 require 'logjam/exceptions'
 require 'logjam/logjam_logger'
 require 'logjam/logjam'
+require 'logjam/object'
 
+LogJam.configure(nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logjam
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-26 00:00:00.000000000 Z
+date: 2013-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -35,9 +35,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/logjam/version.rb
-- lib/logjam/logjam_logger.rb
 - lib/logjam/logjam.rb
 - lib/logjam/exceptions.rb
+- lib/logjam/logjam_logger.rb
+- lib/logjam/object.rb
+- lib/logjam/logjam_logger2.rb
 - lib/logjam.rb
 - license.txt
 - README
@@ -61,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: A library to aggregate logging.