redcar 0.2.9dev

data/lib/logging/data/simple_logging.rb

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

data/lib/logging/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/lib/logging/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/lib/logging/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/lib/logging/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/lib/logging/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:

data/lib/logging/examples/layouts.rb

@@ -0,0 +1,48 @@
+# :stopdoc:
+#
+# The formatting of log messages is controlled by the layout given to the
+# appender. By default all appenders use the Basic layout. It's pretty
+# basic. However, a more sophisticated Pattern layout can be used or one of
+# the Parseable layouts -- JSON or YAML.
+#
+# The available layouts are:
+#
+#   Logging.layouts.basic
+#   Logging.layouts.pattern
+#   Logging.layouts.json
+#   Logging.layouts.yaml
+#
+# In this example we'll demonstrate use of different layouts and setting log
+# levels in the appenders to filter out events.
+#
+
+  require 'logging'
+
+  # only show "info" or higher messages on STDOUT using the Basic layout
+  Logging.appenders.stdout(:level => :info)
+
+  # send all log events to the development log (including debug) as JSON
+  Logging.appenders.rolling_file(
+    'development.log',
+    :age    => 'daily',
+    :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.level = :debug
+
+  log.debug "a very nice little debug message"
+  log.info "things are operating nominally"
+  log.warn "this is your last warning"
+  log.error StandardError.new("something went horribly wrong")
+  log.fatal "I Die!"
+
+# :startdoc:

data/lib/logging/examples/loggers.rb

@@ -0,0 +1,29 @@
+# :stopdoc:
+#
+# Multiple loggers can be created and each can be configured with it's own
+# log level and appenders. So one logger can be configured to output debug
+# messages, and all the others can be left at the info or warn level. This
+# makes it easier to debug specific portions of your code.
+#
+
+  require 'logging'
+
+  # all loggers inherit the log level of the "root" logger
+  # but specific loggers can be given their own level
+  Logging.logger.root.level = :warn
+
+  # similarly, the root appender will be used by all loggers
+  Logging.logger.root.appenders = Logging.appenders.file('output.log')
+
+  log1 = Logging.logger['Log1']
+  log2 = Logging.logger['Log2']
+  log3 = Logging.logger['Log3']
+
+  # you can use strings or symbols to set the log level
+  log3.level = 'debug'
+
+  log1.info "this message will not get logged"
+  log2.info "nor will this message"
+  log3.info "but this message will get logged"
+
+# :startdoc:

data/lib/logging/examples/names.rb

@@ -0,0 +1,43 @@
+# :stopdoc:
+#
+# Loggers and appenders can be looked up by name. The bracket notation is
+# used to find these objects:
+#
+#   Logging.logger['foo']
+#   Logging.appenders['bar']
+#
+# A logger will be created if a new name is used. Appenders are different;
+# nil is returned when an unknown appender name is used. The reason for this
+# is that appenders come in many different flavors (so it is unclear which
+# type should be created), but there is only one type of logger.
+#
+# So it is useful to be able to create an appender and then reference it by
+# name to add it to multiple loggers. When the same name is used, the same
+# object will be returned by the bracket methods.
+#
+# Layouts do not have names. Some are stateful, and none are threadsafe. So
+# each appender is configured with it's own layout.
+#
+
+  require 'logging'
+
+  Logging.appenders.file('Debug File', :filename => 'debug.log')
+  Logging.appenders.growl('Growl Notifier', :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'
+
+  # 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
+  # go lookup the appender by name
+
+  # and now log some messages
+  Logging.logger['Critical'].info 'just keeping you informed'
+  Logging.logger['Critical'].fatal 'WTF!!'
+
+# :startdoc:

data/lib/logging/examples/simple.rb

@@ -0,0 +1,17 @@
+# :stopdoc:
+#
+# Logging provides a simple, default logger configured in the same manner as
+# the default Ruby Logger class -- i.e. the output of the two will be the
+# same. All log messags at "warn" or higher are printed to STDOUT; any
+# message below the "warn" level are discarded.
+#
+
+  require 'logging'
+
+  log = Logging.logger(STDOUT)
+  log.level = :warn
+
+  log.debug "this debug message will not be output by the logger"
+  log.warn "this is your last warning"
+
+# :startdoc: