Update documentation.
- Fix clientstats doc (copied from hoststats). - Add some more examples ro README. Signed-off-by: Thomas Hochstein <thh@thh.name>
This commit is contained in:
parent
0b87e81b08
commit
66890b68d8
11 changed files with 329 additions and 263 deletions
|
|
@ -275,7 +275,7 @@ clientstats - create reports on client usage
|
|||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<clientstats> [B<-Vhcs> B<--comments>] [B<-m> I<YYYY-MM>[:I<YYYY-MM>] | I<all>] [B<-n> I<client(s)>] [B<-r> I<report type>] [B<-l> I<lower boundary>] [B<-u> I<upper boundary>] [B<-g> I<group by>] [B<-o> I<order by>] [B<-f> I<output format>] [B<--filetemplate> I<filename template>] [B<--db> I<database table>] [B<--conffile> I<filename>]
|
||||
B<clientstats> [B<-Vhcsv> B<--comments>] [B<-m> I<YYYY-MM>[:I<YYYY-MM>] | I<all>] [B<-n> I<client(s)>] [B<-r> I<report type>] [B<-l> I<lower boundary>] [B<-u> I<upper boundary>] [B<-g> I<group by>] [B<-o> I<order by>] [B<-f> I<output format>] [B<--filetemplate> I<filename template>] [B<--db> I<database table>] [B<--conffile> I<filename>]
|
||||
|
||||
=head1 REQUIREMENTS
|
||||
|
||||
|
|
@ -323,18 +323,19 @@ 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 B<--format> option. Captions will be added by means of
|
||||
the B<--caption> option; all comments (and captions) can be supressed by
|
||||
using B<--nocomments>.
|
||||
postings with the B<--format> option. Captions will be added by means
|
||||
of the B<--caption> option; all comments (and captions) can be
|
||||
supressed by using B<--nocomments>.
|
||||
|
||||
Last but not least you can redirect all output to a number of files, e.g.
|
||||
one for each month, by submitting the B<--filetemplate> option, see below.
|
||||
Last but not least you can redirect all output to a number of files,
|
||||
e.g. one for each month, by submitting the B<--filetemplate> option,
|
||||
see below.
|
||||
|
||||
=head2 Configuration
|
||||
|
||||
B<clientstats> will read its configuration from F<newsstats.conf>
|
||||
which should be present in etc/ via Config::Auto or from a configuration file
|
||||
submitted by the B<--conffile> option.
|
||||
which should be present in etc/ via Config::Auto or from a configuration
|
||||
file submitted by the B<--conffile> option.
|
||||
|
||||
See doc/INSTALL for an overview of possible configuration options.
|
||||
|
||||
|
|
@ -346,32 +347,47 @@ You can override some configuration options via the B<--db> option.
|
|||
|
||||
=item B<-V>, B<--version>
|
||||
|
||||
Print out version and copyright information and exit.
|
||||
Display version and copyright information and exit.
|
||||
|
||||
=item B<-h>, B<--help>
|
||||
|
||||
Print this man page and exit.
|
||||
Display this man page and exit.
|
||||
|
||||
=item B<-m>, B<--month> I<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 I<all> instead, you can set no
|
||||
processing period to process the whole database.
|
||||
processing period to process the whole database. Defaults to last month.
|
||||
|
||||
=item B<-n>, B<--names> I<name(s)>
|
||||
|
||||
Limit processing to a certain set of client names. I<names(s)>
|
||||
can be a single name (eternal-september.org), a group of names
|
||||
(*.inka.de) or a list of either of these, separated by colons, for
|
||||
example
|
||||
can be a single name (Thunderbird), a group of names (Ice*) or a list
|
||||
of either of these, separated by colons, for example
|
||||
|
||||
eternal-september.org:solani.org:*.inka.de
|
||||
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.
|
||||
|
||||
=item B<-s>, B<--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.
|
||||
containing the sum of all detected clients for that month. False
|
||||
by default.
|
||||
|
||||
=item B<-v>, B<--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.
|
||||
|
||||
=item B<-r>, B<--report> I<default|sums>
|
||||
|
||||
|
|
@ -379,7 +395,7 @@ Choose the report type: I<default> or I<sums>
|
|||
|
||||
By default, B<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.
|
||||
per client for all months. Sums of B<--versions> can be included.
|
||||
|
||||
For report type I<sums>, the B<group-by> option has no meaning and
|
||||
will be silently ignored (see below).
|
||||
|
|
@ -395,10 +411,10 @@ 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.
|
||||
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.
|
||||
|
||||
=item B<-g>, B<--group-by> I<month[-desc]|name[-desc]>
|
||||
|
||||
|
|
@ -406,38 +422,38 @@ By default, all results are grouped by month, sorted chronologically in
|
|||
ascending order, like this:
|
||||
|
||||
# ----- 2012-01:
|
||||
arcor-online.net : 9379
|
||||
individual.net : 19525
|
||||
news.albasani.net: 9063
|
||||
40tude_Dialog: 5873
|
||||
Forte Agent : 7735
|
||||
Thunderbird : 20925
|
||||
# ----- 2012-02:
|
||||
arcor-online.net : 8606
|
||||
individual.net : 16768
|
||||
news.albasani.net: 7879
|
||||
40tude_Dialog: 4142
|
||||
Forte Agent : 5895
|
||||
Thunderbird : 19091
|
||||
|
||||
The results can be grouped by client instead via
|
||||
B<--group-by> I<name>:
|
||||
|
||||
----- individual.net
|
||||
2012-01: 19525
|
||||
2012-02: 16768
|
||||
----- arcor-online.net
|
||||
2012-01: 9379
|
||||
2012-02: 8606
|
||||
----- news.albasani.net
|
||||
2012-01: 9063
|
||||
2012-02: 7879
|
||||
# ----- 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 I<-desc> to the group-by option parameter, you can reverse
|
||||
the sort order - e.g. B<--group-by> I<month-desc> will give:
|
||||
|
||||
# ----- 2012-02:
|
||||
arcor-online.net : 8606
|
||||
individual.net : 16768
|
||||
news.albasani.net: 7879
|
||||
40tude_Dialog: 4142
|
||||
Forte Agent : 5895
|
||||
Thunderbird : 19091
|
||||
# ----- 2012-01:
|
||||
arcor-online.net : 9379
|
||||
individual.net : 19525
|
||||
news.albasani.net: 9063
|
||||
40tude_Dialog: 5873
|
||||
Forte Agent : 7735
|
||||
Thunderbird : 20925
|
||||
|
||||
Sums reports (see above) will always be grouped by months; this option
|
||||
will therefore be ignored.
|
||||
|
|
@ -449,41 +465,57 @@ 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.
|
||||
|
||||
=item B<-f>, B<--format> I<pretty|list|dump>
|
||||
|
||||
Select the output format, I<pretty> being the default:
|
||||
By default, output is sorted alphabetically:
|
||||
|
||||
# ----- 2012-01:
|
||||
arcor-online.net : 9379
|
||||
individual.net : 19525
|
||||
40tude_Dialog: 5873
|
||||
Forte Agent : 7735
|
||||
Thunderbird : 20925
|
||||
|
||||
Using B<--order-by> I<postings[-desc]>, it will be sorted from most
|
||||
to least postings:
|
||||
|
||||
# ----- 2012-01:
|
||||
Thunderbird : 20925
|
||||
Forte Agent : 7735
|
||||
40tude_Dialog: 5873
|
||||
|
||||
=item B<-f>, B<--format> I<pretty|list|dump>
|
||||
|
||||
Select the output format, I<pretty> (a kind of table) being the default:
|
||||
|
||||
# ----- 2012-01:
|
||||
40tude_Dialog: 5873
|
||||
Forte Agent : 7735
|
||||
# ----- 2012-02:
|
||||
arcor-online.net : 8606
|
||||
individual.net : 16768
|
||||
40tude_Dialog: 4142
|
||||
Forte Agent : 5895
|
||||
|
||||
I<list> format looks like this:
|
||||
I<list> format looks like this (each client preceded by month):
|
||||
|
||||
2012-01 arcor-online.net 9379
|
||||
2012-01 individual.net 19525
|
||||
2012-02 arcor-online.net 8606
|
||||
2012-02 individual.net 16768
|
||||
2012-01 40tude_Dialog 5873
|
||||
2012-01 Forte Agent 7735
|
||||
2012-02 40tude_Dialog 4142
|
||||
2012-02 Forte Agent 5895
|
||||
|
||||
And I<dump> format looks like this:
|
||||
|
||||
# 2012-01:
|
||||
arcor-online.net 9379
|
||||
individual.net 19525
|
||||
40tude_Dialog 5873
|
||||
Forte Agent 7735
|
||||
# 2012-02:
|
||||
arcor-online.net 8606
|
||||
individual.net 16768
|
||||
40tude_Dialog 4142
|
||||
Forte Agent 5895
|
||||
|
||||
You can remove the comments by using B<--nocomments>, see below.
|
||||
You can remove the comments (lines after '#') by using B<--nocomments>,
|
||||
see below.
|
||||
|
||||
=item B<-c>, B<--captions|--nocaptions>
|
||||
|
||||
Add captions to output, like this:
|
||||
|
||||
----- Report for 2012-01 to 2012-02 (number of postings for each month)
|
||||
----- Names: individual.net
|
||||
----- Names: Thunderbird
|
||||
----- Threshold: 8000 => x (counting only month fulfilling this condition)
|
||||
----- Grouped by Month (ascending), sorted by number of postings descending
|
||||
|
||||
|
|
@ -491,11 +523,11 @@ False by default.
|
|||
|
||||
=item B<--comments|--nocomments>
|
||||
|
||||
Add comments (group headers) to I<dump> and I<pretty> output. True by default
|
||||
as logn as B<--filetemplate> is not set.
|
||||
Add comments (group headers) to I<dump> and I<pretty> output. True by
|
||||
default as long as B<--filetemplate> is not set.
|
||||
|
||||
Use I<--nocomments> to suppress anything except client names or months and
|
||||
numbers of postings.
|
||||
Use I<--nocomments> to suppress anything except client names or months
|
||||
and numbers of postings.
|
||||
|
||||
=item B<--filetemplate> I<filename template>
|
||||
|
||||
|
|
@ -515,7 +547,7 @@ Override I<DBTableClnts> or I<DBTableClnts> from F<newsstats.conf>.
|
|||
|
||||
=item B<--conffile> I<filename>
|
||||
|
||||
Load configuration from I<filename> instead of F<newsstats.conf>.
|
||||
Read configuration from I<filename> instead of F<newsstats.conf>.
|
||||
|
||||
=back
|
||||
|
||||
|
|
@ -525,26 +557,26 @@ See L<doc/INSTALL>.
|
|||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Show number of postings per group for lasth month in I<pretty> format:
|
||||
Show number of postings per client for lasth month in I<pretty> format:
|
||||
|
||||
clientstats
|
||||
|
||||
Show that report for January of 2010 and *.inka plus individual.net:
|
||||
Show that report for January of 2010 and Thunderbird plus Ice*:
|
||||
|
||||
clientstats --month 2010-01 --names *.inka:individual.net:
|
||||
clientstats --month 2010-01 --names 'Thunderbird:Ice*'
|
||||
|
||||
Only show clients with 30 postings or less last month, ordered
|
||||
by number of postings, descending, in I<pretty> format:
|
||||
Only show clients with at least 30 postings last month and the versions
|
||||
of those clients, ordered each by number of postings, descending,
|
||||
in I<pretty> format:
|
||||
|
||||
clientstats --upper 30 --order-by postings-desc
|
||||
clientstats --lower 30 --versions --order-by postings-desc
|
||||
|
||||
List number of postings per host for each month of 2010 and redirect
|
||||
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
|
||||
|
||||
|
||||
=head1 FILES
|
||||
|
||||
=over 4
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue