mtn_log4r 1.1.11

data/lib/log4r/outputter/syslogoutputter.rb

@@ -0,0 +1,130 @@
+# :include: ../rdoc/syslogoutputter
+#
+# Version:: $Id$
+# Author:: Steve Lumos
+# Author:: Leon Torres
+
+require 'log4r/formatter/formatter'
+require 'log4r/outputter/outputter'
+require 'log4r/configurator'
+require 'syslog'
+
+module Log4r
+
+  SYSLOGNAMES = Hash.new
+
+  class SyslogOutputter < Outputter
+    include Syslog::Constants
+
+    # maps default log4r levels to syslog priorities (logevents never see ALL and OFF)
+    # SYSLOG Levels are:
+    #  "DEBUG"  => Syslog::LOG_DEBUG
+    #  "INFO"   => Syslog::LOG_INFO
+    #  "NOTICE" => Syslog::LOG_NOTICE
+    #  "WARN"   => Syslog::LOG_WARN
+    #  "ERROR"  => Syslog::LOG_ERROR
+    #  "FATAL"  => Syslog::LOG_FATAL
+    #  "ALERT"  => Syslog::LOG_ALERT
+    #  "EMERG"  => Syslog::LOG_EMERG
+    SYSLOG_LEVELS_MAP = {
+      "DEBUG"  => LOG_DEBUG, 
+      "INFO"   => LOG_INFO, 
+      "NOTICE" => LOG_NOTICE,  # by default NOTICE is not in log4r
+      "WARN"   => LOG_WARNING, 
+      "ERROR"  => LOG_ERR, 
+      "FATAL"  => LOG_CRIT,
+      "ALERT"  => LOG_ALERT,   # by default ALERT is not in log4r
+      "EMERG"  => LOG_EMERG,   # by default EMERG is not in log4r
+    }
+
+    # mapping from Log4r default levels to syslog, by string name
+    # "DEBUG" => "DEBUG"
+    #  "INFO"   => "INFO" 
+    #  "WARN"   => "WARN"
+    #  "ERROR"  => "ERROR" 
+    #  "FATAL"  => "FATAL"
+    SYSLOG_LOG4R_MAP = {
+      "DEBUG"  => "DEBUG", 
+      "INFO"   => "INFO", 
+      "WARN"   => "WARN", 
+      "ERROR"  => "ERROR", 
+      "FATAL"  => "FATAL"
+      # "NOTICE" => "INFO",      # by default NOTICE is not in log4r
+      # "ALERT"  => "FATAL",     # by default ALERT is not in log4r
+      # "EMERG"  => "FATAL"      # by default EMERG is not in log4r
+    }
+
+    @levels_map = SYSLOG_LOG4R_MAP
+
+    # There are 3 hash arguments
+    #
+    # [<tt>:ident</tt>]     syslog ident, defaults to _name
+    # [<tt>:logopt</tt>]    syslog logopt, defaults to LOG_PID | LOG_CONS
+    # [<tt>:facility</tt>]  syslog facility, defaults to LOG_USER
+    def initialize(_name, hash={})
+      super(_name, hash)
+      ident = (hash[:ident] or hash['ident'] or _name)
+      logopt = (hash[:logopt] or hash['logopt'] or LOG_PID | LOG_CONS).to_i
+      facility = (hash[:facility] or hash['facility'] or LOG_USER).to_i
+      map_levels_by_name_to_syslog()
+      if ( Syslog.opened? ) then
+	Logger.log_internal { "Syslog already initialized, to alter, " +
+	  "you must close first"}
+      end
+      @syslog = ( Syslog.opened? ) ? Syslog : Syslog.open(ident, logopt, facility)
+    end
+
+    def closed?
+      return !@syslog.opened?
+    end
+
+    def close
+      @syslog.close unless @syslog.nil?
+      @level = OFF
+      OutputterFactory.create_methods(self)
+      Logger.log_internal {"Outputter '#{@name}' closed Syslog and set to OFF"}
+    end
+
+    # A single hash argument that maps custom names to syslog names
+    # 
+    # [<tt>levels_map</tt>]	A map that will create a linkage between levels
+    # 				in a hash and underlying syslog levels.
+    # 				By default, these are direct mapping of the log4r
+    # 				levels (e.g. "DEBUG" => "DEBUG")
+    # 				If you have defined your own custom levels, you
+    # 				should provide this underlying mapping, otherwise
+    # 				all messages will be mapped to the underlying syslog
+    # 				level of INFO by default.
+    # 				e.g.
+    # 				You have created custom levels called:
+    # 				<tt>Configurator.custom_levels "HIGH", "MEDIUM", "LOW"</tt>
+    # 				To map these to 'equivilent' syslog levels, after instantiatin
+    # 				a syslogoutputter:
+    # 				<tt>SyslogOutputter.map_levels_by_name_to_syslog(
+    # 				{ "HIGH" => "ALERT", "MEDIUM" => "WARN", "LOW" => "INFO" }
+    # 				)</tt>
+    def map_levels_by_name_to_syslog( lmap = SYSLOG_LOG4R_MAP )
+      @levels_map = lmap
+    end
+
+    def get_levels_map()
+      return @levels_map
+    end
+
+    private
+
+    def canonical_log(logevent)
+      pri = SYSLOG_LEVELS_MAP[@levels_map[LNAMES[logevent.level]]] rescue pri = LOG_INFO
+      o = format(logevent)
+      if o.kind_of? Exception then
+	msg = "#{o.class} at (#{o.backtrace[0]}): #{o.message}"
+      elsif o.respond_to? :to_str then
+	msg = o.to_str
+      else
+	msg = o.inspect
+      end
+
+      @syslog.log(pri, '%s', msg)
+    end
+  end
+end

