Adds manual test for alerts, topics and handlers with documentation

docs/Integration---Alert-Topic-Handler.md

+<!--
+// © University of Southampton IT Innovation Centre, 2018
+//
+// Copyright in this software belongs to University of Southampton
+// IT Innovation Centre of Gamma House, Enterprise Road, 
+// Chilworth Science Park, Southampton, SO16 7NS, UK.
+//
+// This software may not be used, sold, licensed, transferred, copied
+// or reproduced in whole or in part in any manner or form or in or
+// on any media by any person other than in accordance with the terms
+// of the Licence Agreement supplied with the software, or otherwise
+// without the prior written consent of the copyright owners.
+//
+// This software is distributed WITHOUT ANY WARRANTY, without even the
+// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE, except where stated in the Licence Agreement supplied with
+// the software.
+//
+//      Created By :            Nikolay Stanchev
+//      Created Date :          09-08-2018
+//      Created for Project :   FLAME
+-->
+
+# **FLAME - Integration of alerts, topics and handlers**
+
+#### **Authors**
+
+|Authors|Organisation|                    
+|---|---|  
+|[Nikolay Stanchev](mailto:ns17@it-innovation.soton.ac.uk)|[University of Southampton, IT Innovation Centre](http://www.it-innovation.soton.ac.uk)|
+
+
+#### Description
+
+This document describes the step to follow in order to reproduce a full integration of a Kapacitor alert,
+topic and handler. The alert handler is a HTTP POST handler, which posts data to a test HTTP server. The
+server expects only POST messages and simply logs any request content that it receives into a file 
+(***/var/log/alert-test.log***). The scenario was used to manually test the integration of alerts, topics and handlers in Kapacitor.
+
+
+#### Steps to reproduce the integration
+
+* Set up and ssh into the *default* virtual machine with the usual commands:
+```bash
+vagrant up
+vagrant ssh
+sudo su
+```
+
+* Create the *clmc-service* container:
+```bash
+/vagrant/scripts/test/fixture.sh create -f /vagrant/src/test/clmctest/rspec.json -c clmc-service
+lxc-attach -n clmc-service
+```
+
+* Navigate to the alerts folder start the HTTP server - the server listens to localhost
+ connections on port 9999:
+```bash
+cd /vagrant/src/test/clmctest/alerts
+python3 http_server.py > /dev/null 2>&1 &
+```
+
+* (Optional) Verify the server is running - should return ***SUCCESSFUL GET REQUEST*** 
+in the response body:
+```bash
+curl http://localhost:9999/
+```
+
+* Add a new alert in Kapacitor that will trigger an alert every 10s and enable the task: 
+ ```bash
+kapacitor define alert_id -tick alert_example.tick
+kapacitor enable alert_id
+```
+
+* Verify the task and the topics were created:
+```bash
+kapacitor list tasks
+kapacitor list topics
+```
+
+**N.B.** The topic will be created once the first alert has been triggered,
+hence you might have to wait a few seconds for the task to trigger an alert.
+
+* Subscribe to the created topic with id ***http_topic***:
+```bash
+kapacitor define-topic-handler handler_example.yaml
+```
+
+* (Optional) Verify the topic handler was created:
+```bash
+kapacitor show-topic-handler http_topic handler_id
+```
+
+* Verify the log file has been created and is populated with content:
+```bash
+cat /var/log/alert-test.log
+```
+
+* Tear down the test scenario by killing the http server:
+
+*find the PID of the http server*
+```bash
+ps -ef | grep http_server
+```
+
+*kill the server*
+```bash
+kill <PID>
+```

src/test/clmctest/alerts/alert_example.tick

+dbrp "_internal"."monitor"
+
+batch
+    |query('''
+        SELECT mean(numSeries) as mean
+        FROM "_internal"."monitor"."database"
+    ''')
+        .period(10s)
+        .every(10s)
+    |alert()
+        .crit(lambda: "mean" > 1)
+        .message('TRUE')
+        .topic('http_topic')
\ No newline at end of file

src/test/clmctest/alerts/handler_example.yaml

+id: handler_id
+topic: http_topic
+kind: post
+options:
+  url: http://localhost:9999/
+  headers:
+    'Content-Type': 'text/html'
\ No newline at end of file

src/test/clmctest/alerts/http_server.py

+from http.server import HTTPServer, BaseHTTPRequestHandler
+import logging
+
+
+logger = logging.getLogger('alerts-test')
+logger.setLevel(logging.DEBUG)
+fh = logging.FileHandler("/var/log/alert-test.log")
+fh.setLevel(logging.DEBUG)
+logger.addHandler(fh)
+
+
+class CustomHTTPHandler(BaseHTTPRequestHandler):
+
+    def _set_headers(self):
+        self.send_response(200)
+        self.send_header('Content-type', 'text/html')
+        self.end_headers()
+
+    def do_POST(self):
+        content_length = int(self.headers['Content-Length'])
+        post_data = self.rfile.read(content_length)
+        logger.debug(post_data)
+
+    def do_GET(self):
+        self._set_headers()
+        self.wfile.write(b"<html><body><h1>SUCCESSFUL GET REQUEST</h1></body></html>")
+
+
+def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
+    server_address = ('localhost', 9999)
+    httpd = server_class(server_address, handler_class)
+    httpd.serve_forever()
+
+
+if __name__ == "__main__":
+    run(handler_class=CustomHTTPHandler)