.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "EXIMSTATS 8"
.TH EXIMSTATS 8 2024-04-07 "perl v5.38.2" EXIM4
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
eximstats \- generates statistics from Exim mainlog or syslog files.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& eximstats [Output] [Options] mainlog1 mainlog2 ...
\& eximstats \-merge [Options] report.1.txt report.2.txt ... > weekly_report.txt
.Ve
.SS Output:
.IX Subsection "Output:"
.IP \fB\-txt\fR 4
.IX Item "-txt"
Output the results in plain text to STDOUT.
.IP \fB\-txt\fR=\fIfilename\fR 4
.IX Item "-txt=filename"
Output the results in plain text. Filename '\-' for STDOUT is accepted.
.IP \fB\-html\fR 4
.IX Item "-html"
Output the results in HTML to STDOUT.
.IP \fB\-html\fR=\fIfilename\fR 4
.IX Item "-html=filename"
Output the results in HTML. Filename '\-' for STDOUT is accepted.
.IP \fB\-xls\fR 4
.IX Item "-xls"
Output the results in Excel compatible Format to STDOUT.
Requires the Spreadsheet::WriteExcel CPAN module.
.IP \fB\-xls\fR=\fIfilename\fR 4
.IX Item "-xls=filename"
Output the results in Excel compatible format. Filename '\-' for STDOUT is accepted.
.SS Options:
.IX Subsection "Options:"
.IP \fB\-h\fR\fInumber\fR 4
.IX Item "-hnumber"
histogram divisions per hour. The default is 1, and
0 suppresses histograms. Valid values are:
.Sp
0, 1, 2, 3, 5, 10, 15, 20, 30 or 60.
.IP \fB\-ne\fR 4
.IX Item "-ne"
Don't display error information.
.IP \fB\-nr\fR 4
.IX Item "-nr"
Don't display relaying information.
.IP \fB\-nr\fR\fI/pattern/\fR 4
.IX Item "-nr/pattern/"
Don't display relaying information that matches.
.IP \fB\-nt\fR 4
.IX Item "-nt"
Don't display transport information.
.IP \fB\-nt\fR\fI/pattern/\fR 4
.IX Item "-nt/pattern/"
Don't display transport information that matches
.IP \fB\-q\fR\fIlist\fR 4
.IX Item "-qlist"
List of times for queuing information single 0 item suppresses.
.IP \fB\-t\fR\fInumber\fR 4
.IX Item "-tnumber"
Display top <number> sources/destinations
default is 50, 0 suppresses top listing.
.IP \fB\-tnl\fR 4
.IX Item "-tnl"
Omit local sources/destinations in top listing.
.IP \fB\-t_remote_users\fR 4
.IX Item "-t_remote_users"
Include remote users in the top source/destination listings.
.IP \fB\-include_original_destination\fR 4
.IX Item "-include_original_destination"
Include the original destination email addresses rather than just
using the final ones.
Useful for finding out which of your mailing lists are receiving mail.
.IP \fB\-show_dt\fR\fIlist\fR 4
.IX Item "-show_dtlist"
Show the delivery times (\fBDT\fR)for all the messages.
.Sp
Exim must have been configured to use the +deliver_time logging option
for this option to work.
.Sp
\&\fIlist\fR is an optional list of times. Eg \-show_dt1,2,4,8 will show
the number of messages with delivery times under 1 second, 2 seconds, 4 seconds,
8 seconds, and over 8 seconds.
.IP \fB\-show_rt\fR\fIlist\fR 4
.IX Item "-show_rtlist"
Show the receipt times for all the messages. The receipt time is
defined as the Completed hh:mm:ss \- queue_time_overall \- the Receipt hh:mm:ss.
These figures will be skewed by pipelined messages so might not be that useful.
.Sp
Exim must have been configured to use the +queue_time_overall logging option
for this option to work.
.Sp
\&\fIlist\fR is an optional list of times. Eg \-show_rt1,2,4,8 will show
the number of messages with receipt times under 1 second, 2 seconds, 4 seconds,
8 seconds, and over 8 seconds.
.IP \fB\-byhost\fR 4
.IX Item "-byhost"
Show results by sending host. This may be combined with
\&\fB\-bydomain\fR and/or \fB\-byemail\fR and/or \fB\-byedomain\fR. If none of these options
are specified, then \fB\-byhost\fR is assumed as a default.
.IP \fB\-bydomain\fR 4
.IX Item "-bydomain"
Show results by sending domain.
May be combined with \fB\-byhost\fR and/or \fB\-byemail\fR and/or \fB\-byedomain\fR.
.IP \fB\-byemail\fR 4
.IX Item "-byemail"
Show results by sender's email address.
May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR and/or \fB\-byedomain\fR.
.IP "\fB\-byemaildomain\fR or \fB\-byedomain\fR" 4
.IX Item "-byemaildomain or -byedomain"
Show results by sender's email domain.
May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR and/or \fB\-byemail\fR.
.IP "\fB\-pattern\fR \fIDescription\fR \fI/Pattern/\fR" 4
.IX Item "-pattern Description /Pattern/"
Look for the specified pattern and count the number of lines in which it appears.
This option can be specified multiple times. Eg:
.Sp
.Vb 1
\& \-pattern \*(AqRefused connections\*(Aq \*(Aq/refused connection/\*(Aq
.Ve
.IP \fB\-merge\fR 4
.IX Item "-merge"
This option allows eximstats to merge old eximstat reports together. Eg:
.Sp
.Vb 9
\& eximstats mainlog.sun > report.sun.txt
\& eximstats mainlog.mon > report.mon.txt
\& eximstats mainlog.tue > report.tue.txt
\& eximstats mainlog.wed > report.web.txt
\& eximstats mainlog.thu > report.thu.txt
\& eximstats mainlog.fri > report.fri.txt
\& eximstats mainlog.sat > report.sat.txt
\& eximstats \-merge       report.*.txt > weekly_report.txt
\& eximstats \-merge \-html report.*.txt > weekly_report.html
.Ve
.RS 4
.IP \(bu 4
You can merge text or html reports and output the results as text or html.
.IP \(bu 4
You can use all the normal eximstat output options, but only data
included in the original reports can be shown!
.IP \(bu 4
When merging reports, some loss of accuracy may occur in the top \fIn\fR lists.
This will be towards the ends of the lists.
.IP \(bu 4
The order of items in the top \fIn\fR lists may vary when the data volumes
round to the same value.
.RE
.RS 4
.RE
.IP \fB\-charts\fR 4
.IX Item "-charts"
Create graphical charts to be displayed in HTML output.
Only valid in combination with \fI\-html\fR.
.Sp
This requires the following modules which can be obtained
from http://www.cpan.org/modules/01modules.index.html
.RS 4
.IP GD 4
.IX Item "GD"
.PD 0
.IP GDTextUtil 4
.IX Item "GDTextUtil"
.IP GDGraph 4
.IX Item "GDGraph"
.RE
.RS 4
.PD
.Sp
To install these, download and unpack them, then use the normal perl installation procedure:
.Sp
.Vb 4
\& perl Makefile.PL
\& make
\& make test
\& make install
.Ve
.Sp
On \fBDebian GNU/Linux\fR you can use
\&\f(CW\*(C`apt\-get install libgd\-perl libgd\-text\-perl libgd\-graph\-perl\*(C'\fR
instead.
.RE
.IP "\fB\-chartdir\fRI <dir>" 4
.IX Item "-chartdirI <dir>"
Create the charts in the directory <dir>
.IP "\fB\-chartrel\fRI <dir>" 4
.IX Item "-chartrelI <dir>"
Specify the relative directory for the "img src=" tags from where to include
the charts
.IP \fB\-emptyok\fR 4
.IX Item "-emptyok"
Specify that it's OK to not find any valid log lines. Without this
we will output an error message if we don't find any.
.IP \fB\-d\fR 4
.IX Item "-d"
Debug flag. This outputs the \fBeval()\fR'd parser onto STDOUT which makes it
easier to trap errors in the eval section. Remember to add 1 to the line numbers to allow for the
title!
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Eximstats parses exim mainlog and syslog files to output a statistical
analysis of the messages processed. By default, a text
analysis is generated, but you can request other output formats
using flags. See the help (\fB\-help\fR) to learn
about how to create charts from the tables.
.SH AUTHOR
.IX Header "AUTHOR"
There is a website at https://www.exim.org/.
.SH "TO DO"
.IX Header "TO DO"
This program does not perfectly handle messages whose received
and delivered log lines are in different files, which can happen
when you have multiple mail servers and a message cannot be
immediately delivered. Fixing this could be tricky...
.PP
Merging of xls files is not (yet) possible. Be free to implement :)