Introduction
============

stat4j is Free Software. stat4j is released under the terms of the
Apache, version 2.0 license which may be viewed at:

http://www.apache.org/licenses/LICENSE-2.0

What is stat4j?
===============

stat4j is a a simple,lightweight extension to log4j that allows you to mine your 
logs in real-time for statistical information. It can be used to:
	.Measure and profile application performance
	.Report on business level statistics such as the number of widgets sold
	 or the number of users logged into your site
	.Alert for events that indicate production problems

stat4j may be used by any Java/J2EE application that uses log4j for logging. 
stat4j supports Java 1.4 and above.

Features include:
	.A log4J appender for intercepting log messages
	.A metrics engine for filtering and scraping metrics from log messages
	.Pre-built calculators to dervive statistics using common statistical functions
	.Threshold based alerting
	.An RSS Appender for outputing logs and statistics in RSS format
	
When should you use stat4j?
=========================
.When you want to use a lightweight mechanism for measuring application performance or
 capturing user defined statistics of interest to you or your business
.When you have a mature application and you dont want to use byte code instrumention or 
 invest in exspensive tools
.When you have copious log messages and want to leverage these into useful metrics -
 in real-time

Stat4j is free, production friendly and easy to use. It integrates into your application with 
just one line of configuration.

How does it work? - the 5 second overview
=========================================

Statistics instrumentation:

Statistics may be derived from events or patterns that occur in a log. For example a user count 
may be derived by incrementing a count whenever a messge "User() has logged in."
occurs and decremented whenever a log message "User() has logged out" occurs. Statistics may be be derived from
single (instantaneous) matches or 2 related matches in 2 separate log messages. The unit of measurement 
may be time, memory, occurances or a numeric scraped from the message itself. The stat4j appender
intercepts logs and filters them for matches against user pre-defined statistic patterns. If a match is 
found then the metric is forwarded into stat4j proper which calculates one or more statistic results. 
Calculations can be simple counts,rates or more complex functions such as min,max or average. Log messages that dont 
match any patterns are simply discarded i.e no extra I/O.

Log filtering and scraping is done using regular expressions.

Alerting:

In addition to statistics derivation stat4j allows you to define simple threshold based alerts.
for example WARN when number of users > 100 or error rate > 10 errors per sec. Alerts are evaluated
whenever a statistic is calculated and forwarded to a pre-defined log4j alerts category.
This can then be logged, sent to JMS, or used to generate an RSS feed.

Project Structure
=================
README.txt			Project overview
build.xml			Ant build file
/src				stat4j java source
/test				stat4j junit java source and log configuration
/examples			stat4j examples including and log configuration
/ext				external libraries
/contributors		Comments and src from stat4j contributors
/docs				Docs generated by build
/report				unit test report generated by rruning unit tests

Quick Start
===========

To Build:

stat4j uses ANT to build. Ensure that you have java 1.4+ and ANT installed on you machine.

From the command prompt, cd to the stat4j home directory.

Type "ant list" to get a list of targets to build
Type "ant compile" to compile stat4j classes
Type "ant dist" to build the stat4j jar file
Type "ant test" to runt the stat4j test cases
Type "ant doc" to build the stat4j documentation 
Type "ant demo" to run the stat4j demonstraton app

To Use:

1) Include the stat4j jar file in the classpath of the application you wish to instrument.

e.g java <myApp class> -classpath "libs/log4j.jar;libs/stat4j.jar"

2) Configure log4j to use stat4j

# Add stat4j Appender
log4j.appender.stat4j=net.sourceforge.stat4j.log4j.Stat4jAppender

# Set stat4j Appender as the default appender for your target log categories,
# in this case root. This means all log messages will  be sent to 
# the console and stat4j appenders
log4j.rootCategory=console,stat4j

3) Configure the statistics that you want to measure

stat4j configuration is managed by the stat4j.properties file. This file  
contains the stat4j calculator config and the statistics that you want 
collected.

stat4j will load the stat4j.properties automatically from the classpath when stat4j starts up. 
It is assumed to be at the top of the classpath and so must be present in the
classpath for your application.

stat4j.properties contains several pre-defined statistics,filters 
and alerts: debug_count,error_count,info_count,debug_rate,error_rate, info_rate and error
alert.

To add your own statistics simply follow the examples provided and add your statistics 
configuration to stat4j.properties.

For more information on configuring statistics see the user guide under the docs directory.

For examples that use stat4j see the examples directory.

For more information on log4j setup and configuration see:

	http://logging.apache.org/
	
For more information on ANT see:

	http://ant.apache.org/

Roadmap
=======

1. RSS Appender
2. More Calculators
3. stat4j aspects - to allow statistics collection via AOP
3. Statistics Reporting (push & pull) via RMI/JMX
4. XML configuration
5. User tagging
6. Statistics UI
7. Eclipse Plugin

Contacts
========

stat4j homepage:            http://stat4j.sourceforge.net/
SourceForge project info: 	http://sourceforge.net/projects/stat4j/