logging 1.8.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 522785313b2bc22e301dbc6d52078530fddad1e1
-  data.tar.gz: 8a9288e2d318ecd89ce38fa06c53326c94d5c9f7
+  metadata.gz: 2d4abf77abb948de12d0e860a18be03b9b2314bd
+  data.tar.gz: f3bb7dc5daf79b192d56de6d2a96d217bebbe24b
 SHA512:
-  metadata.gz: 04615c41d0c1853d45a7d0751f5ee2d3b1b23b98e04b5931e001930f6ee247e2d355d691e3878658cc3a11126c823e058374d383fac3611923b89c05f9819e29
-  data.tar.gz: 23125228da4ac0c67bfee7a055deec67fa465c4f1ccabbf41614c897cadcc5ad3dc8bb4292f889a9c38c16889038c7acdf79ba0fa1db8a5124234baeea49a2da
+  metadata.gz: 31e6820636ea493830b4b880c112aa57a53fc4e283da0682b5dfbdb373d3040017889153e50f625525eb6e0e7e4d7e2752fd6fd60c8acbc909d249762b2fd879
+  data.tar.gz: c55a5532bcc8e6c8543f231484a11cb9f65a747afe231f58709fc13274962e6318a05a3e76d09b12c1793bc346cd87eca759e0eefa2185af1ea38d2caf554ab9

data/.travis.yml

@@ -6,8 +6,8 @@ install:        "rake gem:install_dependencies"
 script: "rake"
 
 rvm:
-  - 1.8.7
-  - 1.9.2
   - 1.9.3
-  - jruby
+  - 2.0.0
+  - 2.1.5
+  - 2.2.1
 

data/History.txt

@@ -1,3 +1,23 @@
+== 2.0.0 / 2015-03-28
+
+Enhancements
+- added event filtering via the Filter framework
+- improvements to buffered logging
+- code readability improvements around meta-programming
+
+Bug Fixes
+- fixed an `already initialized error`
+- avoid unnecessary mutex-ing in logger lookup
+
+Deprecations
+- dropped Ruby 1.8 support
+- removed logger consolidation
+- removed YAML style configuration
+- removed the Logging::Stats module
+- removed the Hash#getopt method
+- removed the Growl appender
+- moved the Email appender to the logging-email plugin gem
+
 == 1.8.2 / 2014-01-29
 
 Bug Fixes

data/README.md

