NAME
    clientstats - create reports on client usage

SYNOPSIS
    clientstats [-Vhcsv --comments] [-m *YYYY-MM*[:*YYYY-MM*] | *all*] [-n
    *client(s)*] [-r *report type*] [-l *lower boundary*] [-u *upper
    boundary*] [-g *group by*] [-o *order by*] [-f *output format*]
    [--filetemplate *filename template*] [--db *database table*] [--conffile
    *filename*]

REQUIREMENTS
    See "README" in doc.

DESCRIPTION
    This script create reports on newsgroup usage (number of postings using
    each client per month) taken from result tables created by
    gatherstats.pl.

  Features and options
   Time period and names
    The time period to act on defaults to last month; you can assign another
    time period or a single month (or drop all time constraints) via the
    --month option (see below).

    clientstats will process all clients by default; you can limit
    processing to only some clients by supplying a list of those names by
    using the --names option (see below).

   Report type
    You can choose between different --report types: postings per month or
    all postings summed up; for details, see below.

   Upper and lower boundaries
    Furthermore you can set an upper and/or lower boundary to exclude some
    results from output via the --lower and --upper options, respectively.
    By default, all clients with more and/or less postings per month will be
    excluded from the result set (i.e. not shown and not considered for sum
    reports).

   Sorting and formatting the output
    By default, all results are grouped by month; you can group results by
    clients instead via the --group-by option. Within those groups, the list
    of clients (or months) is sorted alphabetically (or chronologically,
    respectively) ascending. You can change that order (and sort by number
    of postings) with the --order-by option. For details and exceptions,
    please see below.

    The results will be formatted as a kind of table; you can change the
    output format to a simple list or just a list of names and number of
    postings with the --format option. Captions will be added by means of
    the --caption option; all comments (and captions) can be supressed by
    using --nocomments.

    Last but not least you can redirect all output to a number of files,
    e.g. one for each month, by submitting the --filetemplate option, see
    below.

  Configuration
    clientstats will read its configuration from newsstats.conf which should
    be present in etc/ via Config::Auto or from a configuration file
    submitted by the --conffile option.

    See doc/INSTALL for an overview of possible configuration options.

    You can override some configuration options via the --db option.

