docs: add observability documentation

Author: jeboehm

.mkdocs.yaml

@@ -40,6 +40,8 @@ nav:
       - administration/dns-validation-wizard.md
       - administration/user-roles.md
       - administration/ios-macos-profile.md
+  - Observability:
+      - observability/intro.md
   - Recipes:
       - Docker:
           - Traefik Reverse Proxy: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/compose/traefik-reverse-proxy

docs/images/admin/obs_dovecot.png

@@ -0,0 +1,45 @@
+# Observability
+
+Observability is the ability to understand a system's internal state by examining its external outputs, crucial for complex, modern software systems.
+
+`mailserver-admin` provides observability features for monitoring the mailserver components, enabling administrators to monitor service health, message processing statistics, and operational metrics through web-based dashboards.
+
+## Overview
+
+The observability features integrate with the Rspamd filter service and Dovecot mail delivery agent to collect and display real-time statistics and historical trends. These dashboards provide visibility into message processing, spam filtering effectiveness, authentication patterns, and mail delivery rates.
+
+## Rspamd Statistics
+
+The Rspamd Statistics dashboard displays metrics from the Rspamd controller service, providing insights into spam filtering operations and message processing.
+
+![Rspamd Statistics](images/admin/obs_rspamd.png)
+
+The dashboard includes:
+
+- **Service Status**: Health check indicator showing Rspamd controller availability and response time
+- **Summary Metrics**: Key performance indicators including:
+  - Total messages scanned
+  - Spam messages detected
+  - Ham (clean) messages identified
+  - Messages used for machine learning
+  - Active connections to the service
+- **Throughput Chart**: Time-series visualization of message processing rates per minute, showing action distributions including rejections, soft rejections, subject rewrites, header additions, greylisting, and no-action messages. Supports time aggregation for day, week, month, and year views
+- **Action Distribution**: Donut chart showing the proportion of messages categorised by Rspamd actions (clean, rejected, temporarily rejected, probable spam, greylisted)
+- **Configuration Details**: Displays action thresholds and top symbols used in spam scoring
+
+## Dovecot Statistics
+
+The Dovecot Statistics dashboard presents metrics from the Dovecot mail delivery agent via the Doveadm HTTP API, focusing on authentication and mail delivery operations.
+
+![Dovecot Statistics](images/admin/obs_dovecot.png)
+
+The dashboard provides:
+
+- **API Status**: Connection status and authentication verification for the Doveadm HTTP API, including last update timestamp
+- **Summary Metrics**: Overview cards showing:
+  - Authentication successes
+  - Authentication failures
+  - Index operations count
+- **Authentication Rate Chart**: Time-series graph displaying authentication success and failure rates per minute, enabling identification of authentication patterns and potential security issues
+- **Mail Deliveries Chart**: Time-series visualization of mail delivery rates per minute, showing message throughput to user mailboxes
+- **Data Collection**: Charts are calculated from consecutive samples, with rates computed as deltas between measurements

docs/images/admin/obs_rspamd.png

@@ -4,6 +4,16 @@ Upgrade guide for docker-mailserver.
 
 When upgrading, ensure that container configuration files are updated to match the requirements of the new version. Review the manifests in `deploy/compose` and `deploy/kustomize` for any changes to persistent volumes or configuration, and update them as necessary. If new environment variables have been introduced, update the `.env` file accordingly.
 
+## v7.3
+
+`mailserver-admin` now provides observability features for the mailserver. To make sure the service to service communication works, the
+following environment variables have been added:
+
+- `MDA_DOVEADM_ADDRESS`: The address of the MDA service for Dovecot API access. (default: `mda:8080`)
+- `DOVEADM_API_KEY`: The API key for Dovecot API access.
+
+Please make sure to change at least `DOVEADM_API_KEY`.
+
 ## v7.1
 
 - **web**: mailserver-admin now includes a feature to generate mobileconfig files for iOS and macOS. These files are signed with the same TLS certificate that the mailserver displays to connecting clients. To generate these files, it’s necessary to mount the certificate to the web container.