monitor: add some notes

stack/monitor/note.md

+Monitor
+=======
+
+KVM Log access + parsing
+------------------------
+
+Open HTTP GET on static files, open HTTP POST on cgi, make cron to run bin/monitor.py
+
+Tree (`<url>/` = `/srv/monitor/public/`)
+
+    GET  <root_monitor>/                       // classical monitoring interface
+    GET  <root_monitor>/monitor.haljson        // monitor conf
+    GET  <root_monitor>/<service>/status.json  // service status json
+
+KVM Example
+
+    GET  <kvm_monitor>/monitor.haljson
+    GET  <kvm_monitor>/kvm-log-parser/status.json
+    GET  <kvm_monitor>/kvm-log-parser/index.html
+    POST <kvm_monitor>/cgi-bin/kvm-log-parse.cgi  // post handler
+
+Tree for monitor runtime
+
+    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/public/index.html               // generated by slapos
+    srv/monitor/public/monitor.css              // static
+    srv/monitor/public/monitor.js               // static
+    srv/monitor/public/monitor.haljson          // generated by monitor.py
+    srv/monitor/public/*.log|*.json|*.csv       // generator by monitor.py
+    srv/monitor/private/-^
+
+KVM Example
+
+    etc/monitor.conf.d/kvm-log-parse.conf                             // generated by slapos
+    var/monitor/run/kvm-log-parse.py                                  // generated by slapos (a promise that should stdout a status.json)
+    srv/monitor/cgi-bin/kvm-log-parse.cgi                             // generated by slapos (only way to handle post request kvm-log-parse ui)
+    srv/monitor/public/kvm-log-parse/index.html                       // static (renderjs component)
+    srv/monitor/public/kvm-log-parse/status.json                      // generated by kvm-log-parse.py
+    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-result.csv         // genareted by kvm-log-parse.py
+
+
+Service config example etc/monitor.conf.d/kvm-log-parse.conf
+------------------------------------------------------------
+
+    [service]
+    title =             Kvm log parse
+    name =              kvm-log-parse
+    frequency =         <Cron Syntax>
+    promise-path =      $instance/var/monitor/run/kvm-log-parse.py
+    interface-path =    $instance/srv/monitor/public/kvm-log-parse/index.html
+    public-path-list =  $instance/var/log/kvm.log  # automatically symlink to srv/monitor/public/$service/file/
+    private-path-list = $instance/var/log/kvm.log  # automatically symlink to srv/monitor/private/$service/file/
+
+the cgi path should be hardcoded to `${monitor:cgi-path}/${:name}.cgi so $instance/srv/monitor/cgi-bin/kvm-log-parse`, this should be the only way to handle post requests
+
+on cron, the command will be `${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
+
+and "monitor:promise-executor-path" is a script that would run a promise if not already on going (see `run-promise.py`)
+
+TODO put `run-promise.py` in the software
+
+
+Promise or script requirements
+------------------------------
+
+A promise should check something (like web cache, not too much slow queries, ...)
+
+- MUST output the status.json in stdout
+- SHOULD output on stdout
+- MUST return 0 if status is good else != 0
+- 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)
+-------------------------------------------------------------
+
+    {
+      "_links": {
+        "related_monitor": [
+          { "href": "<url>/static" },
+          { "href": "http://my.other.monitor" }
+        ]
+      },
+      "_embedded": {
+        "service": [
+          {
+            "_links": {
+              "status": { "href": "<url>/kvm-log-parse/status.json" },
+              "interface": { "href": "<url>/kvm-log-parse/index.html" }
+            },
+            "title": "KVM log parse",
+            "id": "kvm-log-parse"
+          },
+          {
+            "_links": {
+              "status": { "href": "<url>/<service>/status.json" },
+              "interface": { "href": "<url>/<service>/index.html" }
+            },
+            "title": "Service name",
+            "id": "<service>"
+          }
+        ]
+      },
+      "title": "KVM Monitoring interface"
+    }
+
+
+etc/monitor.conf example
+------------------------
+
+    [monitor]
+    title =              KVM Monitoring interface
+    monitor-hal-json =   $instance/srv/monitor/web/monitor.haljson
+    public-folder =      $instance/srv/monitor/public
+    private-folder =     $instance/srv/monitor/private
+    web-folder =         $instance/srv/monitor/web
+    cgi-folder =         $instance/srv/monitor/cgi-bin
+    service-pid-folder = $instance/var/monitor/service-pid
+    public-path-list =
+      $instance/var/log
+    private-path-list =
+      $instance/srv/backup/log_rotate
+    monitor-url-list =
+      https://[...]/
+      https://[...]/