sgeorgi-logging 1.4.2

data/data/logging.rb

@@ -0,0 +1,42 @@
+
+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

@@ -0,0 +1,63 @@
+
+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

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

data/examples/appenders.rb

@@ -0,0 +1,47 @@
+# :stopdoc:
+#
+# Appenders are used to output log events to some logging destination. The
+# same log event can be sent to multiple desitnations by associating
+# multiple appenders with the logger.
+#
+# The following is a list of all the available appenders and a brief
+# 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
+#   Stderr        appends to STDERR
+#   StringIo      writes to a StringIO instance (useful for testing)
+#   Syslog        outputs to syslogd (not available on all systems)
+#
+# 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
+#   Logging.appenders.stderr
+#   Logging.appenders.string_io
+#   Logging.appenders.syslog
+#
+
+  require 'logging'
+
+  log = Logging.logger['example']
+  log.add_appenders(
+      Logging.appenders.stdout,
+      Logging.appenders.file('development.log')
+  )
+  log.level = :debug
+
+  # These messages will be logged to both the log file and to STDOUT
+  log.debug "a very nice little debug message"
+  log.warn "this is your last warning"
+
+# :startdoc:

data/examples/classes.rb

@@ -0,0 +1,41 @@
+# :stopdoc:
+#
+# The Logging framework is very good about figuring out predictable names
+# for loggers regardless of what object is used to create them. The name is
+# the class name or module name of whatever is passed to the logger bracket
+# method. The following lines all return the exact same logger instance:
+#
+#    ary = Array.new
+#    Logging.logger[ary]
+#    Logging.logger[Array]
+#    Logging.logger['Array']
+#    Logging.logger[:Array]
+#
+# So, if you want each class to have it's own logger this is very easy to
+# do.
+#
+
+  require 'logging'
+
+  Logging.logger.root.appenders = Logging.appenders.stdout
+  Logging.logger.root.level = :info
+
+  class Foo
+    attr_reader :log
+    def initialize() @log = Logging.logger[self]; end
+  end
+
+  class Foo::Bar
+    attr_reader :log
+    def initialize() @log = Logging.logger[self]; end
+  end
+
+  foo = Foo.new.log
+  bar = Foo::Bar.new.log
+
+  # you'll notice in these log messages that the logger names were taken
+  # from the class names of the Foo and Foo::Bar instances
+  foo.info 'this message came from Foo'
+  bar.warn 'this is a warning from Foo::Bar'
+
+# :startdoc:

data/examples/consolidation.rb

@@ -0,0 +1,83 @@
+# :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/examples/fork.rb

@@ -0,0 +1,37 @@
+# :stopdoc:
+#
+# Because of the global interpreter lock, Kernel#fork is the best way
+# to acheive true concurrency in Ruby scripts. However, there are pecularities
+# when using frok and passing file descriptors between process. These
+# pecularities affect the logging framework.
+#
+# In short, always reopen file descriptors in the child process after fork has
+# been called. The RollingFile appender uses flock to safely coordinate the
+# rolling of the log file when multiple processes are writing to the same
+# file. If the file descriptor is opened in the parent and multiple children
+# are forked, then each child will use the same file descriptor lock; when one
+# child locks the file any other child will also have the lock. This creates a
+# race condition in the rolling code. The solution is to reopen the file to
+# obtain a new file descriptor in each of the children.
+#
+
+  require 'logging'
+
+  log = Logging.logger['example']
+  log.add_appenders(
+      Logging.appenders.rolling_file('roller.log', :age => 'daily')
+  )
+  log.level = :debug
+
+  # Create four child processes and reopen the "roller.log" file descriptor in
+  # each child. Now log rolling will work safely.
+  4.times do
+    fork {
+      Logging.reopen
+      log.info "This is child process #{Process.pid}"
+    }
+  end
+
+  log.info "This is the parent process #{Process.pid}"
+
+# :startdoc:

data/examples/formatting.rb