data/lib/log4r/outputter/udpoutputter.rb

@@ -0,0 +1,53 @@
+# :include: ../rdoc/outputter
+#
+# == Other Info
+#
+# Version:: $Id$
+# Author:: Leon Torres <leon@ugcs.caltech.edu>
+
+require "log4r/outputter/outputter"
+require 'log4r/staticlogger'
+require "socket"
+
+module Log4r
+
+  class UDPOutputter < Outputter
+    attr_reader :host, :port
+    attr_accessor :udpsock
+     
+    def initialize(_name, hash={})
+      super(_name, hash)
+      @host = (hash[:hostname] or hash["hostname"])
+      @port = (hash[:port] or hash["port"])
+
+      begin 
+	Logger.log_internal {
+	  "UDPOutputter will send to #{@host}:#{@port}"
+	}
+	@udpsock = UDPSocket.new
+	@udpsock.connect( @host, @port )
+      rescue Exception => e
+	Logger.log_internal(ERROR) {
+	  "UDPOutputter failed to create UDP socket: #{e}"
+	}
+	Logger.log_internal {e}
+	self.level = OFF
+	raise e
+      end
+    end
+
+    #######
+    private
+    #######
+
+    def write(data)
+      @udpsock.send(data, 0)
+    rescue Exception => e
+      Logger.log_internal(ERROR) {
+	"UDPOutputter failed to send data to #{@host}:#{@port}, #{e}"
+      }
+    end
+    
+  end
+
+end

data/lib/log4r/rdoc/GDC

@@ -0,0 +1,14 @@
+= GDC
+
+The GDC class implements a copy of the Global Diagnostic Context, which
+is not part of the Apache Log4j library, as of this writing (10 Jan 2009).
+
+The GDC is like the NDC and MDC classes, only it is global to the
+application (see NDC and MDC for details on those classes).
+
+The GDC is local to the main thread, and any new threads will return
+the value of the current GDC set in the main thread.
+
+Only the main thread can set the GDC, any other threads that
+attempt to will raise an exception.
+

data/lib/log4r/rdoc/MDC

@@ -0,0 +1,16 @@
+= MDC
+
+The MDC class implements a copy of the Mapped Diagnostic Context, which
+is part of the Apache Log4j library.  See the NDC documentation for
+more details.  MDCs are much like NDCs, but instead of a stack context
+it uses a map for holding this information.
+
+This allows for selection of information out of the map when
+the log message is being created.
+
+MDCs are thread safe, and are unique to each thread.
+
+An important difference between MDCs in Log4r vs Log4j is that they
+only inherit from the main thread.  Ruby treats all new threads as
+being the children of the main thread, even if they are started
+from a thread that is not main.

data/lib/log4r/rdoc/NDC

