[pmg-devel] [PATCH pmg-docs 2/2] administration: add section for statistics

[Stoiko Ivanov]

Thanks for addressing this - This should make the experience for our users
much better, and reduce quite a few support-requests!

In general it looks good to me and could be merged as is

One high-level suggestion and a few nits inline (could be a follow-up as
well):

Since Statistics is its own entry in the GUI's navigation tree - why not
have it as a dedicated chapter of the docs? (quickly tried it here - just
putting it in a file of its own, and raising the heading levels by one
(`-` -> `=`, `~` -> `-`) and including it in pmg-adminstration-guide.adoc
seems to work fine)

It's not a strict necessity, and the docs to GUI matching is not 100%
currently either (Backup/Restore is its own chapter, but under
Configuration on the GUI for example)

Let me know what you think (and if you'll find the time soon to address it
or if I should send the suggestions as follow-up)

On Fri, 24 Mar 2023 14:30:13 +0100
Dominik Csapak <d.csapak at proxmox.com> wrote:

> by explaining each panel and it's options
> 
> Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
> ---
>  pmg-administration.adoc | 117 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 117 insertions(+)
> 
> diff --git a/pmg-administration.adoc b/pmg-administration.adoc
> index 05f4589..c4b83c4 100644
> --- a/pmg-administration.adoc
> +++ b/pmg-administration.adoc
> @@ -238,3 +238,120 @@ You can view the complete headers and filter by sender or receiver of
>  queued emails.
>  
>  Here, you can also flush or delete each deferred email independently.
> +
> +
> +[[pmg_statistics]]
> +Statistics
> +----------
> +
> +{pmg} offers a useful and feature-rich statistics interface, which allows the
> +admins to quickly see the general workload and makes it easy to identify
s/admins/administrators/ ?
> +problems.
> +
> +The statistics are shown for the selected time range, which defaults to the
> +current day, but can be changed to any other day, a whole month, or even a
> +whole year.
> +
> +On the man statistics page there are three graphs with additional data:
s/man/main/

> +
> +'Total Mail Count'::
> +
> +Shows the total mail flow as a graph and the following details:
> +
> +* Total Mails
> +* Incoming/Outgoing Mails (as count and percentage)
> +* Virus Outbreaks (the amount of outgoing virus mails)
> +* Avg. Mail Processing Time
> +* Incoming/Outgoing Mail Traffic
> +
> +'Incoming Mails'::
> +
> +Shows the incoming mail counts as a graph and the following details
> +(as counts and percentages of the incoming mail volume):
> +
> +* Incoming Mails
> +* Junk Mails (Virus + Spam + Greylisted + SPF rejects + RBL rejects)
> +* Greylisted Mails
> +* Spam Mails (Mails with Spamscore >= 3 and no virus)
s/and no virus/and not containing a virus/?

> +* SPF rejects
> +* Bounces (mails without a sender)
s/without a sender/with an empty envelope-sender address/ ?
> +* Virus Mails
> +
> +'Outgoing Mails'::
> +
> +Shows the outgoing mail counts as a graph and the following details
> +(as counts and percentages of the incoming mail volume):
s/incoming/outgoing/ 

> +
> +* Outgoing Mails
> +* Bounces (mails without a sender)
as above - s/without a sender/with an empty envelope-sender address/ ?

> +* Virus Mails
> +
> +Spam Scores
> +~~~~~~~~~~~
> +
> +This panel shows the mail count and percentage of the different spam scores
> +for the selected time frame.
s/mail count and percentage/distribution/ ?

> +
> +Virus Charts
> +~~~~~~~~~~~~
> +
> +This panel shows which and how many viruses were detected in the selected
> +time frame.
> +
> +Hourly Distribution
> +~~~~~~~~~~~~~~~~~~~
> +
> +Shows the amount of incoming and outgoing mail per hour for the selected
> +time frame.
> +
> +Postscreen
> +~~~~~~~~~~
> +
> +Contains a chart with the RBL and pregreet rejects for the selected time frame.
> +For more info about postscreen and pregreet tests, see the
> +https://www.postfix.org/POSTSCREEN_README.html[postfix postscreen readme].
s/postfix// ?

> +
> +Domain
> +~~~~~~
> +
> +Here is a summary for the recipient domain of the incoming and outgoing mails
> +of the selected time frame, with traffic, count, how many viruses were detected,
> +and how much of it was spam.
s/Here is/Contains/ ?

> +
> +Sender
> +~~~~~~
> +
> +This panel contains a list of e-mail addresses that sent mail out in the
> +selected time frame, with a total count, how many viruses were detected and how
> +big these mails were.
> +
> +If you click on one of these e-mail addresses, you see a detailed list of
> +recipients, complete with size, date and time.
> +
> +Receiver
> +~~~~~~~~
> +
> +Analog to the `Sender` panel, this contains a list of e-mail addresses that
> +received e-mails from outside, with a total, spam and virus count, as well
> +as the total mail size.
s/Analog/Similar/ ?

> +
> +If you click an entry, it shows a detailed list of mails with size, date,
> +time, virus and spam score info.
> +
> +If the `advanced statistics filters` are active, only active accounts will be
> +listed. Active accounts are those which sent mail in the selected time frame
> +or up to 90 days before.
> +
> +Contact
> +~~~~~~~
> +
> +This contains the reverse list to the `Receiver` panel, namely a list of
> +external recipients that received mail from this {pmg}, with total count,
> +virus count and size.
Not sure if 'the reverse list' is easily understandable here?
Maybe:
This contains the list of external recipients that received mail from this
{pmg}, coming in on the internal port, with total count, virus count and
size. ?

> +
> +If you click an entry, it shows a list of mails with size, date and time.
> +
> +If the `advanced statistics filters` are active, active accounts will be
> +filtered out, since they can already be seen in the `Receiver` panel. Active
> +accounts are those which sent mail in the selected time frame or up to 90 days
> +before.