Documentation for stand-alone mode & plugin diagnostics

docs/PLUGIN_DIAGNOSTICS.md

@@ -0,0 +1,114 @@
+# Plugin Diagnostics
+
+Plugin diagnostics provides a simple way to verify that a plugin is capable of running without requiring the plugin to be loaded and a task started.
+
+It is possible to run plugin diagnostics without any arguments, e.g.:
+
+```
+$ ./snap-plugin-collector-psutil
+```
+
+or with plugin configuration in the form of a JSON:
+
+```
+$ ./snap-plugin-collector-psutil --config {\"mouting_points\":\"/dev/sda\"}
+```
+
+Plugin diagnostics delivers following information:
+- Runtime details, e.g.:
+    ```
+    Runtime Details:
+        PluginName: psutil, Version: 14
+        RPC Type: gRPC, RPC Version: 1
+        Operating system: linux
+        Architecture: amd64
+        Go version: go1.7
+    ```
+
+- Configuration details, e.g.:
+
+    ```
+    Config Policy:
+    NAMESPACE 		 KEY 		 TYPE 		 REQUIRED 	 DEFAULT 	 MINIMUM 	 MAXIMUM
+    intel.psutil.disk 	 mount_points 	 string 	 false 		
+    ```
+
+- Metrics exposed by plugin, e.g.:
+    ```
+    Metric catalog will be updated to include: 
+        Namespace: /intel/psutil/load/load1 
+        Namespace: /intel/psutil/load/load5 
+        Namespace: /intel/psutil/load/load15 
+        Namespace: /intel/psutil/cpu/*/softirq 
+        Namespace: /intel/psutil/cpu/cpu-total/softirq 
+        Namespace: /intel/psutil/cpu/*/steal 
+        Namespace: /intel/psutil/cpu/cpu-total/steal 
+        Namespace: /intel/psutil/cpu/*/guest_nice 
+        Namespace: /intel/psutil/cpu/cpu-total/guest_nice 
+        Namespace: /intel/psutil/cpu/*/user 
+        Namespace: /intel/psutil/cpu/cpu-total/user 
+        [...]
+    ```
+
+- Metrics that can be collected in the running environment in which plugin diagnostics is running, e.g.:
+ 
+    ```
+    Metrics that can be collected right now are: 
+        Namespace: /intel/psutil/load/load1        Type: float64     Value: 1.48 
+        Namespace: /intel/psutil/load/load5        Type: float64     Value: 1.68 
+        Namespace: /intel/psutil/load/load15       Type: float64     Value: 1.65 
+        Namespace: /intel/psutil/cpu/cpu0/softirq  Type: float64     Value: 20.36 
+        Namespace: /intel/psutil/cpu/cpu1/softirq  Type: float64     Value: 13.62 
+        Namespace: /intel/psutil/cpu/cpu2/softirq  Type: float64     Value: 9.96 
+        Namespace: /intel/psutil/cpu/cpu3/softirq  Type: float64     Value: 3.6 
+        Namespace: /intel/psutil/cpu/cpu4/softirq  Type: float64     Value: 1.42 
+        Namespace: /intel/psutil/cpu/cpu5/softirq  Type: float64     Value: 0.69 
+        Namespace: /intel/psutil/cpu/cpu6/softirq  Type: float64     Value: 0.54 
+        Namespace: /intel/psutil/cpu/cpu7/softirq  Type: float64     Value: 0.31 
+        Namespace: /intel/psutil/cpu/cpu-total/softirq  Type: float64     Value: 50.52 
+        Namespace: /intel/psutil/cpu/cpu0/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu1/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu2/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu3/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu4/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu5/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu6/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu7/steal    Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu-total/steal  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu0/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu1/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu2/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu3/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu4/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu5/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu6/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu7/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu-total/guest_nice  Type: float64     Value: 0 
+        Namespace: /intel/psutil/cpu/cpu0/user     Type: float64     Value: 2650.97 
+        Namespace: /intel/psutil/cpu/cpu1/user     Type: float64     Value: 2631.81 
+        Namespace: /intel/psutil/cpu/cpu2/user     Type: float64     Value: 2523.45 
+        Namespace: /intel/psutil/cpu/cpu3/user     Type: float64     Value: 2500.99 
+        Namespace: /intel/psutil/cpu/cpu4/user     Type: float64     Value: 2039.26 
+        Namespace: /intel/psutil/cpu/cpu5/user     Type: float64     Value: 2082.44 
+        Namespace: /intel/psutil/cpu/cpu6/user     Type: float64     Value: 2054.43 
+        Namespace: /intel/psutil/cpu/cpu7/user     Type: float64     Value: 1901.43 
+        Namespace: /intel/psutil/cpu/cpu-total/user  Type: float64     Value: 18384.81
+       [...]
+    ```
+
+- Times required to make operations, e.g.:
+    ```
+    [...]
+    printRuntimeDetails took 11.878µs
+    [...]
+    printConfigPolicy took 67.654µs 
+    [...]
+    printMetricTypes took 504.483µs 
+    [...]
+    printCollectMetrics took 7.470091ms 
+    [...]
+    showDiagnostics took 8.076025ms
+    ```
+## Note
+
+For now plugin diagnostics works only for collector plugins.

docs/STANDALONE_MODE.md

@@ -0,0 +1,30 @@
+# Standalone mode
+
+Standalone mode enables plugin launching on different machine than Snap daemon (`snapteld`).
+
+To run plugin in standalone mode it is needed to launch plugin with `--stand-alone` flag, e.g.:
+```
+$ ./snap-plugin-collector-psutil --stand-alone
+```
+Plugin in standalone mode creates HTTP server for communication with Snap framework, by default plugin listens on `8182` port.
+
+It is possible to configure different port for communication with Snap framework using `--stand-alone-port` flag, e.g.:
+
+```
+$ ./snap-plugin-collector-psutil --stand-alone --stand-alone-port 8183
+```
+
+To load plugin in standalone mode it is required to provide URL to indicate a machine
+on which plugin is running (IP address/hostname with port number), e.g.:
+
+```
+$  snaptel plugin load http://127.0.0.1:8182
+```
+
+or
+
+```
+$  snaptel plugin load http://localhost:8182
+```
+
+The rest of operations remains exactly the same as is it for regular plugins.