Add recommended_metrics

docs/core/recommended_metrics.md

@@ -0,0 +1,25 @@
+---
+layout: doc
+title: Recommended Metrics
+order: 101
+dovecotlinks:
+  recommended_metrics: Recommended Metrics
+  recommended_metrics_dovecot_proxy:
+    hash: dovecot-proxy
+    text: Dovecot Proxy
+  recommended_metrics_dovecot_backend:
+    hash: dovecot-backend
+    text: Dovecot Backend
+---
+
+# Recommended Metrics
+
+<!-- @include: ../../../core/docs/core/recommended_metrics_include/header.inc -->
+
+## Dovecot Proxy
+
+<!-- @include: ../../../core/docs/core/recommended_metrics_include/proxy.inc -->
+
+## Dovecot Backend
+
+<!-- @include: ../../../core/docs/core/recommended_metrics_include/backend.inc -->

docs/core/recommended_metrics_include/backend.inc

@@ -0,0 +1,36 @@
+### Generic authentication metrics
+
+`@metric_defaults = backend` contains:
+
+`auth_successes`
+:  Number of successful authentications. See [[event,auth_request_finished]].
+
+`auth_failures`
+:  Number of unsuccessful authentications. See [[event,auth_request_finished]].
+   These are not usually expected to happen in backends. It may be useful to
+   export these events into log:
+   ```[dovecot.conf]
+   metric auth_failures {
+     exporter = log-export
+   }
+   ```
+
+### Basic mail access and delivery metrics
+
+`@metric_defaults = backend` contains:
+
+`imap_commands`
+:  Number of IMAP commands, grouped by OK/NO/BAD tagged reply.
+   See [[event,imap_command_finished]].
+
+`mail_deliveries`
+:  Number of mails delivered. See [[event,mail_delivery_finished]].
+
+`mail_submissions`
+:  Number of mails submitted for outside delivery (e.g. rejects, vacations).
+   See [[event,smtp_submit_finished]].
+
+`mail_user_session_finished`
+:  Number of mail sessions, including their RSS memory usage and user space
+   CPU usage at the time when the session was finished. See
+   [[event,mail_user_session_finished]].

docs/core/recommended_metrics_include/header.inc

@@ -0,0 +1,15 @@
+This page lists recommended metrics that allow inspecting dovecot's behavior in
+the most general situations. More specialized situations might require further
+refinements or additional statistics. For an overview of how to gather
+statistics see [[link,stats]]. A list of all available events and their fields
+can be found [[link,summary_events,here]].
+
+The following examples use the custom `log-export` exporter.
+
+```[dovecot.conf]
+event_exporter log-export {
+  format = json
+  format_args = time-rfc3339
+  transport = log
+}
+```

docs/core/recommended_metrics_include/proxy.inc

@@ -0,0 +1,16 @@
+`@metric_defaults = proxy` contains:
+
+`auth_successes`
+:  Number of successful authentications. See [[event,auth_request_finished]].
+
+`auth_failures`
+:  Number of unsuccessful authentications. See [[event,auth_request_finished]].
+   It may be useful to export these events into log:
+   ```[dovecot.conf]
+   metric auth_failures {
+     exporter = log-export
+   }
+   ```
+
+`login_aborted`
+:  Number of aborted logins, grouped by reason. See [[event,login_aborted]].