From 1a3a7cd7ef42013131226511dc7526153510c518 Mon Sep 17 00:00:00 2001 From: katarzyna-z Date: Tue, 22 Aug 2017 10:53:05 +0200 Subject: [PATCH 1/3] Documentation for stand-alone mode & plugin diagnostics --- docs/PLUGIN_DIAGNOSTICS.md | 67 ++++++++++++++++++++++++++++++++++++++ docs/STAND-ALONE_MODE.md | 39 ++++++++++++++++++++++ 2 files changed, 106 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..fbaaf4493 --- /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 {\"mouting_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..25bc30163 --- /dev/null +++ b/docs/STAND-ALONE_MODE.md @@ -0,0 +1,39 @@ +# 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 +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 there is any disruption in the connection between Snap and a stand-alone plugin then the task is disabled and the plugin is unloaded, +see [github issue](https://github.com/intelsdi-x/snap/issues/1697). \ No newline at end of file From fa99bb75a3dc974417002c17f258b776a9f09283 Mon Sep 17 00:00:00 2001 From: Izabella Raulin Date: Tue, 29 Aug 2017 11:44:42 +0200 Subject: [PATCH 2/3] Update PLUGIN_DIAGNOSTICS.md --- docs/PLUGIN_DIAGNOSTICS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/PLUGIN_DIAGNOSTICS.md b/docs/PLUGIN_DIAGNOSTICS.md index fbaaf4493..1b1dc6ebc 100644 --- a/docs/PLUGIN_DIAGNOSTICS.md +++ b/docs/PLUGIN_DIAGNOSTICS.md @@ -17,7 +17,7 @@ $ ./snap-plugin-collector-psutil ``` or with plugin configuration in the form of a JSON: ``` -$ ./snap-plugin-collector-psutil --config {\"mouting_points\":\"/dev/sda\"} +$ ./snap-plugin-collector-psutil --config '{"mount_points":"/dev/sda"}' ``` Example output: From 3504ca76d008d27b2b7b5fa44fe8c3281fa4dbbc Mon Sep 17 00:00:00 2001 From: Izabella Raulin Date: Tue, 29 Aug 2017 11:47:28 +0200 Subject: [PATCH 3/3] Update STAND-ALONE_MODE.md --- docs/STAND-ALONE_MODE.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/STAND-ALONE_MODE.md b/docs/STAND-ALONE_MODE.md index 25bc30163..d7afd928a 100644 --- a/docs/STAND-ALONE_MODE.md +++ b/docs/STAND-ALONE_MODE.md @@ -18,8 +18,7 @@ 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.: +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 @@ -33,7 +32,5 @@ $ 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 there is any disruption in the connection between Snap and a stand-alone plugin then the task is disabled and the plugin is unloaded, -see [github issue](https://github.com/intelsdi-x/snap/issues/1697). \ No newline at end of file +## 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).