mtn_log4r 1.1.11

data/lib/log4r/rdoc/log4r

@@ -0,0 +1,89 @@
+= #{version} Log4r API Reference
+
+Welcome to the Log4r API reference. There are two classes of reference,
+the file overview and the class API. They are listed under Files and Classes
+respectively. File overviews cover the use of the Log4r API and some 
+implementation details, whereas class APIs detail the methods available to 
+the various objects.
+
+The code examples in this API assume:
+
+  include Log4r
+
+This file overview covers some of the major concepts in Log4r.
+
+
+== Log Levels
+
+Log4r provides as many levels of logging as desired. Logging levels
+are an ordered set of names ranked by priority. The more important a level is,
+the higher its priority and the more likely we want to see any data associated 
+with it. Log4r provides many ways to filter information by level.
+
+Loggers and Outputters have a level parameter which serves as a level 
+threshold. Any data below this threshold will be ignored by the Logger or
+Outputter. Additionally, Outputters can be set to mask out any particular
+level or collection of levels.
+
+By combining level thresholds with other Log4r features, one can direct any
+set of data to any destination desired in a way that is easy to visualize
+and configure.
+
+=== Default Levels
+
+The default log levels and their priority rankings are:
+
+  DEBUG < INFO < WARN < ERROR < FATAL
+
+=== Custom Levels
+
+You can have as many levels as you desire, with any naming scheme. Log4r
+will automatically define level constants and log method names after
+your custom specification.
+
+Please see log4r/configurator.rb for details.
+
+=== Boundary Levels
+
+There are two special levels, <tt>ALL</tt> and <tt>OFF</tt> which
+denote whether we are logging at all levels or at none. The priority 
+ranks with respect to the logging levels are as follows:
+
+  ALL < logging levels as defined by user < OFF
+
+Thus, setting the level to <tt>ALL</tt> will enable logging at all levels
+whereas <tt>OFF</tt> will turn off logging completely.
+
+== File Overviews
+
+For Loggers::        log4r/logger.rb
+For Outputters::     log4r/outputter/outputter.rb
+For Formatters::     log4r/formatter/formatter.rb
+For configuration::  log4r/configurator.rb
+
+== Principal Classes of Log4r
+
+* Log4r::Logger - Interface to logging
+* Log4r::Outputter - An output destination for a logger.
+* Log4r::Formatter - A means of formatting log data.
+* Log4r::Configurator - A means of configuring Log4r 
+
+== Convenience Classes
+
+Log4r provides several convenience Outputters and Formatters. Please
+look at the file overviews of those classes for more details.
+
+== Remote Logging
+
+Log4r provides a way to send log events over a network. See log4r/logserver.rb
+for details.
+
+== What's Going on Inside?
+
+Log4r has an internal logger which records much of what goes on inside. To see 
+the output, define a Logger named 'log4r' and give it an Outputter of some
+sort. It logs only at the lowest and highest priorities. That would be
+DEBUG and FATAL for the standard setup.
+
+It is essential to view this data when using certain classes, like 
+Log4r::LogServer and Log4r::EmailOutputter.

data/lib/log4r/rdoc/logger