@@ -0,0 +1,41 @@
+= NDC
+
+The NDC class implements a copy of the Nested Diagnostic Context, which
+is part of the Apache Log4j library.  Nested Diagnostic Contexts were
+derived from Neil Harrison's article on "Patterns for Logging
+Diagnostic Messages", part of the book "Pattern Languages of Program
+Design 3" edited by Martin et al.
+
+NDCs in Log4r are thread safe.
+
+NDCs in log4r are close enough to NDCs in Log4j that I include its
+documentation directly:
+
+...
+A Nested Diagnostic Context, or NDC in short, is an instrument to
+distinguish interleaved log output from different sources. Log output
+is typically interleaved when a server handles multiple clients
+near-simultaneously.
+
+Interleaved log output can still be meaningful if each log entry from
+different contexts had a distinctive stamp. This is where NDCs come into
+play.
+
+Note that NDCs are managed on a per thread basis. NDC operations such as
+push, pop(), clear(), getDepth() and setMaxDepth(int) affect the NDC of
+the current thread only. NDCs of other threads remain unaffected.
+...
+
+An important difference between NDCs in Log4r vs Log4j is that you
+do not have to called NDC.remove() when exiting a thread.
+
+This class will automatically create Thread specific storage for the 
+current thread on the first call to any of its methods, i.e.
+
+  NDC.push( "client accept" );
+
+New threads may inherit the NDC of the parent thread by making use of
+the clone_stack() and inherit() methods.  By default, the NDC is not
+inherited automatically.  This is unlike MDCs, which will inherit from
+the main thread.
+

data/lib/log4r/rdoc/configurator

