From 84ef5a94f77758fa4c28ce02880ebc022d7bb12d Mon Sep 17 00:00:00 2001
From: Katarzyna Kujawa <katarzyna.kujawa@intel.com>
Date: Tue, 29 Aug 2017 14:07:54 +0200
Subject: [PATCH] Documentation for stand-alone mode & plugin diagnostics
 (#1719)

* Documentation for stand-alone mode & plugin diagnostics
---
 docs/PLUGIN_DIAGNOSTICS.md | 67 ++++++++++++++++++++++++++++++++++++++
 docs/STAND-ALONE_MODE.md   | 36 ++++++++++++++++++++
 2 files changed, 103 insertions(+)
 create mode 100644 docs/PLUGIN_DIAGNOSTICS.md
 create mode 100644 docs/STAND-ALONE_MODE.md

diff --git a/docs/PLUGIN_DIAGNOSTICS.md b/docs/PLUGIN_DIAGNOSTICS.md
new file mode 100644
index 000000000..1b1dc6ebc
--- /dev/null
+++ b/docs/PLUGIN_DIAGNOSTICS.md
@@ -0,0 +1,67 @@
+# 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 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 exposed 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 '{"mount_points":"/dev/sda"}'
+```
+
+Example output:
+
+```
+$ ./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 
+    [...]
+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
+    [...]
+printCollectMetrics took 7.470091ms 
+
+showDiagnostics took 8.076025ms
+```
diff --git a/docs/STAND-ALONE_MODE.md b/docs/STAND-ALONE_MODE.md
new file mode 100644
index 000000000..d7afd928a
--- /dev/null
+++ b/docs/STAND-ALONE_MODE.md
@@ -0,0 +1,36 @@
+# 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)).
+
+## Running a plugin in stand-alone mode
+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
+To load a plugin in stand-alone mode, provide a URL to indicate to the machine on which 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.
+
+## Known issues
+If some disruption occurs in the connection between Snap and a stand-alone plugin, the running task will be stopped with disabled status and the plugin will be unloaded. Providing the mechanism of reconnecting stand-alone plugins upon network disruption is in our scope, addressed by the [issue #1697](https://github.com/intelsdi-x/snap/issues/1697).