@@ -0,0 +1,175 @@
+= Loggers
+
+Loggers provide the interface for logging in Log4r. To create a logger,
+first come up with a name for it. Good choices include the name of the
+class using it, a service name, or the name of the file. 
+
+To create a logger named 'mylog':
+
+  Logger.new('mylog')
+
+After creating a logger, it is stashed in a repository. The logger may
+be retrieved at any time:
+
+  Logger['mylog']              # get mylog back
+
+It will return nil if the logger is not found. Alternatively, if an
+Exception is desired when a nonexistant logger is referenced, the Logger#get
+command can be used:
+
+  Logger.get('boguslog')       # raises NameError if it doesn't exist
+
+== Manipulating a Logger's Outputters
+
+Loggers start out with no outputters. They can be added using the
+Logger#add method or set directly by modifying the Loggers#outputters array:
+
+  mylog = Logger['mylog']
+
+  # assume we've created Outputters out1 through out4
+  mylog.outputters = out1, out2 
+  mylog.add(out3, out4)
+  mylog.each_outputter {|o| o.flush}
+  
+  # assume out5 through out7 have names 'out5' through 'out7' resp.
+  mylog.outputters = 'out5', 'out6'
+  mylog.add('out7')
+  mylog.remove('out5','out7')
+
+Please see log4r/outputter/outputter.rb and Log4r::Outputter for more about
+outputters.
+
+== Logging Methods
+
+To log something at a certain priority, use the logging method named
+after the lowercased priority level name:
+
+  mylog.warn "This is a message with priority WARN"
+  mylog.fatal "A FATAL message"
+
+Blocks can also be logged:
+
+  mylog.warn {"This is also a message with priority WARN"}
+  mylog.debug do
+    # some complicated string magic
+    return result
+  end
+
+The primary difference is that the block doesn't get called unless
+the Logger can log at that level. It is useful for doing computationaly
+expensive things at a log event.
+
+== Query Methods
+
+To ask Log4r whether it is capable of logging a certain level:
+
+  mylog.warn?   # are we logging WARN?
+  mylog.fatal?  # how about FATAL?
+
+Query methods and blocks accomplish the same thing:
+
+  mylog.warn "don't evaluate unless WARN is on" if mylog.warn?
+  mylog.warn {"don't evaluate unless WARN is on"}
+
+== What About the Special Levels?
+
+<tt>ALL</tt> and <tt>OFF</tt> can be querried, but not logged:
+
+  log.off?                    # true iff level is OFF
+  log.all?                    # true iff level is ALL
+  log.all "Try to log"        => Method not defined. (NameError)
+
+== Custom Levels and Method Names
+
+Suppose we've set up Log4r with the custom levels:
+
+  Foo < Bar < Baz
+
+As one might expect, the logging methods are named after them:
+
+  log.bar "something"        # log at custom level Bar
+  log.bar?                   # are we logging at level Bar?
+
+= Logger Inheritance
+
+Normally, when a logger is created, its parent is set to RootLogger.
+If a Logger's level isn't specified at creation, it will inherit the level 
+of its parent.
+
+To specify an ancestors of a logger besides RootLogger, include the names 
+of the ancestors in order of ancestry and delimited by 
+Log4r::Log4rConfig::LoggerPathDelimiter. For example, if the 
+delimiter is the default <tt>::</tt>, our logger is 'me' 
+and its ancestors are 'cain', 'grandpa', and 'pa', we create the logger 
+like so:
+
+  Logger.new('cain::grandpa::pa::me')
+
+This string is split into three compontents which can be used
+by a Formatter to avoid parsing the name:
+
+Logger#fullname::   The whole enchilada: 'cain::grandpa::pa::me'
+Logger#name::       Just 'me'
+
+To get this logger back from the repository,
+
+  Logger['cain::grandpa::pa::me']
+
+= Outputter Additivity
+
+By default, Logger Outputters are <b>additive</b>. This means that
+a log event will also be sent to all of a logger's ancestors. To 
+stop this behavior, set a logger's +additive+ to false.
+
+  Logger['foo'].additive = false
+
+A Logger's level, additivity and trace can be changed dynamically,
+but this is an expensive operation as the logging methods have to be
+redefined.
+
+= RootLogger
+
+Log4r::RootLogger is the ancestor of all loggers. Its level defines the global
+logging threshold. Any loggers created <b>after</b> RootLogger's level is
+set will not log below that level. By default, RootLogger's level is set
+to <tt>ALL</tt>
+
+RootLogger is a singleton which gets created automaticallay. It can be
+retrieved at any time with Logger.root, Logger.global,
+Logger['root'] or Logger['global'].
+
+== Global Level
+
+Suppose we want _everything_ to ignore events less than FATAL. We can
+accomplish this easily:
+
+  Logger.global.level = FATAL
+
+Just be sure to set this before any other Loggers or Outputters are defined.
+
+== RootLogger Does Nothing
+
+RootLogger itself behaves as if its level were permanently set to 
+<tt>OFF</tt>, thus making it a sort of null object.
+
+= XML Configuration
+
+Please see log4r/configurator.rb for an overview of XML configuratoin.
+
+It's easy to configure a Logger in XML. The following example should be
+sufficient:
+
+    ...
+    <logger name="papa::mylog" level="DEBUG" trace="true">
+      <additive>false</additive>
+      <outputter>stdout</outputter>
+      <outputters>stderr, dancer, doner, blitzen</outputters>
+    </logger>
+    <logger name="papa" outputters="stderr, stdout"/>
+    ...
+
+The element +outputter+ can occur multiple times, but cannot be an attribute 
+of +logger+. That is, it is not an <i>XML directive</i>. However, the element 
++outputters+ is an <i>XML directive</i>, as are all the others.
+
+For more examples, check the <tt>examples</tt> directory in the Log4r package.

