log4r 1.0.6

data/src/log4r/rdoc/emailoutputter

@@ -0,0 +1,103 @@
+= EmailOutputter
+
+This is an experimental class that sends a number of formatted log events as 
+an RFC 822 email. It should work fine if Net:SMTP doesn't cause any 
+problems. Just in case, create a logger named 'log4r' and give it an 
+outputter to see the logging statements made by this class. If it fails to 
+send email, it will set itself to OFF and stop logging.
+
+In order to use it,
+
+  require 'log4r/outputter/emailoutputter'
+
+== SMTP Configuration
+
+All arguments to Net::SMTP.start are supported. Pass them as hash
+parameters to +new+. The to field is specified as a comma-delimited 
+list of emails (padded with \s* if desired).
+
+An example:
+
+  email_out = EmailOutputter.new 'email_out',
+                     :server=>'localhost',
+                     :port=>25,
+                     :domain=>'somewhere.com',
+                     :from=>'me@foo.bar',
+                     :to=>'them@foo.bar, me@foo.bar, bozo@clown.net',
+                     :subject=>'Log Report'
+
+== LogEvent Buffer
+
+EmailOutputter stores log messages in a buffer. When the buffer reaches a 
+certain number, the <tt>buffsize</tt>, it will send an email containing the 
+contents of the buffer. The default +buffsize+ is 100. To set +buffsize+,
+
+  email_out.buffsize = 1000   # set the buffsize to 1000
+
+== Flush To Send Email
+
+Flushing an EmailOutputter will mail out all the remaining LogEvents.
+This is convenient for systems that encapsulate the shutdown process. It's a 
+good idea to do this for all outputters,
+
+  Outputter.each_outputter {|o| o.flush}
+
+Alternatively, one can invoke flush on the outputter directly,
+  
+  email_out.flush
+
+It's also a good idea to notify the recepient of the email that
+the system is shutting down. Before flushing, log a message
+to the owner of this outputter,
+
+  log_with_email_out.info "The system is shutting down at #{Time.now}"
+
+== Format When?
+
+LogEvents may either be formatted as they come in or as the
+email is being composed. To do the former, specify a value of +true+
+to the hash parameter +formatfirst+. The default is to format 
+during email composition.
+
+  email_out.formatfirst = true     # format as soon as LogEvents are received
+
+== Immediate Notification
+
+EmailOutputter can be configured to flush and send the email whenever the
+logger sees a certain log priority. Use the +immediate_at+ hash parameter
+and specify the levels as a comma-delimited list (like an XML element).
+To trigger an email on FATAL and ERROR,
+
+  email_out.immediate_at = "FATAL, ERROR"   
+
+== Example
+
+A security logger sends email to several folks, buffering up to 25
+log events and sending immediates on CRIT and WARN
+
+  EmailOutputter.new 'security', 
+                     :to => 'bob@secure.net, frank@secure.net',
+                     :buffsize => 25,
+                     :immediate_at => 'WARN, CRIT'
+                     
+== XML Configuration
+
+See log4r/configurator.rb for details. Here's an example:
+
+  <outputter name="security" type="EmailOutputter"
+             buffsize="25" level="ALL">
+    <immediate_at>WARN, CRIT</immediate_at>
+    <server>localhost</server>
+    <from>me@secure.net</from>
+    <to>
+      bob@secure.net, frank@secure.net
+    </to>
+    ...
+  </outputter>
+
+== To Do
+
+This class could use some sophistication, in particular a means to compress
+the logs, a way to set the subject dynamically (probably via a block method),
+and a time trigger. When the time trigger is introduced, a +buffsize+
+of 0 should mean ignore +buffsize+ to determine when to send the email.

data/src/log4r/rdoc/formatter

@@ -0,0 +1,39 @@
+= Formatters
+
+Formatters are responsible for formatting LogEvent data.
+An Outputter owning a Formatter will invoke the 
+Log4r::Formatter#format method prior to writing.
+
+== Available Formatters
+
+* Log4r::BasicFormatter -  default
+* Log4r::PatternFormatter - most flexible. See log4r/formatter/patternformatter.rb
+* Log4r::SimpleFormatter - like BasicFormatter for Strings only (low noise)
+* Log4r::ObjectFormatter - for inspecting objects
+* Log4r::NullFormatter - twirls on its feet and does nothing
+
+= XML Configuration
+
+Specify the Formatter and its class (as +type+) under an 
+<tt><outputter></tt> directive:
+
+  <outputter name="someout" type="sometype">
+    <formatter type="Log4r::BasicFormatter"/>
+  </outputter>
+
+As explained in log4r/configurator.rb, the hash arguments you would normally
+pass to +new+ are specified as <i>XML parameters</i>. Only PatternFormatter
+has any of these.
+
+= Custom Formatting
+
+Building a custom Formatter is extremely easy. Just define a class
+that extends Formatter and override the Formatter#format method.
+Then give it to any interested Outputters. 
+
+If you're interested in setting up your custom formatters in XML,
+please take a look at log4r/configurator.rb.
+
+== Data Available
+
+See Log4r::LogEvent

data/src/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/src/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/src/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.