bin/gatherstats.pl

   1 #! /usr/bin/perl
   2 #
   3 # gatherstats.pl
   4 #
   5 # This script will gather statistical information from a database
   6 # containing headers and other information from a INN feed.
   7 #
   8 # It is part of the NewsStats package.
   9 #
  10 # Copyright (c) 2010-2013 Thomas Hochstein <thh@inter.net>
  11 #
  12 # It can be redistributed and/or modified under the same terms under
  13 # which Perl itself is published.
  14
  15 BEGIN {
  16   our $VERSION = "0.02";
  17   use File::Basename;
  18   # we're in .../bin, so our module is in ../lib
  19   push(@INC, dirname($0).'/../lib');
  20 }
  21 use strict;
  22 use warnings;
  23
  24 use NewsStats qw(:DEFAULT :TimePeriods ListNewsgroups ParseHierarchies ReadGroupList);
  25
  26 use DBI;
  27 use Getopt::Long qw(GetOptions);
  28 Getopt::Long::config ('bundling');
  29
  30 ################################# Definitions ##################################
  31
  32 # define types of information that can be gathered
  33 # all / groups (/ clients / hosts)
  34 my %LegalStats;
  35 @LegalStats{('all','groups')} = ();
  36
  37 ################################# Main program #################################
  38
  39 ### read commandline options
  40 my ($OptCheckgroupsFile,$OptClientsDB,$OptDebug,$OptGroupsDB,$OptTLH,
  41     $OptHostsDB,$OptMonth,$OptRawDB,$OptStatsType,$OptTest,$OptConfFile);
  42 GetOptions ('c|checkgroups=s' => \$OptCheckgroupsFile,
  43             'clientsdb=s'     => \$OptClientsDB,
  44             'd|debug!'        => \$OptDebug,
  45             'groupsdb=s'      => \$OptGroupsDB,
  46             'hierarchy=s'     => \$OptTLH,
  47             'hostsdb=s'       => \$OptHostsDB,
  48             'm|month=s'       => \$OptMonth,
  49             'rawdb=s'         => \$OptRawDB,
  50             's|stats=s'       => \$OptStatsType,
  51             't|test!'         => \$OptTest,
  52             'conffile=s'      => \$OptConfFile,
  53             'h|help'          => \&ShowPOD,
  54             'V|version'       => \&ShowVersion) or exit 1;
  55
  56 ### read configuration
  57 my %Conf = %{ReadConfig($OptConfFile)};
  58
  59 ### override configuration via commandline options
  60 my %ConfOverride;
  61 $ConfOverride{'DBTableRaw'}   = $OptRawDB if $OptRawDB;
  62 $ConfOverride{'DBTableGrps'}  = $OptGroupsDB if $OptGroupsDB;
  63 $ConfOverride{'DBTableClnts'} = $OptClientsDB if $OptClientsDB;
  64 $ConfOverride{'DBTableHosts'} = $OptHostsDB if $OptHostsDB;
  65 $ConfOverride{'TLH'} = $OptTLH if $OptTLH;
  66 &OverrideConfig(\%Conf,\%ConfOverride);
  67
  68 ### get type of information to gather, defaulting to 'all'
  69 $OptStatsType = 'all' if !$OptStatsType;
  70 &Bleat(2, sprintf("Unknown type '%s'!", $OptStatsType))
  71   if !exists($LegalStats{$OptStatsType});
  72
  73 ### get time period from --month
  74 # get verbal description of time period, drop SQL code
  75 my ($Period) = &GetTimePeriod($OptMonth);
  76 # bail out if --month is invalid or set to 'ALL';
  77 # we don't support the latter
  78 &Bleat(2,"--month option has an invalid format - please use 'YYYY-MM' or ".
  79          "'YYYY-MM:YYYY-MM'!") if (!$Period or $Period eq 'all time');
  80
  81 ### reformat $Conf{'TLH'}
  82 my $TLH;
  83 if ($Conf{'TLH'}) {
  84   # $Conf{'TLH'} is parsed as an array by Config::Auto;
  85   # make a flat list again, separated by :
  86   if (ref($Conf{'TLH'}) eq 'ARRAY') {
  87     $TLH = join(':',@{$Conf{'TLH'}});
  88   } else {
  89     $TLH  = $Conf{'TLH'};
  90   }
  91   # strip whitespace
  92   $TLH =~ s/\s//g;
  93   # add trailing dots if none are present yet
  94   # (using negative look-behind assertions)
  95   $TLH =~ s/(?<!\.):/.:/g;
  96   $TLH =~ s/(?<!\.)$/./;
  97   # check for illegal characters
  98   &Bleat(2,'Config error - illegal characters in TLH definition!')
  99     if ($TLH !~ /^[a-zA-Z0-9:+.-]+$/);
 100   # escape dots
 101   $TLH =~ s/\./\\./g;
 102   if ($TLH =~ /:/) {
 103     # reformat $TLH from a:b to (a)|(b),
 104     # e.g. replace ':' by ')|('
 105     $TLH =~ s/:/)|(/g;
 106     $TLH = '(' . $TLH . ')';
 107   };
 108 };
 109
 110 ### init database
 111 my $DBHandle = InitDB(\%Conf,1);
 112
 113 ### get data for each month
 114 &Bleat(1,'Test mode. Database is not updated.') if $OptTest;
 115 foreach my $Month (&ListMonth($Period)) {
 116
 117   print "---------- $Month ----------\n" if $OptDebug;
 118
 119   if ($OptStatsType eq 'all' or $OptStatsType eq 'groups') {
 120     # read list of newsgroups from --checkgroups
 121     # into a hash
 122     my %ValidGroups = %{ReadGroupList(sprintf('%s-%s',$OptCheckgroupsFile,$Month))}
 123       if $OptCheckgroupsFile;
 124
 125     ### ----------------------------------------------
 126     ### get groups data (number of postings per group)
 127     # get groups data from raw table for given month
 128     my $DBQuery = $DBHandle->prepare(sprintf("SELECT newsgroups FROM %s.%s ".
 129                                              "WHERE day LIKE ? AND NOT disregard",
 130                                              $Conf{'DBDatabase'},
 131                                              $Conf{'DBTableRaw'}));
 132     $DBQuery->execute($Month.'-%')
 133       or &Bleat(2,sprintf("Can't get groups data for %s from %s.%s: ".
 134                           "$DBI::errstr\n",$Month,
 135                           $Conf{'DBDatabase'},$Conf{'DBTableRaw'}));
 136
 137     # count postings per group
 138     my %Postings;
 139     while (($_) = $DBQuery->fetchrow_array) {
 140       # get list of newsgroups and hierarchies from Newsgroups:
 141       my %Newsgroups = ListNewsgroups($_,$TLH,
 142                                       $OptCheckgroupsFile ? \%ValidGroups : '');
 143       # count each newsgroup and hierarchy once
 144       foreach (sort keys %Newsgroups) {
 145         $Postings{$_}++;
 146       };
 147     };
 148
 149     # add valid but empty groups if --checkgroups is set
 150     if (%ValidGroups) {
 151       foreach (sort keys %ValidGroups) {
 152         if (!defined($Postings{$_})) {
 153           # add current newsgroup as empty group
 154           $Postings{$_} = 0;
 155           warn (sprintf("ADDED: %s as empty group\n",$_));
 156           # add empty hierarchies for current newsgroup as needed
 157           foreach (ParseHierarchies($_)) {
 158             my $Hierarchy = $_ . '.ALL';
 159             if (!defined($Postings{$Hierarchy})) {
 160               $Postings{$Hierarchy} = 0;
 161               warn (sprintf("ADDED: %s as empty group\n",$Hierarchy));
 162             };
 163           };
 164         }
 165       };
 166     };
 167
 168     # delete old data for that month
 169     if (!$OptTest) {
 170       $DBQuery = $DBHandle->do(sprintf("DELETE FROM %s.%s WHERE month = ?",
 171                                        $Conf{'DBDatabase'},$Conf{'DBTableGrps'}),
 172                                        undef,$Month)
 173         or &Bleat(2,sprintf("Can't delete old groups data for %s from %s.%s: ".
 174                             "$DBI::errstr\n",$Month,
 175                             $Conf{'DBDatabase'},$Conf{'DBTableGrps'}));
 176     };
 177
 178     print "----- GroupStats -----\n" if $OptDebug;
 179     foreach my $Newsgroup (sort keys %Postings) {
 180       print "$Newsgroup => $Postings{$Newsgroup}\n" if $OptDebug;
 181       if (!$OptTest) {
 182         # write to database
 183         $DBQuery = $DBHandle->prepare(sprintf("INSERT INTO %s.%s ".
 184                                               "(month,newsgroup,postings) ".
 185                                               "VALUES (?, ?, ?)",
 186                                               $Conf{'DBDatabase'},
 187                                               $Conf{'DBTableGrps'}));
 188         $DBQuery->execute($Month, $Newsgroup, $Postings{$Newsgroup})
 189           or &Bleat(2,sprintf("Can't write groups data for %s/%s to %s.%s: ".
 190                               "$DBI::errstr\n",$Month,$Newsgroup,
 191                               $Conf{'DBDatabase'},$Conf{'DBTableGrps'}));
 192         $DBQuery->finish;
 193       };
 194     };
 195   } else {
 196     # other types of information go here - later on
 197   };
 198 };
 199
 200 ### close handles
 201 $DBHandle->disconnect;
 202
 203 __END__
 204
 205 ################################ Documentation #################################
 206
 207 =head1 NAME
 208
 209 gatherstats - process statistical data from a raw source
 210
 211 =head1 SYNOPSIS
 212
 213 B<gatherstats> [B<-Vhdt>] [B<-m> I<YYYY-MM> | I<YYYY-MM:YYYY-MM>] [B<-s> I<stats>] [B<-c> I<filename template>]] [B<--hierarchy> I<TLH>] [B<--rawdb> I<database table>] [B<-groupsdb> I<database table>] [B<--clientsdb> I<database table>] [B<--hostsdb> I<database table>] [B<--conffile> I<filename>]
 214
 215 =head1 REQUIREMENTS
 216
 217 See L<doc/README>.
 218
 219 =head1 DESCRIPTION
 220
 221 This script will extract and process statistical information from a
 222 database table which is fed from F<feedlog.pl> for a given time period
 223 and write its results to (an)other database table(s). Entries marked
 224 with I<'disregard'> in the database will be ignored; currently, you
 225 have to set this flag yourself, using your database management tools.
 226 You can exclude erroneous entries that way (e.g. automatic reposts
 227 (think of cancels flood and resurrectors); spam; ...).
 228
 229 The time period to act on defaults to last month; you can assign
 230 another time period or a single month via the B<--month> option (see
 231 below).
 232
 233 By default B<gatherstats> will process all types of information; you
 234 can change that using the B<--stats> option and assigning the type of
 235 information to process. Currently that doesn't matter yet as only
 236 processing of the number of postings per group per month is
 237 implemented anyway.
 238
 239 Possible information types include:
 240
 241 =over 3
 242
 243 =item B<groups> (postings per group per month)
 244
 245 B<gatherstats> will examine Newsgroups: headers. Crosspostings will be
 246 counted for each single group they appear in. Groups not in I<TLH>
 247 will be ignored.
 248
 249 B<gatherstats> will also add up the number of postings for each
 250 hierarchy level, but only count each posting once. A posting to
 251 de.alt.test will be counted for de.alt.test, de.alt.ALL and de.ALL,
 252 respectively. A crossposting to de.alt.test and de.alt.admin, on the
 253 other hand, will be counted for de.alt.test and de.alt.admin each, but
 254 only once for de.alt.ALL and de.ALL.
 255
 256 Data is written to I<DBTableGrps> (see L<doc/INSTALL>); you can
 257 override that default through the B<--groupsdb> option.
 258
 259 =back
 260
 261 =head2 Configuration
 262
 263 B<gatherstats> will read its configuration from F<newsstats.conf>
 264 which should be present in etc/ via Config::Auto or from a configuration file
 265 submitted by the B<--conffile> option.
 266
 267 See L<doc/INSTALL> for an overview of possible configuration options.
 268
 269 You can override configuration options via the B<--hierarchy>,
 270 B<--rawdb>, B<--groupsdb>, B<--clientsdb> and B<--hostsdb> options,
 271 respectively.
 272
 273 =head1 OPTIONS
 274
 275 =over 3
 276
 277 =item B<-V>, B<--version>
 278
 279 Print out version and copyright information and exit.
 280
 281 =item B<-h>, B<--help>
 282
 283 Print this man page and exit.
 284
 285 =item B<-d>, B<--debug>
 286
 287 Output debugging information to STDOUT while processing (number of
 288 postings per group).
 289
 290 =item B<-t>, B<--test>
 291
 292 Do not write results to database. You should use B<--debug> in
 293 conjunction with B<--test> ... everything else seems a bit pointless.
 294
 295 =item B<-m>, B<--month> I<YYYY-MM[:YYYY-MM]>
 296
 297 Set processing period to a single month in YYYY-MM format or to a time
 298 period between two month in YYYY-MM:YYYY-MM format (two month, separated
 299 by a colon).
 300
 301 =item B<-s>, B<--stats> I<type>
 302
 303 Set processing type to one of I<all> and I<groups>. Defaults to all
 304 (and is currently rather pointless as only I<groups> has been
 305 implemented).
 306
 307 =item B<-c>, B<--checkgroups> I<filename template>
 308
 309 Check each group against a list of valid newsgroups read from a file,
 310 one group on each line and ignoring everything after the first
 311 whitespace (so you can use a file in checkgroups format or (part of)
 312 your INN active file).
 313
 314 The filename is taken from I<filename template>, amended by each
 315 B<--month> B<gatherstats> is processing in the form of I<template-YYYY-MM>,
 316 so that
 317
 318     gatherstats -m 2010-01:2010-12 -c checkgroups
 319
 320 will check against F<checkgroups-2010-01> for January 2010, against
 321 F<checkgroups-2010-02> for February 2010 and so on.
 322
 323 Newsgroups not found in the checkgroups file will be dropped (and
 324 logged to STDERR), and newsgroups found there but having no postings
 325 will be added with a count of 0 (and logged to STDERR).
 326
 327 =item B<--hierarchy> I<TLH> (newsgroup hierarchy)
 328
 329 Override I<TLH> from F<newsstats.conf>.
 330
 331 =item B<--rawdb> I<table> (raw data table)
 332
 333 Override I<DBTableRaw> from F<newsstats.conf>.
 334
 335 =item B<--groupsdb> I<table> (postings per group table)
 336
 337 Override I<DBTableGrps> from F<newsstats.conf>.
 338
 339 =item B<--clientsdb> I<table> (client data table)
 340
 341 Override I<DBTableClnts> from F<newsstats.conf>.
 342
 343 =item B<--hostsdb> I<table> (host data table)
 344
 345 Override I<DBTableHosts> from F<newsstats.conf>.
 346
 347 =item B<--conffile> I<filename>
 348
 349 Load configuration from I<filename> instead of F<newsstats.conf>.
 350
 351 =back
 352
 353 =head1 INSTALLATION
 354
 355 See L<doc/INSTALL>.
 356
 357 =head1 EXAMPLES
 358
 359 Process all types of information for lasth month:
 360
 361     gatherstats
 362
 363 Do a dry run, showing results of processing:
 364
 365     gatherstats --debug --test
 366
 367 Process all types of information for January of 2010:
 368
 369     gatherstats --month 2010-01
 370
 371 Process only number of postings for the year of 2010,
 372 checking against checkgroups-*:
 373
 374     gatherstats -m 2010-01:2010-12 -s groups -c checkgroups
 375
 376 =head1 FILES
 377
 378 =over 4
 379
 380 =item F<bin/gatherstats.pl>
 381
 382 The script itself.
 383
 384 =item F<lib/NewsStats.pm>
 385
 386 Library functions for the NewsStats package.
 387
 388 =item F<etc/newsstats.conf>
 389
 390 Runtime configuration file.
 391
 392 =back
 393
 394 =head1 BUGS
 395
 396 Please report any bugs or feature requests to the author or use the
 397 bug tracker at L<http://bugs.th-h.de/>!
 398
 399 =head1 SEE ALSO
 400
 401 =over 2
 402
 403 =item -
 404
 405 L<doc/README>
 406
 407 =item -
 408
 409 L<doc/INSTALL>
 410
 411 =back
 412
 413 This script is part of the B<NewsStats> package.
 414
 415 =head1 AUTHOR
 416
 417 Thomas Hochstein <thh@inter.net>
 418
 419 =head1 COPYRIGHT AND LICENSE
 420
 421 Copyright (c) 2010-2013 Thomas Hochstein <thh@inter.net>
 422
 423 This program is free software; you may redistribute it and/or modify it
 424 under the same terms as Perl itself.
 425
 426 =cut