From 6ac9d92e538a3aaf50ab2fe8b9c2b4b9fa7d0181 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Thu, 19 Dec 2024 13:55:33 -0700
Subject: [PATCH] doveadm-stats: Rewrite man page

---
 docs/core/man/doveadm-stats.1.md | 114 +++++++++++++++++++++----------
 1 file changed, 79 insertions(+), 35 deletions(-)

diff --git a/docs/core/man/doveadm-stats.1.md b/docs/core/man/doveadm-stats.1.md
index 79eb2bad8..f7633677d 100644
--- a/docs/core/man/doveadm-stats.1.md
+++ b/docs/core/man/doveadm-stats.1.md
@@ -8,66 +8,110 @@ dovecotComponent: core
 
 ## SYNOPSIS
 
-**doveadm stats dump** [ **-s \<stats socket path\>** ] **\<type\>** [ **\<filter\>** ]
+**doveadm** [*GLOBAL OPTIONS*] **stats add** [ **-\-description** *\<string\>* ] [ **-\-exporter** *\<name\>* ] [ **-\-exporter-include** *\<fields\>* ] [ **-\-fields** *\<fields\>* ] [**-\-group_by** *\<fields\>* ] *name* *\<filter\>*
 
-**doveadm stats top** [ **-s \<stats socket path\>** ] [ **-b** ] [ **sort** *\<field\>* ]
+**doveadm** [*GLOBAL OPTIONS*] **stats dump** [ **-s** *\<stats socket path\>* ] [ **-r** ] [ **-f** *\<fields\>* ]
 
-**doveadm stats reset** [ **-s \<stats socket path\>** ]
+**doveadm** [*GLOBAL OPTIONS*] **stats remove** [ *\<name\>* ]
 
-**doveadm stats add** [ **-\-description** *\<string\>* ] [ **-\-exporter** *\<name\>* ] [ **-\-exporter-include** *\<field\>* ] [ **-\-fields** *\<fields\>* ] [**-\-group_by** *\<fields\>* ] **\<name\>** *\<filter\>*
+**doveadm** [*GLOBAL OPTIONS*] **stats reopen**
 
-**doveadm stats remove** *\<name\>*
+## DESCRIPTION
 
-**doveadm stats reopen**
+Commands to inspect and edit Dovecot stats/metrics generation.
 
-## DESCRIPTION
+<!-- @include: include/global-options.inc -->
 
-**doveadm stats dump** is used to output statistics
+## COMMANDS
 
-**doveadm stats top** is used to monitor statistics
+### stats add
 
-**doveadm stats reset** is used to reset statistics
+**doveadm** [*GLOBAL OPTIONS*] **stats add** [ **-\-description** *\<string\>* ] [ **-\-exporter** *\<name\>* ] [ **-\-exporter-include** *\<fields\>* ] [ **-\-fields** *\<fields\>* ] [**-\-group_by** *\<fields\>* ] *name* *\<filter\>*
 
-**doveadm stats add** is used to add metrics to statistics
+**doveadm stats add** is used to add metrics to statistics.
 
-**doveadm stats remove** is used to remove metrics from statistics
+#### OPTIONS
 
-**doveadm stats reopen** is used to reopen any file exporter files.
+**--description** *\<string\>*
+:   Human-readable description of the metric. This is included in the HELP text
+    sent to OpenMetrics.
 
-## OPTIONS
+**--exporter** *\<name\>*
+:   Export events matching the filter with this event exporter.
+    If empty, the events are used only for statistics, and no exporting is done.
 
-**-s** *socketpath*
-:   Sets stats socket path
+**--exporter-include** *\<fields\>*
+:   Specifies which parts of the event are exported to the serialized event.
+    The fields are space-separated.
+
+**--fields** *\<fields\>*
+:   A list of fields included in the metric. All events have a default `duration`
+    field that does not need to be listed explicitly.
+
+**--group-by** *\<fields\>*
+:   Creates a new group_by for dynamically generating sub-metrics based on the
+    specified field's values.
+
+#### ARGUMENTS
+
+*name*
+:   Metric name.
+
+*filter*
+:   Filter options:
+
+    - **user=\<wildcard\>**
+      :   Match user.
+
+    - **domain=\<wildcard\>**
+      :   Match DNS domain name.
 
-**-b**
-:   Show disk input/output bytes
+    - **session=\<str\>**
+      :   Match session identifier.
 
-## ARGUMENTS
+    - **ip=\<ip\>[/\<mask\>]**
+      :   Match local or remote IP.
 
-**dump** accepts following types: command, session, user, domain, ip and
-global.
+    - **since=\<timestamp\>**
+      :   Match session start time.
 
-Filter can be
+    - **connected**
+      :   Show only connected sessions.
 
-**user=\<wildcard\>**
-:   Match given user.
+### stats dump
 
-**domain=\<wildcard\>**
-:   Match given DNS domain name
+**doveadm** [*GLOBAL OPTIONS*] **stats dump** [ **-s** *\<stats socket path\>* ] [ **-r** ] [ **-f** *\<fields\>* ]
 
-**session=\<str\>**
-:   Match session identifier
+**doveadm stats dump** is used to output statistics.
 
-**ip=\<ip\>[/\<mask\>]**
-:   Match local or remote IP
+#### OPTIONS
 
-**since=\<timestamp\>**
-:   Match session start time
+**-f**
+:   TODO
 
-**connected**
-:   Show only connected sessions
+**-r**
+:   Resets statistics after dumping.
 
-**top** accepts any valid field name to sort along with.
+**-s** *socketpath*
+:   Stats socket path.
+
+### stats remove
+
+**doveadm** [*GLOBAL OPTIONS*] **stats remove** [ *\<name\>* ]
+
+**doveadm stats remove** is used to remove metrics from statistics.
+
+#### ARGUMENTS
+
+*name*
+
+:   The metric name to remove.
+
+### stats reopen
+
+**doveadm** [*GLOBAL OPTIONS*] **stats reopen**
+
+**doveadm stats reopen** is used to reopen any file exporter files.
 
 <!-- @include: include/reporting-bugs.inc -->