@@ -0,0 +1,243 @@
+= Configuring Log4r with Log4r::Configurator
+
+The Configurator class allows one to set up Log4r via XML.
+Additionally, Configurator contains methods to configure any Log4r 
+defaults. In particular, Configurator provides a method to
+customize the logging levels.
+
+Log4r is also configurable using YAML. For that, there is
+a class similar to Configurator called Log4r::YamlConfigurator. Please see
+log4r/yamlconfigurator.rb for details.
+
+REXML is required for XML configuration. Get REXML at 
+http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML
+
+To use the Configurator class,
+
+  require 'log4r/configurator'
+
+== Custom Levels
+
+Suppose you want the following levels and ranks:
+
+  Foo < Bar < Baz
+
+This is easily accomplished:
+
+  Configurator.custom_levels('Foo', 'Bar', :Baz)
+
+The method accepts strings or symbols. However, custom levels must have names 
+that are valid for Ruby constants. Also, custom levels should be set before 
+anything else is done with Log4r, otherwise the default levels will be loaded.
+
+You can set custom levels in XML. That's covered in the following section.
+
+== XML Configuration
+
+If you have REXML, you can configure Log4r with XML.
+To do this, first write an XML configuration (which you can learn by
+studying this document and the examples provided in the distribution)
+and then load up the XML from within your program as follows:
+
+  Configurator.load_xml_file('/path/to/file.xml')
+
+The Log4r XML configuration system is very flexible and powerful. In fact,
+it is somewhat preferable to configuring Log4r in Ruby. In order to take
+full advantage of this feature, there are several concepts one must know.
+They are covered in the following three sections.
+
+=== Concept: XML Directives
+
+The expressive power of Ruby has enabled a feature I call 
+<i>XML directives</i>. An XML directive is a name-value pair belonging to 
+some element. It
+may be represented as an attribute (name="value") of the element, or
+as a child (<name>value</name>) of the element. Therefore, you are
+free to specify information about an object as either an attribute
+or an element. An example should clarify:
+
+  <object data="value"/>
+
+Is equivalent to:
+
+  <object>
+     <data>value</data>
+  </object>
+
+You can assume this behavior except where noted elsewhere in the API.
+
+=== Concept: XML Parameters
+
+A scheme which I call <i>XML parameters</i> enables one to utilize the XML 
+configuratin system for custom Outputters and Formatters.
+This requires <b>no</b> extra work on your part, so long as your objects 
+are set up using hash arguments and can decode string values. That is, once
+you've written a custom Outputter, it is automatically configurable in XML
+without having to write any extra code.
+
+An XML parameter is analogous to a hash argument to some object's <tt>new</tt>
+method. Consider these hash arguments to FileOutputter:
+
+  :filename => '/path/to/logs/my.log'
+  :trunc => 'true'
+
+We can specify them in XML like this:
+
+  <outputter type="FileOutputter" trunc="true">
+     <filename>/path/to/logs/my.log</filename>
+     ...
+
+The name of the element/attribute is just the name of the parameter. Note that
+the input will be a string, thus it's wise to convert the data in from 
+strings in any custom classes (to_i for integers, etc). Now let's suppose you 
+have defined a custom Outputter named MyOutputter with the following 
+additional hash args:
+
+  :myarg1 => 'foo'
+  :myarg2 => 123
+
+Automagically, you can configure your Outputter like so:
+
+  <outputter type="MyOutputter" myarg2="123">
+     <myarg1>foo</myarg1>
+     ...
+
+Isn't that nice? <tt>:-)</tt>
+
+=== Concept: Variable Substitution
+
+To kill the need for preprocessors, Configurator provides a means of variable 
+substitution for XML parameters at runtime. If you specify 
+<tt>#{foo}</tt> in an XML parameter value, Configurator will replace it with 
+the value of 'foo' in its parameter hashtable. The primary idea is that you 
+can figure stuff out in your program, 
+say the log path, and relay that information to the XML while it's being 
+loaded. Secondarily, it is a way to have aliases within an XML document.
+
+There are two ways to tell Configurator about these variables. The first
+method we'll cover is done within a Ruby program with Configurator[].
+
+  Configurator['logpath'] = '/path/to/logs'
+
+Thereafter, any occurence of <tt>#{logpath}</tt> in each and every XML 
+parameter will be substituted with '/path/to/logs'. For example:
+
+  <filename>#{logpath}/mylog.log</filename>
+
+Becomes,
+
+  <filename>/path/to/logs/mylog.log</filename>
+
+Aside from Configurator[], another way to define XML parameter variables
+is to define <tt>parameters</tt> under the <tt><pre_config></tt> element
+of an XML configuration:
+
+  <pre_config>
+     <parameter name="logpath" value="/path/to/logs'/>
+     <parameter name="other" value="somethingelse'/>
+     ...
+  </pre_config>
+
+Alternatively,
+
+  <pre_config>
+     <parameters>
+        <logpath>/path/to/logs</logpath>
+        <other>somethingelse</other>
+        ...
+     </parameters>
+     ...
+
+The end result is the same as using Configurator[]. However, this method
+is not dynamic. Configurator[] should be used when you want to set variables
+from within Ruby.
+
+= XML Grammar
+
+And now, here's the XML grammar we use to configure Log4r.
+
+== Root Element
+
+The root element is <tt><log4r_config></tt>. It can be embedded as a node of
+any other element in an XML file. For instance:
+
+  <my-xml-thing>
+     <customize-libraries>
+        <log4r_config>
+           <!-- log4r configuratin goes here -->
+        </log4r_config>
+        ...
+
+== Pre-config element
+
+The pre_config element is a child of log4r_config and contains:
+
+* 'custom_levels' element
+* 'global' element
+* 'parameters' element
+* any number of 'parameter' elements
+
+=== Pre_config: Custom Levels
+
+The custom_levels element is not an <i>XML directive</i> of pre_config. It
+<b>must</b> be specified like this:
+
+  <custom_levels>Foo, Bar, Baz</custom_levels>
+
+And <b>not</b> like this:
+
+  <!-- NOT SUPPORTED -->
+  <custom_levels levels="Foo, Bar, Baz"/>
+
+=== Pre_config: Global Level
+
+  <global level="DEBUG"/>
+
+or
+
+  <global><level>DEBUG</level></global>
+
+Here, level is an XML directive of global.
+
+=== Pre_config: Parameters
+
+Parameters are variables that will be substituted later on. Please
+see the <b>Concept: Variable Substitution</b> section above. Parameters 
+are <i>XML Directives</i>, which means they can be expressed using elements 
+or attributes. Here is an example:
+
+  <parameter name="param name 1" value="param value 1">
+  <parameter name="param name 2" value="param value 2">
+  ...
+  <parameters>
+     <param3>value3</param3>
+     <param4>value3</param4>
+     ...
+
+=== Pre_config: Complete Example
+
+   <log4r_config>
+
+      <pre_config>
+         <custom_levels>
+            Foo,Bar, Baz
+         </custom_levels>
+         <global level="Bar"/>
+         <parameters>
+            <logpath>/var/log/foo</logpath>
+            <mypattern>%l [%d] %m</mypattern>
+         </parameters>
+      </pre_config>
+
+      <!-- define some outputters and loggers -->
+      
+   </log4r_config>
+
+== Configuring Log4r Objects
+
+The XML configuration grammar for Loggers, Outputters and the like are 
+covered in the usage guidelines for those classes.
+
+== Order Doesn't Matter
+
+You can (it is hoped) define any of the XML objects in any order desired.

data/lib/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/lib/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/lib/log4r/rdoc/log4jxmlformatter

@@ -0,0 +1,21 @@
+= 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.
+