data/lib/log4r/rdoc/logserver

@@ -0,0 +1,85 @@
+= Remote Logging 
+
+Want to use Log4r over a network? No problem! A Log4r::RemoteOutputter will
+send its LogEvents to a Log4r::LogServer. These two classes are as easy to
+set up and use as the rest of Log4r. 
+
+== Use ROMP
+
+There is one catch though: ROMP is required to use this service. It is a
+DRb-like system with superb performance and better features. Get ROMP at 
+http://rubystuff.org/romp/
+
+== LogServer
+
+LogServer is simply a kind of Logger which embeds a ROMP::Server. Like a
+normal Logger, you can give it Outputters, set its level and so on. Its
+logging methods are accessible over a network and are called by a 
+RemoteOutputter on another host.
+
+=== LogServer Setup
+
+Setup is easy. First,
+
+  require 'log4r/logserver'
+
+The following sets up a LogServer named 'central' on localhost port 9999:
+
+  LogServer.new('central', 'tcpromp://localhost:9999')
+
+We manipulate it and give it outputters as normal:
+
+  serv = Logger['central']              # grab our new LogServer
+  serv.add 'stdout'                     # make it log to $stdout
+
+== RemoteOutputter
+
+RemoteOutputter is simply a kind of Outputter that embeds a ROMP::Client. When 
+RemoteOutputter gets a LogEvent, it will forward it to whatever LogServer it's 
+connected to. In essence, RemoteOutputter behaves like a Logger that is
+forwarding a LogEvent to another Logger (as is done in hierarchical logging).
+
+=== RemoteOutputter Setup
+
+First,
+
+  require 'log4r/outputter/remoteoutputter'
+
+Unlike typical outputters, RemoteOutputter doesn't do any formatting. That's
+up to the LogServer's outputters. Otherwise, RemoteOutputter can be
+set up as usual. The ROMP uri of the LogServer must be specified.
+
+  RemoteOutputter.new 'client', :uri=>'tcpromp://localhost:9999'
+
+=== Using RemoteOutputter
+
+Give our new RemoteOutputter to a logger:
+
+  mylog = Logger['mylog']
+  mylog.add 'client'
+
+Now, whenever mylog generates a LogEvent, LogServer should get a copy. Doing
+the following:
+
+  mylog.info "This is a message from 'mylog'"
+
+Produces this output on LogServer's console:
+
+  INFO mylog: This is a message from 'mylog'
+
+== XML Configuration
+
+RemoteOutputter is set up like normal Outputters. LogServer is set up
+like a normal Logger, but with an element name of logserver instead of
+logger:
+
+  <log4r_config>
+    <logserver name="name" uri="tcpromp://localhost:9999">
+    ...
+
+== Debugging
+
+It is recommended to set up a logger named 'log4r' on both the server and
+client to see what LogServer and RemoteOutputter are up to. Both of the classes
+use Log4r's internal logging to report any problems. See the section
+<b>What's Going on Inside?</b> in log4r.rb for more info.

data/lib/log4r/rdoc/outputter

