logging 1.8.2 → 2.0.0

data/README.rdoc

@@ -1,143 +0,0 @@
-= Logging
-by Tim Pease {<img src="https://secure.travis-ci.org/TwP/logging.png">}[http://travis-ci.org/TwP/logging]
-
-* {Homepage}[http://rubygems.org/gems/logging]
-* {Github Project}[https://github.com/TwP/logging]
-* email tim dot pease at gmail dot com
-
-== 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.
-
-== INSTALL
-
-  gem install logging
-
-== EXAMPLE
-
-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.
-
-  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.
-
-  require 'logging'
-
-  logger = Logging.logger['example_logger']
-  logger.add_appenders(
-      Logging.appenders.stdout,
-      Logging.appenders.file('example.log')
-  )
-  logger.level = :info
-
-  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.
-
-  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 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]
-
-== NOTES
-
-Although Logging is intended to supersede Log4r, it is not a one-to-one
-replacement for the Log4r library. Most notably is the difference in namespaces
--- Logging vs. Log4r. Other differences include renaming Log4r::Outputter to
-Logging::Appender and renaming Log4r::Formatter to Logging::Layout. These
-changes were meant to bring the Logging class names more in line with the Log4j
-class names.
-
-== REQUIREMENTS
-
-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.
-
-   gem install bones
-
-After Mr Bones is installed you can install all the depdencies via the rake
-task.
-
-   rake gem:install_dependencies
-
-Always remember that "rake -T" is your friend!
-
-== LICENSE
-
-The MIT License
-
-Copyright (c) 2012 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/data/bad_logging_1.rb

@@ -1,13 +0,0 @@
-
-Logging.configure {
-
-  logger(:root) {
-    level      :info
-    appenders  'bad'
-  }
-
-  appender('bad') {
-    type 'FooBar'
-  }
-
-}  # logging configuration

data/data/bad_logging_2.rb

@@ -1,21 +0,0 @@
-
-Logging.configure {
-
-  logger(:root) {
-    level      :info
-    appenders  'logfile'
-  }
-
-  appender('logfile') {
-    type      'File'
-    level     'DEB'
-    filename  'tmp/temp.log'
-    truncate  true
-    layout {
-      type         'BadLayout'
-      date_method  'to_s'
-      pattern      '[%d] %l  %c : %m\n'
-    }
-  }
-
-}  # logging configuration

data/data/logging.rb

@@ -1,42 +0,0 @@
-
-Logging.configure {
-
-  pre_config {
-    levels      %w[DEB INF PRT WRN ERR FAT]
-    format_as  :inspect
-  }
-
-  logger('A::B::C') {
-    level      'DEB'
-    additive   false
-    trace      false
-    appenders  %w[stderr logfile]
-  }
-
-  logger('yourlogger') {
-    level      'INF'
-    appenders  %w[stderr logfile]
-  }
-
-  appender('stderr') {
-    type   'Stderr'
-    level  'DEB'
-    layout {
-      type       'Basic'
-      format_as  :string
-    }
-  }
-
-  appender('logfile') {
-    type      'File'
-    level     'DEB'
-    filename  'tmp/temp.log'
-    truncate  true
-    layout {
-      type         'Pattern'
-      date_method  'to_s'
-      pattern      '[%d] %l  %c : %m\n'
-    }
-  }
-
-}  # logging configuration

data/data/logging.yaml

@@ -1,63 +0,0 @@
-
-purpose    : TestA
-description: This is the 1st YAML doc
-say        : Hi
-
----
-# *** YAML2LOGGING ***
-logging_config:
-  # define all pre config ...
-  pre_config:
-    define_levels:
-      - DEB
-      - INF
-      - PRT
-      - WRN
-      - ERR
-      - FAT
-    format_as   : inspect
-    root:
-      level     : WRN
-
-  # define all loggers ...
-  loggers:
-    - name      : mylogger
-      level     : DEB
-      additive  : false
-      trace     : false      
-      appenders:
-        - stderr
-        - logfile 
-
-    - name      : yourlogger
-      level     : INF 
-      appenders: 
-        - stderr
-        - logfile 
-
-  # define all appenders (incl. layouts)      
-  appenders:
-    - type          : Stderr
-      name          : stderr 
-      level         : DEB
-      layout:
-        type        : Basic
-        format_as   : string
-
-    - type          : File
-      name          : logfile
-      level         : DEB
-      filename      : 'tmp/temp.log'
-      truncate      : true
-      layout:
-        type        : Pattern
-        date_method : to_s
-        pattern     : '[%d] %l  %c : %m\n'
-  
----
-purpose    : TestB
-description: This is the last YAML doc
-say        : Bye
-
-
-# EOF  

data/data/simple_logging.rb

@@ -1,13 +0,0 @@
-
-Logging.configure {
-
-  logger(:root) {
-    level      :info
-    appenders  'stdout'
-  }
-
-  appender('stdout') {
-    type 'Stdout'
-  }
-
-}  # logging configuration

data/examples/consolidation.rb

@@ -1,83 +0,0 @@
-# :stopdoc:
-#
-# Logging support can be included globally giving all objects in the Ruby
-# space access to a logger instance. This "logger" method invokes
-#
-#    Logging.logger[self]
-#
-# And returns the appropriate logger for the current context.
-#
-# However, there might be times when it is not desirable to create an
-# individual logger for every class and module. This is where the concept of
-# "logger consolidation" comes into play. A ruby namespace can be configured
-# to consolidate loggers such that all classes and modules in that namespace
-# use the same logger instance.
-#
-# Because our loggers are being accessed via the self context, it becomes
-# very easy to turn on debugging on a class-by-class basis (or a
-# module-by-module basis). The trick is to create the debug logger first and
-# then configure the namespace to consolidate all loggers. Since we already
-# created our debug logger, it will be used by the class in question instead
-# of the consolidated namespace logger.
-#
-
-  require 'logging'
-  include Logging.globally
-
-  Logging.logger.root.appenders = Logging.appenders.stdout
-  Logging.logger.root.level = :info
-
-  # we want to debug the "FooBar" module of ActiveRecord
-  Logging.logger['ActiveRecord::FooBar'].level = :debug
-
-  # and we want everything else in ActiveRecord and ActiveResource
-  # to use the same consolidated loggers (one for each namespace)
-  Logging.consolidate 'ActiveRecord', 'ActiveResource'
-
-
-  logger.info 'because we included Logging globally, ' \
-              'we have access to a logger anywhere in our code'
-
-
-  module ActiveRecord
-    logger.info 'even at the module level'
-
-    class Base
-      logger.info 'and at the class level'
-    end
-  end
-
-
-  module ActiveResource
-    logger.info "you'll notice that these log messages " \
-                "are coming from the same logger"
-
-    class Base
-      logger.info "even though the logger is invoked from different classes"
-    end
-
-    class Foo
-      def foo
-        logger.info "that is because ActiveRecord and ActiveResource " \
-                    "are consolidating loggers in their respective namespaces"
-      end
-    end
-    Foo.new.foo
-  end
-
-
-  module ActiveRecord
-    logger.debug 'this debug message will not be logged ' \
-                 '- level is info'
-
-    class Base
-      logger.debug 'and this debug message will not be logged either ' \
-                   '- same logger as above'
-    end
-
-    module FooBar
-      logger.debug 'however, this debug message WILL be logged'
-    end
-  end
-
-# :startdoc:

data/lib/logging/appenders/email.rb

@@ -1,178 +0,0 @@
-
-require 'net/smtp'
-require 'time' # get rfc822 time format
-
-module Logging::Appenders
-
-  # Accessor / Factory for the Email appender.
-  #
-  def self.email( *args )
-    return ::Logging::Appenders::Email if args.empty?
-    ::Logging::Appenders::Email.new(*args)
-  end
-
-  # Provides an appender that can send log messages via email to a list of
-  # recipients.
-  #
-  class Email < ::Logging::Appender
-    include Buffering
-
-    attr_reader :authentication, :to, :port
-    attr_accessor :address, :domain, :from, :subject
-    attr_accessor :user_name, :password, :enable_starttls_auto
-
-    # call-seq:
-    #    Email.new( name, :from => 'me@example.com', :to => 'you@example.com', :subject => 'Whoops!' )
-    #
-    # Create a new email appender that will buffer messages and then send them
-    # out in batches to the listed recipients. See the options below to
-    # configure how emails are sent through you mail server of choice. All the
-    # buffering options apply to the email appender.
-    #
-    # The following options are required:
-    #
-    #  :from - The base filename to use when constructing new log
-    #          filenames.
-    #  :to   - The list of email recipients either as an Array or a comma
-    #          separated list.
-    #
-    # The following options are optional:
-    #
-    #  :subject   - The subject line for the email.
-    #  :address   - Allows you to use a remote mail server. Just change it
-    #               from its default "localhost" setting.
-    #  :port      - On the off chance that your mail server doesn't run on
-    #               port 25, you can change it.
-    #  :domain    - If you need to specify a HELO domain, you can do it here.
-    #  :user_name - If your mail server requires authentication, set the user
-    #               name in this setting.
-    #  :password  - If your mail server requires authentication, set the
-    #               password in this setting.
-    #  :authentication - If your mail server requires authentication, you need
-    #                    to specify the authentication type here. This is a
-    #                    symbol and one of :plain (will send the password in
-    #                    the clear), :login (will send password Base64
-    #                    encoded) or :cram_md5 (combines a Challenge/Response
-    #                    mechanism to exchange information and a cryptographic
-    #                    Message Digest 5 algorithm to hash important
-    #                    information)
-    #  :enable_starttls_auto - When set to true, detects if STARTTLS is
-    #                          enabled in your SMTP server and starts to use it.
-    #
-    # Example:
-    #
-    # Setup an email appender that will buffer messages for up to 1 minute,
-    # and only send messages for ERROR and FATAL messages. This example uses
-    # Google's SMTP server with authentication to send out messages.
-    #
-    #   Logger.appenders.email( 'email',
-    #       :from       => "server@example.com",
-    #       :to         => "developers@example.com",
-    #       :subject    => "Application Error [#{%x(uname -n).strip}]",
-    #
-    #       :address    => "smtp.google.com",
-    #       :port       => 443,
-    #       :domain     => "google.com",
-    #       :user_name  => "example",
-    #       :password   => "12345",
-    #       :authentication => :plain,
-    #       :enable_starttls_auto => true,
-    #
-    #       :auto_flushing => 200,     # send an email after 200 messages have been buffered
-    #       :flush_period  => 60,      # send an email after one minute
-    #       :level         => :error   # only process log events that are "error" or "fatal"
-    #   )
-    #
-    def initialize( name, opts = {} )
-      opts[:header] = false
-      super(name, opts)
-
-      af = opts.getopt(:buffsize) ||
-           opts.getopt(:buffer_size) ||
-           100
-      configure_buffering({:auto_flushing => af}.merge(opts))
-
-      # get the SMTP parameters
-      self.from = opts.getopt :from
-      raise ArgumentError, 'Must specify from address' if @from.nil?
-
-      self.to = opts.getopt :to
-      raise ArgumentError, 'Must specify recipients' if @to.empty?
-
-      self.subject   = opts.getopt :subject, "Message from #{$0}"
-      self.address   = opts.getopt(:server) || opts.getopt(:address) || 'localhost'
-      self.port      = opts.getopt(:port, 25)
-      self.domain    = opts.getopt(:domain, ENV['HOSTNAME']) || 'localhost.localdomain'
-      self.user_name = opts.getopt(:acct) || opts.getopt(:user_name)
-      self.password  = opts.getopt(:passwd) || opts.getopt(:password)
-      self.enable_starttls_auto = opts.getopt(:enable_starttls_auto, false)
-      self.authentication = opts.getopt(:authtype) || opts.getopt(:authentication) || :plain
-    end
-
-    # Close the email appender. If the layout contains a foot, it will not be
-    # sent as an email.
-    #
-    def close( *args )
-      super(false)
-    end
-
-    # If your mail server requires authentication, you need to specify the
-    # authentication type here. This is a symbol and one of :plain (will send
-    # the password in the clear), :login (will send password Base64 encoded)
-    # or :cram_md5 (combines a Challenge/Response mechanism to exchange
-    # information and a cryptographic Message Digest 5 algorithm to hash
-    # important information)
-    #
-    def authentication=( val )
-      @authentication = val.to_s.to_sym
-    end
-
-    # On the off chance that your mail server doesn't run on port 25, you can
-    # change it.
-    #
-    def port=( val )
-      @port = Integer(val)
-    end
-
-    # The list of email recipients. This can either be an Array of recipients
-    # or a comma separated list. A single recipient is also valid.
-    #
-    #   email.to = ['mike@example.com', 'tony@example.com']
-    #   email.to = 'alicia@example.com'
-    #   email.to = 'bob@example.com, andy@example.com, john@example.com'
-    #
-    def to=( val )
-      @to = val.respond_to?(:split) ?  val.split(',') : Array(val)
-    end
-
-
-  private
-
-    # This method is called by the buffering code when messages need to be
-    # sent out as an email.
-    #
-    def canonical_write( str )
-      ### build a mail header for RFC 822
-      rfc822msg =  "From: #{@from}\n"
-      rfc822msg << "To: #{@to.join(",")}\n"
-      rfc822msg << "Subject: #{@subject}\n"
-      rfc822msg << "Date: #{Time.new.rfc822}\n"
-      rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
-
-      rfc822msg = rfc822msg.force_encoding(encoding) if encoding and rfc822msg.encoding != encoding
-      rfc822msg << str
-
-      ### send email
-      smtp = Net::SMTP.new(@address, @port)
-      smtp.enable_starttls_auto if @enable_starttls_auto and smtp.respond_to? :enable_starttls_auto
-      smtp.start(@domain, @user_name, @password, @authentication) { |s| s.sendmail(rfc822msg, @from, @to) }
-      self
-    rescue StandardError, TimeoutError => err
-      self.level = :off
-      ::Logging.log_internal {'e-mail notifications have been disabled'}
-      ::Logging.log_internal(-2) {err}
-    end
-
-  end   # Email
-end   # Logging::Appenders
-