@@ -0,0 +1,51 @@
+# :stopdoc:
+#
+# Any Ruby object can be passed to the log methods of a logger. How these
+# objects are formatted by the Logging framework is controlled by a global
+# "format_as" option and a global "backtrace" option.
+#
+# The format_as option allows objects to be converted to a string using the
+# standard "to_s" method, the "inspect" method, or the "to_yaml" method
+# (this is independent of the YAML layout). The format_as option can be
+# overridden by each layout as desired.
+#
+#   Logging.format_as :string   # or :inspect or :yaml
+#
+# Exceptions are treated differently by the logging framework. The Exception
+# class is printed along with the message. Optionally, exception backtraces
+# can be included in the logging output; this option is enabled by default.
+#
+#   Logging.backtrace false
+#
+# The backtrace can be enabled or disabled for each layout as needed.
+#
+
+  require 'logging'
+
+  Logging.format_as :inspect
+  Logging.backtrace false
+
+  Logging.appenders.stdout(
+    :layout => Logging.layouts.basic(:format_as => :yaml)
+  )
+
+  Logging.appenders.stderr(
+    :layout => Logging.layouts.basic(:backtrace => true)
+  )
+
+  log = Logging.logger['foo']
+  log.appenders = %w[stdout stderr]
+
+  # these log messages will all appear twice because of the two appenders -
+  # STDOUT and STDERR - but the interesting thing is the difference in the
+  # output
+  log.info %w[An Array Of Strings]
+  log.info({"one"=>1, "two"=>2})
+
+  begin
+    1 / 0
+  rescue => err
+    log.error err
+  end
+
+# :startdoc:

data/examples/hierarchies.rb

@@ -0,0 +1,73 @@
+# :stopdoc:
+#
+# Loggers exist in a hierarchical relationship defined by their names. Each
+# logger has a parent (except for the root logger). A logger can zero or
+# more children. This parent/child relationship is determined by the Ruby
+# namespace separator '::'.
+#
+#   root
+#   |-- Foo
+#   |   |-- Foo::Bar
+#   |   `-- Foo::Baz
+#   |-- ActiveRecord
+#   |   `-- ActiveRecord::Base
+#   |-- ActiveSupport
+#   |   `-- ActiveSupport::Base
+#   `-- Rails
+#
+# A logger inherits its log level from its parent. This level can be set for
+# each logger in the system. Setting the level on a logger affects all it's
+# children and grandchildren, etc. unless the child has it's own level set.
+#
+# Loggers also have a property called "additivity", and by default it is set
+# to true for all loggers. This property enables a logger to pass log events
+# up to its parent.
+#
+# If a logger does not have an appender and its additivity is true, it will
+# pass all log events up to its parent who will then try to send the log
+# event to its appenders. The parent will do the same thing, passing the log
+# event up the chain till the root logger is reached or some parent logger
+# has its additivity set to false.
+#
+# So, if the root logger is the only one with an appender, all loggers can
+# still output log events to the appender because of additivity. A logger
+# will ALWAYS send log events to its own appenders regardless of its
+# additivity.
+#
+# The show_configuration method can be used to dump the logging hierarchy.
+#
+
+  require 'logging'
+
+  Logging.logger.root.level = :debug
+
+  foo = Logging.logger['Foo']
+  bar = Logging.logger['Foo::Bar']
+  baz = Logging.logger['Foo::Baz']
+
+  # configure the Foo logger
+  foo.level = 'warn'
+  foo.appenders = Logging.appenders.stdout
+
+  # since Foo is the parent of Foo::Bar and Foo::Baz, these loggers all have
+  # their level set to warn
+
+  foo.warn 'this is a warning, not a ticket'
+  bar.info 'this message will not be logged'
+  baz.info 'nor will this message'
+  bar.error 'but this error message will be logged'
+
+  # let's demonstrate additivity of loggers
+
+  Logging.logger.root.appenders = Logging.appenders.stdout
+
+  baz.warn 'this message will be logged twice - once by Foo and once by root'
+
+  foo.additive = false
+  bar.warn "foo is no longer passing log events up to it's parent"
+
+  # let's look at the logger hierarchy
+  puts '='*76
+  Logging.show_configuration
+
+# :startdoc: