monitor: README & notes +1

stack/monitor/note.md

 Monitor
 =======
 
-Activate monitoring
--------------------
+This stack has for purpose to know if all promises went/are ok.
 
-Create a new buildout:
+It provides a web interface, to see which promises failed. It also provide a rss
+feed to easily know the actual state of your instance, and to know when it
+started to went bad.
 
-    [buildout]
-    extends =
-      monitor_url
-      my_software_url
+Index:
 
+- Activate monitoring for you software
+- Add a monitor promise
+- Information about URL access
+- Monitor promise configuration example
+- Promise requirements
+- monitor.haljson example
+- monitor.conf example
 
-KVM Log access + parsing
-------------------------
 
-Open HTTP GET on static files, open HTTP POST on cgi, make cron to run bin/monitor.py
-
-    GET  <root_monitor>/                              // classical monitoring interface
-    GET  <root_monitor>/monitor.haljson               // monitor conf
-    GET  <root_monitor>/public/<service>.status.json  // service status json
+Activate monitoring for your software
+-------------------------------------
 
-KVM Example
+You just have to extend the monitor stack from your software.cfg.
 
-    GET  <kvm_monitor>/monitor.haljson
-    GET  <kvm_monitor>/public/kvm-log-parser.status.json
-    GET  <kvm_monitor>/public/kvm-log-parser/index.html
-    POST <kvm_monitor>/cgi-bin/monitor-run-promise.cgi?service=kvm-log-parse  // rerun the promise
+You can also create a new buildout which extends your software, and the
+monitoring stack:
 
-Tree for monitor runtime
+    [buildout]
+    extends =
+      monitor_url
+      my_software_url
 
-    etc/monitor.conf             // generated by slapos
-    etc/cron.d/monitor           // generated by slapos
-    bin/monitor.py               // generated by slapos  // import var/monitor/run/X.py as plop;  plop.run(**conf [parameter] section)
-    srv/monitor/index.html       // generated by slapos
-    srv/monitor/monitor.css      // static
-    srv/monitor/monitor.js       // static
-    srv/monitor/monitor.haljson  // generated by monitor.py
-    srv/monitor/public/....      // generated by monitor.py
-    srv/monitor/private/....     // generated by monitor.py
+In your instance.cfg, your publish section should be named `[publish]` in order
+to extends the one of the monitoring stack.
 
-KVM Example
+Then, in the same file you can configure the monitor by adding this section:
 
-    etc/monitor-promise/kvm-log-parse.cfg                                                                    // generated by slapos (kvm-log-parser-promise)
-    etc/monitor-promise/kvm-log-parse                                                                        // generated by slapos (kvm-log-parser-promise)
-    var/kvm-log-parser-promise/interface/index.html                                                          // generated by slapos (kvm-log-parser-promise)
-    var/log/kvm.log                                                                                          // generated by kvm
-    var/log/kvm-log-parse-last-report.csv                                                                    // generated by kvm-log-parse
-    srv/monitor/public/kvm-log-parse.status.json                                                             // generated by kvm-log-parse (indirectly by the monitor promise executor)
-    srv/monitor/public/kvm-log-parse/kvm.log -> var/log/kvm.log                                              // generated by monitor.py
-    srv/monitor/public/kvm-log-parse/interface -> var/kvm-log-parser-promise/interface                       // generated by monitor.py
-    srv/monitor/public/kvm-log-parse/kvm-log-parse-last-report.csv -> var/log/kvm-log-parse-last-report.csv  // genareted by monitor.py
+    [monitor-instance-parameter]
+    monitor-httpd-ipv6 = ...
+    monitor-httpd-port = ...
+    monitor-title = ...
 
 
 Add a monitor promise
 ---------------------
 
-For instance, we want to create a promise for kvm log parsing. Add these sections somewhere:
+For instance, we want to create a promise for KVM log parsing. Add these
+sections in its instance.cfg:
 
     [directory]
     monitor-promise = ${:etc}/monitor-promise
@@ -90,7 +80,7 @@ We can optionaly add promise title:
     [kvm-log-parser-promise-parameter]
     frequency = */5 * * * *
 
-Optionaly, we also want an custom interface:
+Optionaly, we also want a custom interface:
 
     [directory]
     kvm-log-parser-promise-interface-dir = ....../interface
@@ -113,28 +103,81 @@ service.cfg:
     {% endfor -%}
 
 
-Service config example etc/monitor.conf.d/kvm-log-parse.conf
-------------------------------------------------------------
+Information about URL access
+----------------------------
+
+Open HTTP GET on static files, open HTTP POST on cgi
 
