path-log4r 1.1.10

data/examples/logclient.rb

@@ -0,0 +1,25 @@
+# How to use RemoteOutputter. See logserver.rb first.
+
+$: << File.join('..','lib')
+require 'log4r'
+require 'log4r/outputter/remoteoutputter'
+include Log4r
+
+Logger.new('log4r').add 'stdout'        # to see what's going on inside
+RemoteOutputter.new 'remote',           # make a RemoteOutputter
+    :uri=>'tcpromp://localhost:9999',   # where our LogServer is
+    :buffsize=>10                       # buffer 10 before sending to LogServer
+Logger.new('client').add('remote')      # give 'remote' to a 'client' Logger
+
+# we're done with setup, now let's log
+def log(l)
+  l.debug "debugging"
+  l.info "a piece of info"
+  l.warn "Danger, Will Robinson, danger!"
+  l.error "I dropped by Wookie! :("
+  l.fatal "kaboom!"
+end
+
+5.times { log(Logger['client']) }      # do a bunch of logging
+Logger['client'].info "Bye Bye from client!"
+Outputter['remote'].flush              # flush the RemoteOutputter

data/examples/logserver.rb

@@ -0,0 +1,18 @@
+# How to use LogServer
+
+$: << File.join('..','lib')
+require 'log4r'
+require 'log4r/configurator'
+
+# XML configuration is simple enough to embed here
+xml = %(
+<log4r_config>
+  <logserver name="server" uri="tcpromp://localhost:9999">
+   <outputter>stdout</outputter>
+  </logserver>
+</log4r_config>
+)
+Log4r::Logger.new('log4r').add 'stdout'        # to see what's going on inside
+Log4r::Configurator.load_xml_string xml        # load it up
+sleep                                   
+# now run logclient.rb on another terminal

data/examples/moderate.xml

@@ -0,0 +1,29 @@
+<!-- the config file used by xmlconfig.rb -->
+<log4r_config>
+  <pre_config>
+    <global level="DEBUG"/>
+    <!-- we'll set serverlog in XML and logpath at runtime for illustration -->
+    <parameter name="serverlog" value="./logs/server.log"/>
+  </pre_config>
+
+  <!-- outputters, illustrating XML config flexibility -->
+  <outputter type="FileOutputter" name="server">
+    <filename>#{serverlog}</filename>
+    <trunc>false</trunc>
+  </outputter>
+  <outputter type="FileOutputter" name="client" 
+             filename="#{logpath}/client.log"/>
+  <outputter type="FileOutputter" name="gui" 
+             filename="#{logpath}/guidebug.log"/>
+  <outputter type="StderrOutputter" name="console" level="ERROR"/>
+
+  <!-- loggers -->
+
+  <logger name="server" level="ERROR" outputters="server, console"/>
+  <logger name="client" level="INFO"  outputters="client, console"/>
+  <logger name="client::gui" trace="true">
+    <level>DEBUG</level>
+    <outputter>gui</outputter>
+  </logger>
+
+</log4r_config> 

data/examples/moderateconfig.rb

