h1. A flexible logging library for Ruby, now in color

This project is currently decoupled from the main log4r project which it rests on. The main addition to log4r in this project is the ColorOutputter which uses "colorize":https://github.com/fazibear/colorize to display logs in the console/terminal with colorschemes for each log level to make it easy to distinquish them.

This project is used in "logging_assist":https://github.com/kristianmandrup/logging_assist which wraps log4r-color in a convenient DSL syntax.

h2. Release

This release: 1.2 Release date: Jan/2011 License: LGPLv3

h2. Contributors

• Colby Gutierrez-Kraybill
• Kristian Mandrup (ColorOutputter)
• Leon Torres - Original Maintainer
• Martain Stannard - RollingFileOutputter
• Steve Lumos - SyslogOutputter
• Mark Lewandowski - ScribeOutputter
• Andreas Hund - YamlConfigurator
• Jamis Buck - log4r.gemspec
• Charles Strahan - log4jxml/chainsaw integration
• Nitay Joffe - STARTTLS
• David Siegal - Smart updates to RollingFileOutputter

"Homepage":http://log4r.rubyforge.org/ "Download":http://rubyforge.org/frs/?group_id=203

h2. Summary

Log4r is a comprehensive and flexible logging library written in Ruby for use in Ruby programs. It features a hierarchical logging system of any number of levels, custom level names, logger inheritance, multiple output destinations per log event, execution tracing, custom formatting, thread safteyness, XML and YAML configuration, and more.

h2. Requirements

• (required) Ruby >= 1.7.0 (use log4r 1.0.2 for Ruby 1.6)
• (optional) RubyGems for installing Log4r as a gem
• (optional) Ruby syslog library for SyslogOutputter
• (optional) XML configuration requires REXML
• (optional) log4j chainsaw integration requires 'builder' >= 2.0
• (optional) STARTTLS email login, requires 'smtp_tls" if Ruby <= 1.8.6

h3. Gem requirements

• colorize
• scribe

h2. Install

gem install log4r-color

h2. Usage

Here is an example of setting up a logger with ColorOutputter using a color scheme. While logging, one of the color schemes is changed and it applies immediately to log messages after.

require 'log4r-color'
include Log4r

Logger.global.level = ALL
formatter = PatternFormatter.new(:pattern => "%l - %m - %c")

ColorOutputter.new 'color', {:colors => 
  { 
    :debug  => :light_blue, 
    :info   => :light_blue, 
    :warn   => :yellow, 
    :error  => :red, 
    :fatal  => {:color => :red, :background => :white} 
  } 
}

Logger.new('color_logger', DEBUG).add('color')

def do_logging(log)
  puts "--"
  log.debug "This is debug"
  log.info "This is info"
  log.warn "This is warn"
  Outputter['color'].colors[:info] = :green
  log.info "This is info again, now in green"
  log.error "This is error"
  log.fatal "This is fatal"  
end

do_logging Logger['color_logger']  

Note: You can set the log levels you allow via the `Log4r.LNAMES` constant, by default set to `['ALL']` to allow any log level.

h2. More Info

• Installation instructions are in the file INSTALL

• Comprehensive examples are provided in examples/ and can be run right away

• Log4r homepage: doc/index.html Online: http://log4r.rubyforge.org/

• Manual: doc/manual.html Online: http://log4r.rubyforge.org/manual.html

• RDoc API reference: doc/rdoc/index.html Online: http://log4r.rubyforge.org/rdoc/index.html

• The changelog

• Log4r is hosted by RubyForge, which provides news, bug tracking and a forum

• Feel free to bug the maintainer with any questions (listed at top of file)

h2. Usability

Log4r works really well, so please take advantage of it right away! :) All versions since 0.9.2 have been stable and backward-compatible. The code is stable enough that updates are infrequent and usually only for adding features or keeping the code up to date with Ruby.

h2. Platform Issues

Log4r is known to work on Linux and WindowsXP. It's safe to assume that Log4r will work on any Ruby-supported platform.

h2. When Trouble Strikes

Log4r comes with an internal logger. To see its output, create a logger named 'log4r' before any others and give it a suitable outputter,

  trouble = Logger.new['log4r']
  trouble.add Outputter.stdout