forked from holyjak/blog
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.txt
155 lines (113 loc) · 5.65 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
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/