@@ -0,0 +1,66 @@
+# Now, for something more complicted
+# Let's pretend this is the global config file for our app
+
+$: << File.join('..','lib')
+require "log4r"
+
+include Log4r                   # include Log4r to make things simple
+
+Logger.root.level = DEBUG       # global level DEBUG
+
+# suppose we want to have loggers for a Server and a Client class
+# furthermore, we want the client gui to have its own logger. (You'll want
+# one logger per class or so.)
+# When the loggers are created, they are stored in a repository for further
+# retreival at any point using a hash method call: Logger['name']
+
+# server is stable, so only log ERROR and FATAL
+Logger.new("server", ERROR)
+# let's say we don't need the DEBUG junk for client logs
+Logger.new("client", INFO)
+# but we're still debugging the gui
+debugger = Logger.new("client::gui", DEBUG)
+debugger.trace = true     # we want to see where the log method was called
+
+# Guilog is a child of client. In this case, any log events to the gui
+# logger will also be logged to the client outputters. We can change
+# that behavior by setting guilogger's 'additive' to false, but not yet.
+
+# let's create the outputters
+FileOutputter.new('server', :filename=>'logs/server.log', :trunc => false)
+FileOutputter.new('client', :filename=>'logs/client.log')
+FileOutputter.new('gui', :filename=>'logs/guidebug.log')
+# additionally, we want ERROR and FATAL messages to go to stderr
+StderrOutputter.new('console', :level=>ERROR)
+
+# add the outputters
+Logger['server'].add 'server', 'console'
+Logger['client'].add 'client', 'console'
+Logger['client::gui'].add 'gui'  # gui will also write to client's outputters
+
+# That's it for config. Now let's use the loggers:
+
+def do_logging(log)
+  log.debug "debugging"
+  log.info "a piece of info"
+  log.warn "Danger, Will Robinson, danger!"
+  log.error "I dropped my Wookie! :(" 
+  log.fatal "kaboom!"
+end
+
+Logger.each_logger{|logger| do_logging(logger) }
+
+# You can dynamically change levels and turn off tracing:
+Logger['client'].level = OFF
+Logger['client::gui'].trace = false
+
+puts 'Only server should show Dynamic Change onscreen:'
+Logger.each_logger{|logger| logger.fatal "Dynamic change." }
+# logs/client.log file should not show "Dynamic change."
+# logs/guidebug.log should not show the trace at "Dynamic change."
+
+# we can also set our outputter to log only specified levels:
+
+Outputter['console'].only_at ERROR
+puts "Should only see ERROR next:"
+do_logging Logger['server']

data/examples/myformatter.rb

@@ -0,0 +1,23 @@
+# try out a custom formatter
+
+$: << '../lib'
+
+require "log4r"
+
+class MyFormatter <  Log4r::Formatter
+  def format(event)
+    buff = "The level is #{event.level} and has "
+    buff += "name '#{Log4r::LNAMES[event.level]}'\n"
+    buff += "The logger is '#{event.name}' "
+    buff += "and the data type is #{event.data.class}\n"
+    buff += "Let's inspect the data:\n"
+    buff += event.data.inspect + "\n"
+    buff += "We were called at #{event.tracer[0]}\n\n"
+  end
+end
+
+log = Log4r::Logger.new('custom formatter')
+log.trace = true
+log.add Log4r::StdoutOutputter.new('stdout', :formatter=>MyFormatter)
+log.info [1, 2, 3, 4]
+log.error "A log statement"

data/examples/outofthebox.rb

@@ -0,0 +1,21 @@
+# Here's how to start using log4r right away
+$: << File.join('..','lib')                   # path if log4r not installed
+require "log4r"
+
+Log = Log4r::Logger.new("outofthebox")        # create a logger
+Log.add Log4r::Outputter.stderr               # which logs to stdout
+
+# do some logging
+def do_logging
+ Log.debug "debugging"
+ Log.info "a piece of info"
+ Log.warn "Danger, Will Robinson, danger!"
+ Log.error "I dropped my Wookie! :("
+ Log.fatal "kaboom!"
+end
+do_logging
+
+# now let's filter anything below WARN level (DEBUG and INFO)
+puts "-= Changing level to WARN =-"
+Log.level = Log4r::WARN
+do_logging

data/examples/rdoc-gen

@@ -0,0 +1,2 @@
+rdoc --exclude *CVS* --exclude .*patch --exclude diff
+

data/examples/rrconfig.xml

