diff --git a/packages/xo-server-perf-alert/.USAGE.md b/packages/xo-server-perf-alert/.USAGE.md
index 8368fbaf609..9045adf9d54 100644
--- a/packages/xo-server-perf-alert/.USAGE.md
+++ b/packages/xo-server-perf-alert/.USAGE.md
@@ -1,2 +1,10 @@
 Like all xo-server plugins, it can be configured directly via
 the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html).
+
+Monitors can be defined in the plugin configuration. These can monitor the storage usage of your SRs, the CPU usage or memory usage of your hosts and VMs.
+
+A separate alarm is created for each monitored element. This alarm will be raised when an element exceeds the defined threshold (on average during the last minute), and it will be lowered when it falls back below the threshold. An email alert is sent in both of those cases, and also if a problem is encountered when trying to access the stats of a monitored element.
+
+To ensure that each alert email is only sent once, the boolean state of each alarm is stored with an ID, e.g. `host|memoryUsage|40|803c2676-c309-721e-7123-e6c3de854c32` is the ID corresponding to the alarm that is raised when host `803c2676-c309-721e-7123-e6c3de854c32` exceeds 40% memory usage.
+
+You can use the "Test plugin" option to receive an email containing the list of the monitors you have configured, and the status of the elements monitored.
diff --git a/packages/xo-server-perf-alert/README.md b/packages/xo-server-perf-alert/README.md
index 65125992ae6..d2a9266a72e 100644
--- a/packages/xo-server-perf-alert/README.md
+++ b/packages/xo-server-perf-alert/README.md
@@ -9,6 +9,14 @@
 Like all xo-server plugins, it can be configured directly via
 the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html).
 
+Monitors can be defined in the plugin configuration. These can monitor the storage usage of your SRs, the CPU usage or memory usage of your hosts and VMs.
+
+A separate alarm is created for each monitored element. This alarm will be raised when an element exceeds the defined threshold (on average during the last minute), and it will be lowered when it falls back below the threshold. An email alert is sent in both of those cases, and also if a problem is encountered when trying to access the stats of a monitored element.
+
+To ensure that each alert email is only sent once, the boolean state of each alarm is stored with an ID, e.g. `host|memoryUsage|40|803c2676-c309-721e-7123-e6c3de854c32` is the ID corresponding to the alarm that is raised when host `803c2676-c309-721e-7123-e6c3de854c32` exceeds 40% memory usage.
+
+You can use the "Test plugin" option to receive an email containing the list of the monitors you have configured, and the status of the elements monitored.
+
 ## Contributions
 
 Contributions are _very_ welcomed, either on the documentation or on