File Coverage

blib/lib/Tail/Stat.pm

Criterion	Covered	Total	%
statement	6	6	100.0
branch			n/a
condition			n/a
subroutine	2	2	100.0
pod			n/a
total	8	8	100.0

line	stmt	sub	time	code
1				package Tail::Stat;
2
3				=head1 NAME
4
5				Tail::Stat - Real-time log statistics server
6
7				=cut
8
9
10	1	1	21093	use strict;
	1		2
	1		28
11	1	1	5	use warnings qw(all);
	1		2
	1		78
12
13				our $VERSION = '0.25';
14
15
16				=head1 ABSTRACT
17
18				It's often necessary to collect some statistics data for following
19				analysis or processing. Common case are various monitoring tools,
20				like a MRTG, Nagios or Zabbix. Some services may be examined by special
21				commands or protocols, other may not. But often, information we are interested in
22				can be extracted from server logs. This software helps
23				to extract, accumulate and provide this information to monitoring
24				tool via simple, easy parseable protocol.
25
26
27				=head1 ARCHITECTURE
28
29				Tail::Stat has a plugin structure. Each plugin supports logs processing
30				for a specific service. Main executable (called I) works as a
31				long running background process (daemon) with TCP listen socket for
32				querying about collected statistics. There is no any configuration files,
33				all required parameters tstatd takes from command line options.
34				One running instance of tstatd can process many similar log files
35				simultaneously. It agregates extracted parameters into I.
36				Zones are just namespaces for grouping this values.
37				For collecting parameters from other kind of service you have to run
38				other instance of tstatd.
39
40
41				=head1 TYPE OF VALUES
42
43				Fundamentally all measured values can be separated into two principally
44				different groups: I and I.
45				For example, processing web-server logs we want to calculate two parameters:
46				total processed HTTP requests and average time elapsed per request.
47				The first goal can be achieved by simple incremented counter, but the second
48				is a little harder. We have to summarize elapsed times and then divide this
49				amount onto request count. But we have to do this for a small time slot
50				(usually comparable with our monitoring tool polling interval).
51				This kind of calculations is supported by Tail::Stat and calls I
52				calculations. Tail::Stat operate with a set of a small windows.
53				First window (called I) accumulates current data.
54				After a fixed period of time (C<--window-size>) a window is closing (special
55				handler executing), new window creating and setting as current and last of closed
56				windows is removing. Total number of windows can be adjusted by special option
57				(C<--windows-num>). For example: our monitoring tool has a polling interval
58				about 10 minutes (600 seconds). We want to provide it average response time
59				for last 600 seconds respectively. Appropriate window size can be set
60				as 10 seconds with keeping values for 60 windows (and this are default values).
61
62
63				=head1 CLIENT PROTOCOL
64
65				Querying accumulated data is available via simple TCP-based protocol.
66				Protocol is line oriented (like an HTTP or SMTP).
67
68				=head2 zones
69
70				Prints list of known zones. Zones specified via command line options marked
71				with 'a:' prefix (active). Zones restored from a database file, but not
72				found in command options marked with 'i:' prefix (inactive).
73
74				=head2 globs I
75
76				Prints list of globs (wildcards) associated with I. Applicable only
77				to active zones.
78
79				=head2 files I
80
81				Prints list of files currently processing for I. Each file prefixed by
82				current reading offset and size of file. Applicable only to active zones.
83
84				=head2 wipe I\|*
85
86				Wipes out an inactive I or all inactive zones. Applicable only to inactive
87				zones.
88
89				=head2 dump I
90
91				Prints out raw I statistics.
92
93				=head2 stats I
94
95				Prints out formatted I statistics.
96
97				=head2 quit
98
99				Closes client connection.
100
101
102				=head1 BUGS
103
104				Please report any bugs or feature requests to C, or through
105				the web interface at L. I will be notified, and then you'll
106				automatically be notified of progress on your bug as I make changes.
107
108
109				=head1 SUPPORT
110
111				You can find documentation for this module with the perldoc command.
112
113				perldoc Tail::Stat
114
115				You can also look for information at:
116
117				=over 4
118
119				=item * RT: CPAN's request tracker
120
121				L
122
123				=item * AnnoCPAN: Annotated CPAN documentation
124
125				L
126
127				=item * CPAN Ratings
128
129				L
130
131				=item * Search CPAN
132
133				L
134
135				=back
136
137
138				=head1 AUTHOR
139
140				Oleg A. Mamontov, C<< >>
141
142
143				=head1 COPYRIGHT & LICENSE
144
145				This program is free software; you can redistribute it and/or modify it
146				under the terms of either: the GNU General Public License as published
147				by the Free Software Foundation; or the Artistic License.
148
149				See http://dev.perl.org/licenses/ for more information.
150
151				=cut
152
153
154				1;
155