Documentation for monitoring.

docs/engine-features.md

@@ -167,6 +167,66 @@ schemas:
 * `/app/trackservice` ................. Web Application for displaying the Track-Service
 * `/app/clock` ........................ Web Application for displaying the studio clock
 
+## Monitoring
+
+You have following options to monitor the Engine:
+
+* Send mails on errors and warnings
+* Engine Status Information
+* Engine Heartbeat
+
+### Send mails on errors and warnings
+
+To activate you'll need to set some mail account within the `[monitoring]` section of your configuration.
+
+```ini
+[monitoring]
+mail_server="mail.o94.at"
+mail_server_port="587"
+mail_user="aura@o94.at"
+mail_pass="---SECRET--PASSWORD---"
+
+# If you want to send multiple adminmails, make them space separated
+admin_mail="david@subsquare.at"
+
+# Which from mailadress should be used
+from_mail="monitoring@aura.engine"
+
+# The beginning of the subject. With that you can easily apply filter rules using a mail client
+mailsubject_prefix="[Aura Engine]"
+```
+
+### Engine Status Information
+
+You can get various status fields & flags using the `/status` endpoint.
+
+> Please note this is a rather expensive call. If you need to call this on a regular basis
+for continious monitoring, the *Heartbeat* option might be preferred.
+
+### Engine Heartbeat
+
+Instead of checking all status properties, the Heartbeat only validates the vital ones
+required to run the engine. If all of those are valid, as network socket request is sent
+to a defined server.
+
+This heartbeat is sent continiously based on the configured `heartbeat_frequency`.
+
+```ini
+# Server where heartbeat info is sent to
+heartbeat_server = "127.0.0.1"
+# Some UDP port
+heartbeat_port = 43334 
+# Seconds how often the vitality of the Engine should be checked (0 = disabled)
+heartbeat_frequency = 1
+```
+
+The service receiving this heartbeat ticks can decide what to do with that information.
+One scenario could be switching to another Engine instance or any other failover scenario.
+Under `contrib/heartbeat-monitor` you'll find some sample application digesting these
+heartbeat signals.
+
+
+
 ## Read more
 
 - [Overview](/README.md)