add-metric-docs

manual/administration/seafile_metrics.md

@@ -0,0 +1,48 @@
+# Integrate Seafile Metrics with Third-Party Monitoring Tools
+Seafile provides a standardized interface to expose system operational metrics, enabling integration with third-party monitoring tools such as Prometheus and Grafana.
+This allows administrators to real-time monitor Seafile service status, including (but not limited to)  I/O queue length and background task latency.
+
+
+## Configuration Steps
+To enable metric monitoring for Seafile, follow these steps:
+
+### 1. Enable Metric Exposure
+Edit the Seafile configuration file `seahub_settings.py` (located in the Seafile configuration directory) and add the following configuration items. If the items already exist, update their values accordingly:
+
+```python
+# Enable the metric exposure function (set to True to activate)
+ENABLE_METRIC = True
+
+# Authentication username for monitoring tools (e.g., Prometheus)
+# Used for HTTP Basic Authentication when accessing Seafile's metric endpoint
+METRIC_AUTH_USER = "your_prometheus_username"
+
+# Authentication password corresponding to the above username
+METRIC_AUTH_PWD = "your_prometheus_password"
+```
+
+> **Note**: Replace `your_prometheus_username` and `your_prometheus_password` with custom credentials (recommend using strong, unique passwords for security).
+
+
+### 2. Configure Third-Party Monitoring Tools
+After completing the above Seafile configuration, monitoring tools can retrieve Seafile metrics via the `/metrics` endpoint. Key requirements for tool configuration:
+
+* Endpoint: Seafile’s metric data is accessible at `http://<seafile-server-ip>:<port>/metrics` (replace `<seafile-server-ip>` and `<port>` with your Seafile server’s actual IP and port).
+* Authentication: Use HTTP Basic Authentication and input the `METRIC_AUTH_USER` and `METRIC_AUTH_PWD` configured in Step 1.
+* Data Scraping: For tools like Prometheus, configure a scrape job to periodically pull data from the `/metrics` endpoint (refer to Prometheus documentation for details).
+
+
+For detailed configuration guides of monitoring tools, refer to the official documentation below:
+
+* [Prometheus Official Documentation - Configuration](https://prometheus.io/docs/prometheus/latest/getting_started/)
+  Learn how to set up Prometheus scrape jobs, data storage, and metric query rules.
+* [Grafana Official Documentation - Prometheus Data Source](https://grafana.com/docs/grafana/latest/datasources/prometheus/)
+  Learn how to connect Grafana to Prometheus, create visual dashboards, and set up alert rules.
+
+
+## Effect Description
+Once the configuration is complete:
+
+1. Prometheus will periodically scrape Seafile metrics from the `/metrics` endpoint (based on the configured scrape interval).
+2. You can create custom visual dashboards in Grafana (e.g., "Seafile Monitoring Dashboard" ) to visualize metrics in real time.
+3. Alerts can be set up in Grafana (e.g., trigger an alert when Seafile storage usage exceeds 90%) to proactively monitor system health.

mkdocs.yml

@@ -188,6 +188,7 @@ nav:
     - Seafile FSCK: administration/seafile_fsck.md
     - Seafile GC: administration/seafile_gc.md
     - Clean database: administration/clean_database.md
+    - Integrate Seafile Metrics with Third-Party Monitoring Tools: administration/seafile_metrics.md
   - Upgrade:
     - Outline: upgrade/upgrade.md
     - Upgrade Seafile Docker: upgrade/upgrade_docker.md