OPTIONS
    -V, --version
       Display version and copyright information and exit.

    -h, --help
       Display this man page and exit.

    -m, --month *YYYY-MM[:YYYY-MM]|all*
       Set processing period to a single month in YYYY-MM format or to a
       time period between two month in YYYY-MM:YYYY-MM format (two month,
       separated by a colon). By using the keyword *all* instead, you can
       set no processing period to process the whole database. Defaults to
       last month.

    -n, --names *name(s)*
       Limit processing to a certain set of client names. *names(s)* can be
       a single name (Thunderbird), a group of names (Ice*) or a list of
       either of these, separated by colons, for example

          Forte Agent:Thunderbird:Ice*

       Spaces or special characters like "*" need to be quoted from the
       shell, like

          -n 'Forte Agent:Thunderbird:Ice*'

       There is no way to limit processing to a specific version, but you
       can alway grep through the output.

    -s, --sums|--nosums (sum per month)
       Include "virtual" clients named "ALL" for every month in output,
       containing the sum of all detected clients for that month. False by
       default.

    -v, --versions|--noversions (client versions)
       Include a list of all observed versions of each client in output.
       Version information will be displayed with indents ('-') below each
       client, sorted in the same way (by postings or alphanumeric). False
       by default.

    -r, --report *default|sums*
       Choose the report type: *default* or *sums*

       By default, clientstats will report the number of postings for each
       client in each month. But it can also report the total sum of
       postings per client for all months. Sums of --versions can be
       included.

       For report type *sums*, the group-by option has no meaning and will
       be silently ignored (see below).

    -l, --lower *lower boundary*
       Set the lower boundary. See below.

    -l, --upper *upper boundary*
       Set the upper boundary.

       By default, all clients with more postings per month than the upper
       boundary and/or less postings per month than the lower boundary will
       be excluded from further processing. For the default report that
       means each month only clients with a number of postings between the
       boundaries will be displayed. For the sums report, clients with a
       number of postings exceeding the boundaries in all (!) months will
       not be considered.

    -g, --group-by *month[-desc]|name[-desc]*
       By default, all results are grouped by month, sorted chronologically
       in ascending order, like this:

           # ----- 2012-01:
           40tude_Dialog:  5873
           Forte Agent  :  7735
           Thunderbird  : 20925
           # ----- 2012-02:
           40tude_Dialog:  4142
           Forte Agent  :  5895
           Thunderbird  : 19091

       The results can be grouped by client instead via --group-by *name*:

           # ----- 40tude_Dialog:
           2012-01:  5873
           2012-02:  4142
           # ----- Forte Agent:
           2012-01:  7735
           2012-02:  5895
           # ----- Thunderbird:
           2012-01: 20925
           2012-02: 19091

       By appending *-desc* to the group-by option parameter, you can
       reverse the sort order - e.g. --group-by *month-desc* will give:

           # ----- 2012-02:
           40tude_Dialog:  4142
           Forte Agent  :  5895
           Thunderbird  : 19091
           # ----- 2012-01:
           40tude_Dialog:  5873
           Forte Agent  :  7735
           Thunderbird  : 20925

       Sums reports (see above) will always be grouped by months; this
       option will therefore be ignored.

    -o, --order-by *default[-desc]|postings[-desc]*
       Within each group (a single month or single client, see above), the
       report will be sorted by name (or month) in ascending alphabetical
       order by default. You can change the sort order to descending or sort
       by number of postings instead.

       By default, output is sorted alphabetically:

           # ----- 2012-01:
           40tude_Dialog:  5873
           Forte Agent  :  7735
           Thunderbird  : 20925

       Using --order-by *postings[-desc]*, it will be sorted from most to
       least postings:

           # ----- 2012-01:
           Thunderbird  : 20925
           Forte Agent  :  7735
           40tude_Dialog:  5873

    -f, --format *pretty|list|dump*
       Select the output format, *pretty* (a kind of table) being the
       default:

           # ----- 2012-01:
           40tude_Dialog:  5873
           Forte Agent  :  7735
           # ----- 2012-02:
           40tude_Dialog:  4142
           Forte Agent  :  5895

       *list* format looks like this (each client preceded by month):

           2012-01 40tude_Dialog 5873
           2012-01 Forte Agent 7735
           2012-02 40tude_Dialog 4142
           2012-02 Forte Agent 5895

       And *dump* format looks like this:

           # 2012-01:
           40tude_Dialog 5873
           Forte Agent 7735
           # 2012-02:
           40tude_Dialog 4142
           Forte Agent 5895

       You can remove the comments (lines after '#') by using --nocomments,
       see below.

    -c, --captions|--nocaptions
       Add captions to output, like this:

           ----- Report for 2012-01 to 2012-02 (number of postings for each month)
           ----- Names: Thunderbird
           ----- Threshold: 8000 => x (counting only month fulfilling this condition)
           ----- Grouped by Month (ascending), sorted by number of postings descending

       False by default.

    --comments|--nocomments
       Add comments (group headers) to *dump* and *pretty* output. True by
       default as long as --filetemplate is not set.

       Use *--nocomments* to suppress anything except client names or months
       and numbers of postings.

    --filetemplate *filename template*
       Save output to file(s) instead of dumping it to STDOUT. clientstats
       will create one file for each month (or each client, according to the
       setting of --group-by, see above), with filenames composed by adding
       year and month (or client names) to the *filename template*, for
       example with --filetemplate *stats*:

           stats-2012-01
           stats-2012-02
           ... and so on

    --db *database table*
       Override *DBTableClnts* or *DBTableClnts* from newsstats.conf.

    --conffile *filename*
       Read configuration from *filename* instead of newsstats.conf.

INSTALLATION
    See "INSTALL" in doc.

EXAMPLES
    Show number of postings per client for lasth month in *pretty* format:

        clientstats

    Show that report for January of 2010 and Thunderbird plus Ice*:

        clientstats --month 2010-01 --names 'Thunderbird:Ice*'

    Only show clients with at least 30 postings last month and the versions
    of those clients, ordered each by number of postings, descending, in
    *pretty* format:

        clientstats --lower 30 --versions --order-by postings-desc

    List number of postings per client for each month of 2010 and redirect
    output to one file for each month, named hosts-2010-01 and so on, in
    machine-readable form (without formatting):

        clientstats -m 2010-01:2010-12 -f dump --filetemplate hosts

FILES
    bin/clientstats.pl
        The script itself.

    lib/NewsStats.pm
        Library functions for the NewsStats package.

    etc/newsstats.conf
        Runtime configuration file.

BUGS
    Please report any bugs or feature requests to the author or use the bug
    tracker at <https://code.virtcomm.de/thh/newsstats/issues>!

SEE ALSO
    - "README" in doc

    - "INSTALL" in doc

    - gatherstats -h

    This script is part of the NewsStats package.

AUTHOR
    Thomas Hochstein <thh@thh.name>

COPYRIGHT AND LICENSE
    Copyright (c) 2025 Thomas Hochstein <thh@thh.name>

    This program is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.