@@ -0,0 +1,63 @@
+<!-- This is a real config file used by a game that I'm working on 
+     The Ruby file that loads this is rrsetup.rb -->
+<log4r_config>
+  <pre_config>
+    <!-- I like having a ton of levels. There are three extra for component
+         data, comp1..3 and one level for object dumps (DATA) -->
+    <custom_levels>
+      COMP3, COMP2, COMP1, DATA, DEBUG, INFO, WARN, ERROR, FATAL
+    </custom_levels>
+    <!-- change to ERROR when the game goes to production -->
+    <global level="ALL"/>
+  </pre_config>
+
+  <!-- Outputters -->
+
+  <!-- game.log records DEBUG and higher, so no game component data -->
+  <outputter name="gameout" type="FileOutputter" level="DEBUG">
+    <!-- I set the logpath from within the game. -->
+    <filename>#{logpath}/game.log</filename>
+  </outputter>
+  <!-- DATA level goes to its own special file. These log events are
+       too noisy for game.log and are not game components. Useful
+       for dumping lots of objects during development. -->
+  <outputter name="gamedata" type="FileOutputter" only_at="DATA">
+    <filename>#{logpath}/data.log</filename>
+    <!-- low-noise custom formatter for objects -->
+    <formatter type="CompFormatter"/>
+  </outputter>
+  <!-- Spit any errors to the console. They merit special attention -->
+  <outputter name="console" type="StderrOutputter" level="ERROR"/>
+  <!-- A separate log file for tracking game components, 
+       used for development. It logs ALL-->
+  <outputter name="componentout" type="FileOutputter">
+    <filename>#{logpath}/component.log</filename>
+    <formatter type="CompFormatter"/>
+  </outputter>
+
+  <!-- Loggers -->
+
+  <!-- 'game' is the main logger for the client-server framework -->
+  <logger name="game" level="DATA" additive="false" trace="true">
+    <outputters>gameout, gamedata, console</outputters>
+  </logger>
+  <!-- Notice how we have fine control over how each element logs.
+       The gui and controller are stable while the rest are being debugged. -->
+  <logger name="game::gui" level="ERROR" additive="true" trace="true"/>
+  <logger name="game::boardgui" level="DEBUG" additive="true" trace="false"/>
+  <logger name="game::server" level="DEBUG" additive="true" trace="true"/>
+  <logger name="game::client" level="DEBUG" additive="true" trace="true"/>
+  <logger name="game::controller" level="ERROR" additive="true" trace="false"/>
+
+  <!-- 'component' is the main logger for game objects. It's used in
+       development to track how the objects change with time. -->
+  <logger name="component" level="ALL" additive="false" trace="false">
+    <outputter>componentout</outputter>
+    <outputter>console</outputter>
+  </logger>
+  <logger name="component::board"/>
+  <logger name="component::tile"/>
+  <logger name="component::player"/>
+  <logger name="component::player::robot"/>
+ 
+</log4r_config>

data/examples/rrsetup.rb

@@ -0,0 +1,42 @@
+# This is a real config file used by a game that I'm working on
+# The XML config file is called rrconfig.xml
+
+$: << File.join('..','lib')
+require 'log4r'
+require 'log4r/configurator'
+include Log4r
+
+# How to format component data - low noise
+class CompFormatter < Formatter
+  def format(event)
+    buff = event.name + "> "
+    if event.data.kind_of?(String) then buff += event.data
+    else buff += event.data.inspect end
+    return buff + "\n"
+  end
+end
+
+# Set the logpath. Eventually, this will be determined from the environment.
+Configurator['logpath'] = './logs'
+Configurator.load_xml_file('rrconfig.xml')
+
+# the rest is an example
+
+Robot = {"name"=>"twonky", "row"=>"3", "col"=>"4"}
+
+def do_logging(log)
+log.comp3  Robot
+log.comp2 Robot
+log.comp1 Robot
+log.data "this is a piece of data".split
+log.debug "debugging"
+log.info "a piece of info"
+log.warn "Danger, Will Robinson, danger!"
+log.error "I dropped my Wookie! :(" 
+log.fatal "kaboom!"
+end
+
+Logger.each_logger {|logger| do_logging(logger)}
+
+# you can see the results onscreen and in logs/game.log
+# logs/data.log and logs/component.log

data/examples/simpleconfig.rb

@@ -0,0 +1,39 @@
+# Simple configuration example.
+# Where we configure just one logger and make it log to a file and stdout.
+
+# add the path to log4r if it isn't installed in a ruby path
+$: << File.join('..','lib')
+require "log4r"
+
+# First things first, get the root logger and set its level to WARN.
+# This makes the global level WARN. Later on, we can turn off all logging
+# by setting it to OFF right here (or dynamically if you prefer)
+Log4r::Logger.root.level = Log4r::WARN
+
+# Remember: By specifying a level, we are saying "Include this level and
+# anything worse." So in this case, we're logging WARN, ERROR and FATAL
+
+# create a logger
+log = Log4r::Logger.new("simpleconf")
+
+# We want to log to $stderr and a file ./tmp.log
+
+# Create an outputter for $stderr. It defaults to the root level WARN
+Log4r::StderrOutputter.new 'console'
+# for the file, we want to log only FATAL and ERROR and don't trunc
+Log4r::FileOutputter.new('logfile', 
+                         :filename=>'logs/simple.log', 
+                         :trunc=>false,
+                         :level=>Log4r::FATAL)
+
+# add the outputters (this method accepts outputter names or references)
+log.add('console','logfile')
+
+# Now let's try it out:
+log.debug "debugging"
+log.info "a piece of info"
+log.warn "Danger, Will Robinson, danger!"
+log.error "I dropped my Wookie! :("
+log.fatal "kaboom!"
+
+# now run this and compare output to ./tmp.log