@@ -0,0 +1,108 @@
+= Outputters
+
+An Outputter is a logging destination with a particular way to format
+data. It has a level threshold and a flexible level mask.
+
+Outputters must have names.
+
+== Level Threshold
+
+Outputters have their own level thresholds that default to <tt>root</tt> 
+level. They will not write any log events with a rank less than their
+threshold.
+
+== Level Mask
+
+Alternatively, an Outputter can be told to log specific levels only:
+
+  o = StdoutOutputter.new 'console'
+  o.only_at DEBUG, FATAL         # only DEBUG and FATAL get written 
+
+== Outputter Repository
+
+When outputters are created, they store themselves in an Outputter
+repository similar to the Logger repository. 
+
+  StdoutOutputter.new 'console'   => Create 'console' outputter
+  Outputter['console']            => Get it back from the stash.
+
+== Formatter
+
+An outputter has a format defined by its Formatter. If no Formatter
+is specified, DefaultFormatter will be used.
+
+== Outputter is Abstract
+
+The basic Outputter class is both abstract and a null object.
+
+== Interesting Outputters
+
+* log4r/outputter/syslogoutputter.rb - Logs to syslog
+* log4r/outputter/emailoutputter.rb - Email logs
+* log4r/logserver.rb - For remote logging
+
+== Subclasses
+
+* Log4r::IOOutputter - for any IO object
+* Log4r::StdoutOutputter - $stdout
+* Log4r::StderrOutputter - $stderr
+* Log4r::FileOutputter - log to a file
+* Log4r::RollingFileOutputter - log to a file and split it as it grows
+* Log4r::SyslogOutputter - logs to syslog
+* Log4r::EmailOutputter - email logs
+* Log4r::RemoteOutputter - for remote logging
+
+== Default Outputters
+
+Two outputters named 'stdout' and 'stderr' are created automatically at
+the root level. They are nice shortcuts.
+
+  Outputter['stdout'] => 'stdout'
+  Outputter['stderr'] => 'stderr'
+  Outputter.stdout    => 'stdout'
+  Outputter.stderr    => 'stderr'
+
+== Configuring
+
+Outputters must have names and receive hash arguments. The parameter name
+for the hash args can be either a symbol or a string. All defined outputters
+accept <tt>:level</tt> and <tt>:formatter</tt> arguments. For arguments 
+specific to a convenience Outputter, please look at the class description.
+
+The level threshold, the levels to log at (only_at) and formatter can be
+changed dynamically using the <tt>=</tt> methods.
+
+As a collective example of all this, here are various ways to set up an 
+IOOutputter:
+
+  IOOutputter.new ExoticIO.new 'exotic', 'level' => WARN, 
+                  :formatter => MyFormatter.new
+  # an equivalent way:
+  o = IOOutputter.new ExoticIO.new 'exotic'
+  o.level = WARN
+  o.formatter = MyFormatter         # we can specify just the class
+  o.only_at = THIS, THAT
+
+== XML Configuration
+
+Specify outputters as children of <tt><log4r_config></tt>:
+
+  <log4r_config>
+    <outputter name="myout" type="Log4r::StdoutOutputter">
+      <only_at>DEBUG, INFO</only_at>
+    </outputter>
+    <outputter name="file" level="WARN">
+      <type>FileOutputter</type>
+      <filename>#{logpath}/file.log</filename>
+      <trunc>false</trunc>
+    </outputter>
+    ...
+
+As explained in log4r/configurator.rb, the hash arguments you would normally
+pass to <tt>new</tt> are specified as <i>XML parameters</i>.
+It is given an IO object to write 
+to, a Formatter to call, and, optionally, levels to write at.
+
+Outputters invoke print then flush on the wrapped IO object.
+If the IO chokes, the Outputter will close the IO and set its
+level to <tt>OFF</tt>.

data/lib/log4r/rdoc/patternformatter

