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 bran cond sub pod 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   61389 use strict;
  1         2  
  1         32  
11 1     1   3 use warnings qw(all);
  1         2  
  1         71  
12              
13             our $VERSION = '0.26';
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<tstatd>) 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<zones>.
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<counters> and I<gauges>.
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<sliding windows>
52             calculations. Tail::Stat operate with a set of a small windows.
53             First window (called I<current>) 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<zone>
75              
76             Prints list of globs (wildcards) associated with I<zone>. Applicable only
77             to active zones.
78              
79             =head2 files I<zone>
80              
81             Prints list of files currently processing for I<zone>. Each file prefixed by
82             current reading offset and size of file. Applicable only to active zones.
83              
84             =head2 wipe I<zone>|*
85              
86             Wipes out an inactive I<zone> or all inactive zones. Applicable only to inactive
87             zones.
88              
89             =head2 dump I<zone>
90              
91             Prints out raw I<zone> statistics.
92              
93             =head2 stats I<zone>
94              
95             Prints out formatted I<zone> 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<bug-tail-stat at rt.cpan.org>, or through
105             the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tail-Stat>. 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<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tail-Stat>
122              
123             =item * AnnoCPAN: Annotated CPAN documentation
124              
125             L<http://annocpan.org/dist/Tail-Stat>
126              
127             =item * CPAN Ratings
128              
129             L<http://cpanratings.perl.org/d/Tail-Stat>
130              
131             =item * Search CPAN
132              
133             L<http://search.cpan.org/dist/Tail-Stat/>
134              
135             =back
136              
137              
138             =head1 AUTHOR
139              
140             Oleg A. Mamontov, C<< <oleg@mamontov.net> >>
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