docs/alerts: explain how alerts work and their issues

README.md

@@ -11,7 +11,7 @@ software for details.
 
 ## Description
 
-This is Red Hat 3scale API Management Platform's Backend.
+This is the Red Hat 3scale API Management backend.
 
 It has the following components:
 
@@ -86,6 +86,15 @@ This component may also be referred to as 'backend-cron'.
 
 See the file [DEVELOPMENT](DEVELOPMENT.md)
 
+## Documentation
+
+You can find documentation about Apisonator (also called referred to as `3scale
+backend`) at the [Red Hat 3scale API Management product pages](https://access.redhat.com/products/red-hat-3scale/).
+
+Documentation about specific parts of Apisonator (APIs, specs, behaviour, etc)
+can be found in the [`docs`](https://github.com/3scale/apisonator/tree/master/docs) folder, though this is mostly meant for development and design purposes rather
+than user documentation.
+
 ## How to run
 
 ### Prerequisites

docs/alerts.md

@@ -0,0 +1,40 @@
+## How do Utilization Alerts work?
+
+Utilization alerts work in a way that surprises some users, typically wondering
+why a specific utilization alert has not been notified. Here is a description of
+how they work so that users can understand why that is the case.
+
+### Utilization percentages
+
+Apisonator will emit alerts to the administrative instance for traffic crossing
+the following utilization percentage of an application _if configured to do so_:
+
+0, 50, 80, 90, 100, 120, 150, 200, 300
+
+However, only one alert percentage is to be notified in any given 24h period.
+
+### Alert notification
+
+Alerts are only sent **once** in any given 24 hours period for each application and
+utilization percentage regardless of the period for which the utilization
+percentage was computed.
+
+This means that once a configured alert is emitted for a particular application,
+such as 120% utilization for any period (ie. minute), no alert will be emitted
+for that particular application and utilization level for the next 24 hours,
+even if the utilization that would reach 120% would be applying to a different
+period (ie. hour), or even if the alert would be emitted for a different metric.
+
+If, however, the utilization percentage would have not been notified in the
+previous 24 hours, such as 150, then it is notified.
+
+### Issues
+
+This behaviour is surprising to users because they might expect an alert
+notified the last day to be "forgotten" by the next day even though 24h have not
+really elapsed.
+
+There is also the additional issue that alerts that could not be sent are stored
+for sending later on, but the code requires another actual alert to be generated
+in order for those pending alerts to be sent. This is usually not a big deal but
+still has potential for edge cases to behave very weirdly.