@@ -0,0 +1,128 @@
+= PatternFormatter
+
+PatternFormatter offers complete control over the appearance of
+Log4r log events without having to write custom Formatter classes.
+In order to take advantage of PatternFormatter, some familarity with
+Kernel#sprintf or the C printf function is recommended. For time formatting,
+please look at Time.strftime.
+
+PatternFormatter accepts three hash arguments:
+
+<tt>pattern</tt>::       Log event format string.
+<tt>date_pattern</tt>::  Date format string.
+<tt>date_method</tt>::   <tt>Time</tt> method to call (instead of using date_pattern).
+
+
+The <tt>pattern</tt> format string is something like "%l [%d] %80M", 
+which resembles a pattern one would normally pass to Kernel#sprintf. However, 
+the directives are specific to Log4r. Before we go on, let's cover some
+terminology.
+
+== Terminology
+
+[<b>%</b>]  The directive identifier. Everything after this up to and 
+            including one of the <em>directive letters</em> defines a 
+            <em>directive</em>.
+[<b>directive letter</b>]  
+  Letters in the set <tt>[cCdtmMl%]</tt>. These 
+  identify what kind of data we're interested in. 
+  They are detailed below.
+[<b>format directive</b>] 
+  The numbers and assorted symbols that appears 
+  between <b>%</b> and a <em>directive letter</em>
+  is a format directive. It is comprised of an
+  integer specifying the field width followed 
+  optionally by a period and an integer specifying 
+  the precision. The field width is the minimum 
+  number of characters to copy from the data string 
+  while the precision is the maximum number to copy. 
+  If the field width is preceded by a - sign, the 
+  data will be left-justified. Otherwise, it is 
+  right-justified.
+[<b>directive</b>]  
+  A statement that says, "I want this data to appear with 
+  this (optional) particular format." A directive starts 
+  with a <b>%</b> and is followed by a format directive and 
+  terminates in a directive letter.
+
+== What the Directive Letters mean
+
+[<b>c</b>]  Produces a logger's name. Fast.
+[<b>C</b>]  Produces a logger's full name. Fast.
+[<b>d</b>]  Produces the time in a format specified by <b>date_pattern</b> or
+            by <b>date_method</b>. If neither is specified, the default will 
+            be used (ISO8601). Slow.
+[<b>t</b>]  Produces the file and line number of the log event. The 
+            appearance varies by Ruby version, but it is the same output 
+            returned by Kernel#caller[0]. Slow.
+[<b>m</b>] The non-inspected log message. That is, to_s called on the object 
+           passed into a log method. Fast.
+[<b>M</b>] The message formatted by the <tt>format_object</tt> method in 
+           BasicFormatter. It will pretty-print Exceptions, print Strings
+           and inspect everything else. Slow.
+[<b>l</b>] The name of the level. That's l as in Lambda. Fast.
+[<b>%</b>] %% just prints a %. Any formatting is <em>probably</em> ignored. 
+           Fast.
+
+== Examples of directives:
+
+
+[<b>%d</b>]    Prints out the date according to our date_pattern or 
+               date_method. By default, it looks like this: 2001-01-12 13:15:50
+[<b>%.120m</b>]  Prints out at most 120 characters of the log message.
+[<b>%15t</b>]    Prints the execution trace and pads it on the left with 
+                 enough whitespace to make the whole thing 15 chars.
+
+== Pattern String
+
+A pattern string is simply a bunch of directives combined with the desired
+format. For instance, to show the level in brackets followed by the date
+and then the log message trimmed to 15 characters, we use the following
+pattern:
+ 
+  "[%l] %d :: %.15m"     #=>     [DEBUG] 2001-01-12 13:15:50 :: This is a messa
+ 
+To create a PatternFormatter with this format:
+ 
+  p = PatternFormatter.new(:pattern => "[%l] %d :: %.15m")
+ 
+== Formatting time
+ 
+To format time, do one of the following:
+ 
+* Specify a date_pattern
+* Specify what class method of Ruby's <tt>Time</tt> class to call.
+* Use the default format
+ 
+If neither date_pattern nor date_method is specified, the default date
+format will be used. Currently, that would be ISO8601,
+ 
+The date_pattern is exactly what one would pass to <tt>Time.strftime</tt>.
+To specify a date_pattern, pass
+<tt>:date_pattern=>"pattern"</tt> to PatternFormat.new.
+ 
+Alternatively, date_method can be specified to produce the output of
+a specific <tt>Time</tt> method, such as <tt>usec</tt> or <tt>to_s</tt> 
+or any other zero argument <tt>Time</tt> method that produces a time. More 
+precisely, the method to call will be invoked on <tt>Time.now</tt>. 
+To specify a date_method, pass <tt>:date_method=>'methodname'</tt> (or a 
+Symbol equivalent) to <tt>PatternFormatter.new</tt>.
+
+= XML Configuration
+
+As explained in log4r/configurator.rb, the hash arguments to PatternFormatter
+are <i>XML parameters</i>. Here's an example:
+
+  <formatter type="PatternFormatter" pattern="[%l] %d :: %.15m">
+    <date_method>usec</date_method>
+  </formatter>
+ 
+= Performace considerations
+ 
+The performance impact of using a particular directive letter is noted in
+the <b>What the Directives Letters mean</b> section.
+ 
+The performance impact of time formatting merits special attention. If you
+aren't aware yet, the Time class is kind of a kludge. Time.now.usec happens
+to be faster than Time.now. If you're concerned about performance, please
+profile the various time methods and patterns.

