Skip to content
This repository has been archived by the owner on Nov 8, 2022. It is now read-only.

Documentation for stand-alone mode & plugin diagnostics #1719

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions docs/PLUGIN_DIAGNOSTICS.md
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@katarzyna-z, could we simplify this sentence to be more clear - I will think about some proposal of that. Also, plugin-diagnostics is only collector plugin feature - that should be mentioned somewhere.

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
```
36 changes: 36 additions & 0 deletions docs/STAND-ALONE_MODE.md
Original file line number Diff line number Diff line change
@@ -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).