+    GET  <root_monitor>/                              // classical monitoring interface
+    GET  <root_monitor>/monitor.haljson               // monitor conf
+    GET  <root_monitor>/public/<service>.status.json  // service status json
+
+Example for KVM log parsing promise
+
+    GET  <kvm_monitor>/monitor.haljson
+    GET  <kvm_monitor>/public/kvm-log-parser.status.json
+    GET  <kvm_monitor>/public/kvm-log-parser/index.html
+    POST <kvm_monitor>/cgi-bin/monitor-run-promise.cgi?service=kvm-log-parse  // rerun the promise
+
+
+Information about internal file tree
+------------------------------------
+
+Tree for monitor runtime:
+
+    etc/monitor.conf                 // generated by slapos
+    etc/cron.d/monitor               // generated by slapos
+    bin/monitor.py                   // generated by slapos
+    srv/monitor/web/index.html       // static
+    srv/monitor/web/monitor.css      // static
+    srv/monitor/web/monitor.js       // static
+    srv/monitor/web/monitor.haljson  // generated by monitor.py
+    srv/monitor/public/....          // generated by monitor.py
+    srv/monitor/private/....         // generated by monitor.py
+
+Example for KVM log parsing promise
+
+    etc/monitor-promise/kvm-log-parse.cfg                                                                    // generated by slapos (kvm-log-parser-promise)
+    etc/monitor-promise/kvm-log-parse                                                                        // generated by slapos (kvm-log-parser-promise)
+    var/kvm-log-parser-promise/interface/index.html                                                          // generated by slapos (kvm-log-parser-promise)
+    var/log/kvm.log                                                                                          // generated by kvm
+    var/log/kvm-log-parse-last-report.csv                                                                    // generated by kvm-log-parse
+    srv/monitor/public/kvm-log-parse.status.json                                                             // generated by kvm-log-parse (indirectly by the monitor promise executor)
+    srv/monitor/public/kvm-log-parse/kvm.log -> var/log/kvm.log                                              // generated by monitor.py
+    srv/monitor/public/kvm-log-parse/kvm-log-parse-last-report.csv -> var/log/kvm-log-parse-last-report.csv  // genareted by monitor.py
+    srv/monitor/private/kvm-log-parse/interface -> var/kvm-log-parser-promise/interface                      // generated by monitor.py
+
+
+Monitor promise config example
+------------------------------
+
+Example for KVM log parsing promise
+
+    # etc/monitor-promise/kvm-log-parse.cfg
     [service]
     title =             Kvm log parse
     frequency =         <Cron Syntax>
     public-path-list =  $instance/var/log/kvm.log  # automatically symlink to srv/monitor/public/$service/
-    private-path-list = $instance/var/log/kvm.log  # automatically symlink to srv/monitor/private/$service/
+    private-path-list = $instance/var/log          # automatically symlink to srv/monitor/private/$service/
+
+On cron, the command will be something like:
 
-on cron, the command will be `${service:frequency} ${monitor:promise-executor-path} '${monitor:service-pid-folder}/${service:name}.pid' '${service:status-path}' '${promise_path}' `
+    ${service:frequency} ${monitor:promise-executor-path} '${monitor:service-pid-folder}/${service:name}.pid' '${service:status-path}' '${promise_path}'
 
-TODO cron accepts 999 characters maximum for a command, so we should reduce the size of the cron command
+and "monitor:promise-executor-path" is a script that would run a promise if not
+already on going (see `run-promise.py`).
 
-and "monitor:promise-executor-path" is a script that would run a promise if not already on going (see `run-promise.py`)
+TODO cron accepts 999 characters maximum for a command, so we should reduce the
+size of the cron command
 
 TODO put `run-promise.py` in the software
 
 
-Promise or script requirements
-------------------------------
+Promise requirements
+--------------------
 
-A promise should check something (like web cache, not too much slow queries, ...)
+A promise should check something (like web page is well cached, there's not too
+much slow queries, ...):
 
 - MUST output the status.json in stdout
 - SHOULD output on stdout
@@ -142,8 +185,8 @@ A promise should check something (like web cache, not too much slow queries, ...
 - the status.json MUST contain "message" (string) which explains why the status is OK or bad
 
 
-srv/monitor/public/monitor.haljson for kvm instance (example)
--------------------------------------------------------------
+monitor.haljson example
+-----------------------
 
     {
       "_links": {
@@ -176,8 +219,8 @@ srv/monitor/public/monitor.haljson for kvm instance (example)
     }
 
 
-etc/monitor.conf example
-------------------------
+monitor.conf example
+--------------------
 
     [monitor]
     title =              KVM Monitoring interface