data/lib/log4r/rdoc/scribeoutputter

@@ -0,0 +1,16 @@
+= ScribeOutputter
+
+A ScribeOutputter transforms a Log4r::LogEvent into an event passed to Scribe. The user can configure the outputter with
+the host and port of the scribe scribe server.
+
+== Usage
+
+To use,
+  <tt>require 'log4r'</tt>
+
+An example,
+
+  require 'log4r'
+
+  logger = Log4r::ScribeOutputter.new('name', '127.0.0.1', 1463)
+  logger.debug("Hello World")

data/lib/log4r/rdoc/syslogoutputter

@@ -0,0 +1,29 @@
+= SyslogOutputter
+
+A SyslogOutputter transforms a Log4r::LogEvent into a call to syslog().
+Since syslog has its own formatting system, log4r formatters are ignored. 
+
+== Usage
+
+To use, 
+
+  <tt>require 'log4r/outputter/syslogoutputter'</tt>
+
+An example,
+
+  require 'log4r'
+  require 'log4r/outputter/syslogoutputter'
+
+  syslog = Log4r::SyslogOutputter.new("name", 'logopt'=>#, 'facility'=>#)
+  syslog.err("this is an ERR message")
+
+The output in <tt>/var/logs/syslog</tt> (Debian) is,
+
+  Sep  3 11:43:06 tiphares sys[1603]: this is an ERR message
+
+The hash arguments +logoptions+ and +facility+ are passed to 
+<tt>Syslog.open</tt>. The
+defaults are <tt>LOG_PID | LOG_CONS</tt> and <tt>LOG_USER</tt> respectively.
+
+This is a first try implementation. It works well. Please report 
+any bugs and fixes.

data/lib/log4r/rdoc/win32eventoutputter

@@ -0,0 +1,7 @@
+= Win32EventOutputter
+
+THIS IS A DEVELOPMENT VERSION AND IS NOT READY FOR USE
+INFACT, IT MAY NEVER BE READY FOR USE, AS TRYING TO INTERACT
+WITH THE WIN32 EVENTLOG API REQUIRES USER INTERVENTION TO LOOKUP
+event_id AND category CODES THAT THIS LIBRARY CANNOT KNOW A PRIORI
+

data/lib/log4r/rdoc/yamlconfigurator

@@ -0,0 +1,20 @@
+= Configuring Log4r with Log4r::YamlConfigurator
+
+The YamlConfigurator class allows one to set up Log4r via YAML.
+It is used almost exactly as Log4r::Configurator and has the same features,
+
+  ycfg = YamlConfigurator    # handy shorthand
+  ycfg['foo'] = bar          # replaces instances of #{foo} in the YAML with bar
+  ycfg.load_yaml_file('foo.yaml')
+
+Ruby 1.7 and 1.8 comes with a YAML parser. Hence, YAML can be used
+to configure Log4r out of the box.
+
+A comprehensive example of a Log4r YAML configuration is provided in the 
+examples directory.
+
+To use this class:
+
+  require 'log4r/yamlconfigurator'
+
+Thanks to Andreas Hund for making this possible.