@@ -0,0 +1,159 @@
+## Logging
+by Tim Pease [![](https://secure.travis-ci.org/TwP/logging.png)](https://travis-ci.org/TwP/logging)
+
+* [Homepage](http://rubygems.org/gems/logging)
+* [Github Project](https://github.com/TwP/logging)
+
+### Description
+
+Logging is a flexible logging library for use in Ruby programs based on the
+design of Java's log4j library. It features a hierarchical logging system,
+custom level names, multiple output destinations per log event, custom
+formatting, and more.
+
+### Installation
+
+```
+gem install logging
+```
+
+### Examples
+
+This example configures a logger to output messages in a format similar to the
+core ruby Logger class. Only log messages that are warnings or higher will be
+logged.
+
+```ruby
+require 'logging'
+
+logger = Logging.logger(STDOUT)
+logger.level = :warn
+
+logger.debug "this debug message will not be output by the logger"
+logger.warn "this is your last warning"
+```
+
+In this example, a single logger is created that will append to STDOUT and to a
+file. Only log messages that are informational or higher will be logged.
+
+```ruby
+require 'logging'
+
+logger = Logging.logger['example_logger']
+logger.level = :info
+
+logger.add_appenders \
+    Logging.appenders.stdout,
+    Logging.appenders.file('example.log')
+
+logger.debug "this debug message will not be output by the logger"
+logger.info "just some friendly advice"
+```
+
+The Logging library was created to allow each class in a program to have its
+own configurable logger. The logging level for a particular class can be
+changed independently of all other loggers in the system. This example shows
+the recommended way of accomplishing this.
+
+```ruby
+require 'logging'
+
+Logging.logger['FirstClass'].level = :warn
+Logging.logger['SecondClass'].level = :debug
+
+class FirstClass
+  def initialize
+    @logger = Logging.logger[self]
+  end
+
+  def some_method
+    @logger.debug "some method was called on #{self.inspect}"
+  end
+end
+
+class SecondClass
+  def initialize
+    @logger = Logging.logger[self]
+  end
+
+  def another_method
+    @logger.debug "another method was called on #{self.inspect}"
+  end
+end
+```
+
+There are many more examples in the [examples folder](https://github.com/TwP/logging/tree/master/examples)
+of the logging package. The recommended reading order is the following:
+
+* [simple.rb](https://github.com/TwP/logging/blob/master/examples/simple.rb)
+* [rspec_integration.rb](https://github.com/TwP/logging/blob/master/examples/rspec_integration.rb)
+* [loggers.rb](https://github.com/TwP/logging/blob/master/examples/loggers.rb)
+* [classes.rb](https://github.com/TwP/logging/blob/master/examples/classes.rb)
+* [hierarchies.rb](https://github.com/TwP/logging/blob/master/examples/hierarchies.rb)
+* [names.rb](https://github.com/TwP/logging/blob/master/examples/names.rb)
+* [lazy.rb](https://github.com/TwP/logging/blob/master/examples/lazy.rb)
+* [appenders.rb](https://github.com/TwP/logging/blob/master/examples/appenders.rb)
+* [layouts.rb](https://github.com/TwP/logging/blob/master/examples/layouts.rb)
+* [formatting.rb](https://github.com/TwP/logging/blob/master/examples/formatting.rb)
+* [colorization.rb](https://github.com/TwP/logging/blob/master/examples/colorization.rb)
+* [consolidation.rb](https://github.com/TwP/logging/blob/master/examples/consolidation.rb)
+* [fork.rb](https://github.com/TwP/logging/blob/master/examples/fork.rb)
+* [mdc.rb](https://github.com/TwP/logging/blob/master/examples/mdc.rb)
+
+### Extending
+
+The Logging framework is extensible via the [little-plugger](https://github.com/twp/little-plugger)
+gem based plugin system. New appenders or formatters can be released as ruby
+gems. When installed locally, the Logging framework will automatically detect
+these gems as plugins and make them available for use.
+
+The [logging-email](https://github.com/twp/logging-email) plugin is a good
+example to follow. It includes a [`lib/logging/plugins/email.rb`](https://github.com/twp/logging-email/tree/master/lib/logging/plugins/email.rb)
+file which is detected by the plugin framework. This file declares a
+`Logging::Plugins::Email.initialize_email` method that is called when the plugin
+is loaded.
+
+The three steps for creating a plugin are:
+
+* create a new Ruby gem: `logging-<name>`
+* include a plugin file: `lib/logging/plugins/<name>.rb`
+* definie a plugin initializer: `Logging::Plugins::<Name>.initialize_<name>`
+
+### Development
+
+The Logging source code relies on the Mr Bones project for default rake tasks.
+You will need to install the Mr Bones gem if you want to build or test the
+logging gem. Conveniently there is a bootstrap script that you can run to setup
+your development environment.
+
+```
+script/bootstrap
+```
+
+This will install the Mr Bones gem and the required Ruby gems for development.
+After this is done you can rake `rake -T` to see the available rake tasks.
+
+### License
+
+The MIT License
+
+Copyright (c) 2015 Tim Pease
+
+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/Rakefile

@@ -1,10 +1,13 @@
-
 begin
   require 'bones'
 rescue LoadError
   abort '### please install the "bones" gem ###'
 end
 
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'logging/version'
+
 task :default => 'test:run'
 task 'gem:release' => 'test:run'
 
@@ -14,6 +17,7 @@ Bones {
   authors      'Tim Pease'
   email        'tim.pease@gmail.com'
   url          'http://rubygems.org/gems/logging'
+  version      Logging::VERSION
 
   rdoc.exclude << '^data'
   rdoc.include << '^examples/.*\.rb'
@@ -21,11 +25,11 @@ Bones {
 
   use_gmail
 
-  depend_on 'little-plugger'
-  depend_on 'multi_json'
+  depend_on 'little-plugger', '~> 1.1'
+  depend_on 'multi_json',     '~> 1.10'
 
-  depend_on 'flexmock', '~> 1.0',  :development => true
-  depend_on 'bones-git',           :development => true
+  depend_on 'flexmock',  '~> 1.0', :development => true
+  depend_on 'bones-git', '~> 1.3', :development => true
   #depend_on 'bones-rcov',   :development => true
 }
 

data/examples/appenders.rb

@@ -8,9 +8,7 @@
 # description of each. Please refer to the documentation for specific
 # configuration options available for each.
 #
-#   Email         generates e-mail messages
 #   File          writes to a regular file
-#   Growl         outputs growl notifications (Mac OS X only)
 #   IO            generic IO appender
 #   RollingFile   writes to a file and rolls based on size or age
 #   Stdout        appends to STDOUT
@@ -20,9 +18,7 @@
 #
 # And you can access these appenders:
 #
-#   Logging.appenders.email
 #   Logging.appenders.file
-#   Logging.appenders.growl
 #   Logging.appenders.io
 #   Logging.appenders.rolling_file
 #   Logging.appenders.stdout

data/examples/layouts.rb

@@ -28,15 +28,8 @@
     :layout => Logging.layouts.json
   )
 
-  # send growl notifications for errors and fatals using a nice pattern
-  Logging.appenders.growl(
-    'growl',
-    :level  => :error,
-    :layout => Logging.layouts.pattern(:pattern => '[%d] %-5l: %m\n')
-  )
-
   log = Logging.logger['Foo::Bar']
-  log.add_appenders 'stdout', 'development.log', 'growl'
+  log.add_appenders 'stdout', 'development.log'
   log.level = :debug
 
   log.debug "a very nice little debug message"

data/examples/names.rb

@@ -22,15 +22,15 @@
   require 'logging'
 
   Logging.appenders.file('Debug File', :filename => 'debug.log')
-  Logging.appenders.growl('Growl Notifier', :level => :error)
+  Logging.appenders.stderr('Standard Error', :level => :error)
 
   # configure the root logger
   Logging.logger.root.appenders = 'Debug File'
   Logging.logger.root.level = :debug
 
-  # add the growl notifier to the Critical logger (it will use it's own
-  # appender and the root logger's appender, too)
-  Logging.logger['Critical'].appenders = 'Growl Notifier'
+  # add the Standard Error appender to the Critical logger (it will use it's
+  # own appender and the root logger's appender, too)
+  Logging.logger['Critical'].appenders = 'Standard Error'
 
   # if you'll notice above, assigning appenders using just the name is valid
   # the logger is smart enough to figure out it was given a string and then

data/lib/logging.rb

@@ -1,8 +1,3 @@
-
-# Equivalent to a header guard in C/C++
-# Used to prevent the class/module from being loaded more than once
-unless defined? Logging
-
 require File.expand_path('../logging/utils', __FILE__)
 
 require 'yaml'
@@ -11,7 +6,12 @@ require 'fileutils'
 require 'little-plugger'
 require 'multi_json'
 
-HAVE_SYSLOG = require? 'syslog'
+begin
+  require 'syslog'
+  HAVE_SYSLOG = true
+rescue LoadError
+  HAVE_SYSLOG = false
+end
 
 #
 #
@@ -28,28 +28,6 @@ module Logging
 
   class << self
 
-    # call-seq:
-    #    Logging.configure( filename )
-    #    Logging.configure { block }
-    #
-    # Configures the Logging framework using the configuration information
-    # found in the given file. The file extension should be either '.yaml'
-    # or '.yml' (XML configuration is not yet supported).
-    #
-    def configure( *args, &block )
-      if block
-        return ::Logging::Config::Configurator.process(&block)
-      end
-
-      filename = args.shift
-      raise ArgumentError, 'a filename was not given' if filename.nil?
-
-      case File.extname(filename)
-      when '.yaml', '.yml'
-        ::Logging::Config::YamlConfigurator.load(filename, *args)
-      else raise ArgumentError, 'unknown configuration file format' end
-    end
-
     # call-seq:
     #    Logging.logger( device, age = 7, size = 1048576 )
     #    Logging.logger( device, age = 'weekly' )
@@ -185,34 +163,6 @@ module Logging
       self
     end
 
-    # call-seq:
-    #    Logging.consolidate( 'First::Name', 'Second::Name', ... )
-    #
-    # Consolidate all loggers under the given namespace. All child loggers
-    # in the namespace will use the "consolidated" namespace logger instead
-    # of creating a new logger for each class or module.
-    #
-    # If the "root" logger name is passed to this method then all loggers
-    # will consolidate to the root logger. In other words, only the root
-    # logger will be created, and it will be used by all classes and modules
-    # in the application.
-    #
-    # ==== Example
-    #
-    #    Logging.consolidate( 'Foo' )
-    #
-    #    foo = Logging.logger['Foo']
-    #    bar = Logging.logger['Foo::Bar']
-    #    baz = Logging.logger['Baz']
-    #
-    #    foo.object_id == bar.object_id    #=> true
-    #    foo.object_id == baz.object_id    #=> false
-    #
-    def consolidate( *args )
-      ::Logging::Repository.instance.add_master(*args)
-      self
-    end
-
     # call-seq:
     #    include Logging.globally
     #    include Logging.globally( :logger )
@@ -361,12 +311,6 @@ module Logging
           end
     end
 
-    # Returns the version string for the library.
-    #
-    def version
-      @version ||= File.read(path('version.txt')).strip
-    end
-
     # Returns the library path for the module. If any arguments are given,
     # they will be joined to the end of the library path using
     # <tt>File.join</tt>.
@@ -434,11 +378,11 @@ module Logging
     #                    that the logger will *not* pass log events up to the
     #                    parent logger
     #
-    #    4) trace      - a "+T" shows that the logger will include trace
-    #                    information in generated log events (this includes
-    #                    filename and line number of the log message; "-T"
-    #                    shows that the logger does not include trace
-    #                    information in the log events)
+    #    4) tracing    - a "+T" shows that the logger will include caller
+    #                    tracing information in generated log events (this
+    #                    includes filename and line number of the log
+    #                    message); "-T" shows that the logger does not include
+    #                    caller tracing information in the log events
     #
     # If a logger has appenders then they are listed, one per line,
     # immediately below the logger. Appender lines are pre-pended with a
@@ -463,7 +407,7 @@ module Logging
     def show_configuration( io = STDOUT, logger = 'root', indent = 0 )
       logger = ::Logging::Logger[logger] unless ::Logging::Logger === logger
 
-      logger._dump_configuration(io, indent)
+      io << logger._dump_configuration(indent)
 
       indent += 2
       children = ::Logging::Repository.instance.children(logger.name)
@@ -471,7 +415,7 @@ module Logging
         ::Logging.show_configuration(io, child, indent)
       end
 
-      self
+      io
     end
 
     # :stopdoc:
@@ -497,6 +441,14 @@ module Logging
       ::Logging::Logger[::Logging].__send__(levelify(LNAMES[level]), &block)
     end
 
+    # Internal logging method for handling exceptions. If the
+    # `Thread#abort_on_exception` flag is set then the
+    # exception will be raised again.
+    def log_internal_error( err )
+      log_internal(-2) { err }
+      raise err if Thread.abort_on_exception
+    end
+
     # Close all appenders
     def shutdown( *args )
       return unless initialized?
@@ -526,22 +478,21 @@ module Logging
     # :startdoc:
   end
 
+  require libpath('logging/version')
   require libpath('logging/appender')
   require libpath('logging/layout')
+  require libpath('logging/filter')
   require libpath('logging/log_event')
   require libpath('logging/logger')
   require libpath('logging/repository')
   require libpath('logging/root_logger')
-  require libpath('logging/stats')
   require libpath('logging/color_scheme')
   require libpath('logging/appenders')
   require libpath('logging/layouts')
+  require libpath('logging/filters')
   require libpath('logging/proxy')
   require libpath('logging/diagnostic_context')
 
-  require libpath('logging/config/configurator')
-  require libpath('logging/config/yaml_configurator')
-
   require libpath('logging/rails_compat')
 end  # module Logging
 
@@ -554,6 +505,3 @@ end  # module Logging
 # application. This is required when daemonizing.
 #
 ObjectSpace.define_finalizer self, Logging.method(:shutdown)
-
-end  # unless defined?
-