data/examples/syslogcustom.rb

@@ -0,0 +1,52 @@
+# Suppose we don't like having 5 levels named DEBUG, INFO, etc.
+# Suppose we'd rather use 3 levels named Foo, Bar, and Baz.
+# Suppose we'd like to use these with syslog
+# Log4r allows you to rename the levels and their corresponding methods
+# in a painless way and then map those to corrisponding syslog levels
+# or have them all default to LOG_INFO
+# This file provides an example
+
+$: << '../lib'
+
+require 'log4r'
+require 'log4r/configurator'
+require 'log4r/formatter/patternformatter'
+require 'log4r/outputter/syslogoutputter'
+require 'syslog'
+include Log4r
+include Syslog::Constants
+
+# This is how we specify our levels
+Configurator.custom_levels "Foo", "Bar", "Baz"
+
+l = Logger.new('custom levels')
+slp = PatternFormatter.new( :pattern => '{%p} {%h} {%d} {%l} {%C} {%m}', :date_method => 'usec' )
+sl = SyslogOutputter.new( 'sysloggertest', 
+			 { :logopt => LOG_CONS | LOG_PID | LOG_PERROR,
+			   :facility => LOG_LOCAL7,
+			   :formatter => slp } )
+sl.map_levels_by_name_to_syslog( { "Foo" => "DEBUG", "Bar" => "INFO", "Baz" => "ALERT" } )
+l.add sl
+
+l.level = Foo
+puts l.foo?
+l.foo "This is foo"
+puts l.bar?
+l.bar "this is bar"
+puts l.baz?
+l.baz "this is baz"
+
+puts "Now change to Baz"
+
+l.level = Baz
+puts l.foo?
+l.foo {"This is foo"}
+puts l.bar?
+l.bar {"this is bar"}
+puts l.baz?
+l.baz {"this is baz"}
+
+l4r = Logger.new('log4r')
+l4r.add Log4r::Outputter.stderr
+
+Log4r::SyslogOutputter.new 'test'

data/examples/xmlconfig.rb

@@ -0,0 +1,25 @@
+# This is like moderateconfig.rb, but using an XML config
+# please look at moderate.xml
+
+$: << '../lib'
+
+require 'log4r'
+require 'log4r/configurator'
+include Log4r
+
+# set any runtime XML variables
+Configurator['logpath'] = './logs'
+# Load up the config file
+Configurator.load_xml_file('./moderate.xml')
+
+# now repeat what moderateconfig.rb does
+def do_logging(log)
+log.debug "debugging"
+log.info "a piece of info"
+log.warn "Danger, Will Robinson, danger!"
+log.error "I dropped my Wookie! :("
+log.fatal "kaboom!"
+end
+
+Logger.each_logger{|logger| do_logging(logger) }
+# stop here

data/examples/yaml.rb

@@ -0,0 +1,30 @@
+# Log4r can be configured using YAML. This example uses log4r_yaml.yaml
+
+$: << File.join('..','lib') # path if log4r is not installed
+require 'log4r'
+require 'log4r/yamlconfigurator'
+# we use various outputters, so require them, otherwise config chokes
+require 'log4r/outputter/datefileoutputter'
+require 'log4r/outputter/emailoutputter'
+require 'log4r/outputter/scribeoutputter'
+
+cfg = Log4r::YamlConfigurator # shorthand
+cfg['HOME'] = '.'      # the only parameter in the YAML, our HOME directory
+
+# load the YAML file with this
+cfg.load_yaml_file('log4r_yaml.yaml')
+
+# Method to log each of the custom levels
+def do_logging(log)
+  log.deb "This is DEB"
+  log.inf "This is INF"
+  log.prt "This is PRT"
+  log.wrn "This is WRN"
+  log.err "This is ERR"
+  log.fat "This is FAT"
+end
+
+# turn off the email outputter
+Log4r::Outputter['email'].level = Log4r::OFF
+# the other two outputters log to stderr and a timestamped file in ./logs
+do_logging( Log4r::Logger['mylogger'])