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