5.4 The mailstats Program

The sendmail program provides the ability to gather information that can be used to produce valuable statistics. As you will see, the StatusFile (S) option (StatusFile) is used to specify a file into which delivery agent statistics can be saved. The mailstats(1) program prints a summary of those statistics.

5.4.1 The statistics File

The sendmail program can maintain an ongoing record of the total number and total sizes of all outgoing and incoming mail messages handled by each delivery agent. This ability is enabled by defining STATUS_FILE in your m4 build file:

define(`STATUS_FILE',`/path')

The /path is the full pathname of the file into which statistics are saved. Version 8.12 sendmail provides configuration files that specify /path as:

/etc/mail/statistics

Just declaring the StatusFile option is not enough, however, for if the file does not exist (or is unwritable), sendmail silently ignores that file and does not save statistics. To avoid this behavior, sendmail creates an empty file during installation:

% touch /etc/mail/statistics

Note that the gathering of statistics can be turned off merely by renaming or removing the file.

5.4.2 Viewing Statistics: mailstats

The mailstats program is supplied with the sendmail source distribution to provide a convenient way to print the contents of the statistics file. The output of the mailstats program varies depending on the version of sendmail installed. For V8.12 sendmail the output looks like this:

Statistics from Mon Jan 14 10:56:15 2002
 M   msgsfr  bytes_from   msgsto    bytes_to  msgsrej msgsdis  Mailer
 0        0          0K     4063      25765K        0       0  prog
 3      267        336K        0          0K        0       0  local
 5     4120       6188K      142       1652K      672       0  esmtp
=  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==   
 T     4387       6524K     4205      27417K      672       0
 C     4387                 4205                  672

The first line shows when the statistics file was begun. The lines that follow show the number of messages and the total size, in kilobytes, of those messages, both received (msgsfr and bytes_from), and sent (msgsto and bytes_to), for each delivery agent. V8.9 and above sendmail also shows the number of rejected messages (msgsrej) and discarded messages (msgsdis). The M column shows the index into the internal array of delivery agents, and the Mailer column shows the symbolic name. Note that if a delivery agent handled no traffic, it is excluded from the report.

The last two lines show totals. The line that begins with T shows the totals for the columns above. The line that begins with C shows totals for connections, the corresponding daemon-accept connections (inbound), client connections (outbound), and rejected connections. The two can show different totals when there are multiple envelopes per connection.

Command-line arguments are available to modify this output. We describe them beginning in Section 5.4.4.

5.4.3 Using cron for Daily and Weekly Statistics

The mailstats program prints the contents of the statistics file, but it does not zero the counters in that file. To clear (zero) that file, you need to truncate it. One easy way to do this is:

# cp /dev/null /etc/mail/statistics

When sendmail discovers an empty statistics file, it begins gathering statistics all over again. One use for truncation is to collect daily reports from mailstats. Consider the following simple shell script:

#!/bin/sh
ST=/etc/mail/statistics
MS=/usr/etc/mailstats
if [ -s $ST -a -f $MS ]; then
        $MS | mail -s "Daily mail stats" postmaster
        cp /dev/null $ST
fi
exit 0

When run, this script checks to see whether a nonempty statistics file and the mailstats program both exist. If they do, mailstats is run, printing the statistics, which are then mailed to postmaster. The statistics file is then truncated to a size of zero. Such a script could be run once per night using the cron(8) facility with a crontab(5) entry like this:

0 0 * * * sh /usr/ucb/mailstats.script >/dev/null 2>&1

Here, mailstats.script is the name given to the earlier shell script, and the 0 0 causes that script to be executed once per day at midnight.

Moving and renaming the statistics file allows one to automatically collect daily copies of that file. Consider the following variation on the previous shell script:

#!/bin/sh
BASE=/etc/mail
ST=statistics
MS=${BASE}/stats_arch
if [ -d $BASE ]; then
        cd $BASE
        if [ -s $ST -a -d $MS ]; then
                mailstats | mail -s "Daily mail stats" postmaster
                test -f ${MS}/${ST}.5 && mv ${MS}/${ST}.5 ${MS}/${ST}.6
                test -f ${MS}/${ST}.4 && mv ${MS}/${ST}.4 ${MS}/${ST}.5
                test -f ${MS}/${ST}.3 && mv ${MS}/${ST}.3 ${MS}/${ST}.4
                test -f ${MS}/${ST}.2 && mv ${MS}/${ST}.2 ${MS}/${ST}.3
                test -f ${MS}/${ST}.1 && mv ${MS}/${ST}.1 ${MS}/${ST}.2
                test -f ${MS}/${ST}.0 && mv ${MS}/${ST}.0 ${MS}/${ST}.1
                test -f ${ST}         && mv ${ST}         ${MS}/${ST}.0
                touch ${ST}
        fi
fi
exit 0

As before, the statistics are mailed to postmaster. But instead of being truncated, the statistics file is renamed stats_arch/statistics.0. A series of renames (mv(1)) are used to maintain a week's worth of copies. These copies allow the ambitious administrator to create a program for gathering weekly summaries from seven archived daily copies.

The mailstats program allows you to specify a different name for the statistics file. By using the -f command-line switch, you can view statistics from any of the archived files:

% mailstats -f /etc/mail/stats_arch/statistics.4

5.4.4 The mailstats Program's Switches

The mailstats program has a modest number of command-line switches. They are summarized in Table 5-5 and described more fully in the sections that follow.