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