Documentation for stand-alone mode & plugin diagnostics

intelsdi-x · Aug 28, 2017 · 4fe6e17 · 4fe6e17
1 parent 9377eae
commit 4fe6e17
Show file tree

Hide file tree

Showing 2 changed files with 138 additions and 0 deletions.
diff --git a/docs/PLUGIN_DIAGNOSTICS.md b/docs/PLUGIN_DIAGNOSTICS.md
@@ -0,0 +1,98 @@
+# 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.
+This feature works for collector and streaming collectors plugins written using one of our snap-plugin-libs ([snap-plugin-lib-go](https://github.com/intelsdi-x/snap-plugin-lib-go), [snap-plugin-lib-py](https://github.com/intelsdi-x/snap-plugin-lib-py), [snap-plugin-lib-cpp](https://github.com/intelsdi-x/snap-plugin-lib-cpp)).
+
+Plugin diagnostics delivers following information:
+- runtime details (plugin name, version, etc.)
+- configuration details
+- list of metrics expose by the plugin
+- metrics with their values that can be collected right now
+- and times required to retrieve this information
+
+## Running plugin diagnostics
+It is possible to run plugin diagnostics without any arguments (default values are used), 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\"}
+```
+
+For example:
+
+```
+$ ./snap-plugin-collector-psutil
+
+Runtime Details:
+    PluginName: psutil, Version: 14
+    RPC Type: gRPC, RPC Version: 1
+    Operating system: linux
+    Architecture: amd64
+    Go version: go1.7
+printRuntimeDetails took 11.878µs
+
+Config Policy:
+NAMESPACE 		 KEY 		 TYPE 		 REQUIRED 	 DEFAULT 	 MINIMUM 	 MAXIMUM
+intel.psutil.disk 	 mount_points 	 string 	 false 		
+printConfigPolicy took 67.654µs
+
+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 
+printMetricTypes took 504.483µs 
+
+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
+printCollectMetrics took 7.470091ms 
+
+showDiagnostics took 8.076025ms
+```
diff --git a/docs/STANDALONE_MODE.md b/docs/STANDALONE_MODE.md
@@ -0,0 +1,40 @@
+# Stand-alone mode
+
+Stand-alone mode enables plugin launching on different machine than Snap daemon (`snapteld`).
+This feature works for plugins written using one of our snap-plugin-libs ([snap-plugin-lib-go](https://github.com/intelsdi-x/snap-plugin-lib-go),
+[snap-plugin-lib-py](https://github.com/intelsdi-x/snap-plugin-lib-py), [snap-plugin-lib-cpp](https://github.com/intelsdi-x/snap-plugin-lib-cpp)).
+
+To run a plugin in stand-alone mode, you must start it with the `--stand-alone` flag, e.g.:
+```
+$ ./snap-plugin-collector-psutil --stand-alone
+```
+
+A plugin running in stand-alone mode creates a HTTP server for communication with the Snap framework.
+By default the plugin listens on port `8182`.
+
+To specify a different listening port, use the `--stand-alone-port` flag, e.g.:
+```
+$ ./snap-plugin-collector-psutil --stand-alone --stand-alone-port 8183
+```
+##  Loading a plugin
+When loading a plugin in stand-alone mode into `snapteld` you must provide a URL to indicate which
+machine the 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 plugins running in regular mode.
+
+## Notice
+
+If the connection between `snapteld` and the plugin running in stand-alone mode is disrupted
+it will try to reconnect. If it is unable to reconnect the plugin will be unloaded,
+metric catalog updated, and any dependent tasks will stop,
+see also [github issue](https://github.com/intelsdi-x/snap/issues/1697).