THIS IS UNOFFICIAL PLUGIN. DO NOT INSTALL UNLESS APPROVED BY BOUNDARY SUPPORT. Shell plugin is generic plugin that allows the use of any program or scripting language to produce metrics for the Boundary product.
OS | Linux | Windows | SmartOS | OS X |
---|---|---|---|---|
Supported | v | - | v | v |
Runtime | node.js | Python | Java |
---|---|---|---|
Required | - |
-
Once the Shell Plugin is installed, any metric to be collected requires additional configuration.
How to add new metrics?
- Define the metric
- Write the script that collects the metric (see Shell Plugin Protocol)
- Configure the metric in the Shell plugin.
See this article on how to define custom metrics.
This step is going to be short cut by providing an already created script the counts the number of files in a directory. The example script is called nfiles
- Login into Boundary Premium
- Display the settings dialog by clicking on the settings icon and selecting meters to display the list of installed meters.
- Click on a meter in the list which then shows a list of the plugins installed on the meter.
- Click on the Add a plugin drop down menu and select shell.
- Click on the Add a Metric Command fill out the form as shown here and the click on OK:
- Click on the Save button to save the configuration.
- The meter console is then displayed showing the plugin loading. Click on the Close button to dismiss the dialog.
See Building a Dashboard - How To to create a dashboard to display the metric configured above.
To aide in the development of your custom metric script you can enable debug, by checking the Debug checkbox in the Metric Command definition form. This enables logging of the the command executed and the output that is produced by the command.
Collection of your own defined metric requires a program or script to:
- Collect, by any means the desired metric
- Write the collected metric value, along with the metric name, and source to standard output with an accompanying new line.
Here is a Bash shell code snipet that illustrates:
#### Collect the metric
# List the directory, count the lines, and remove white space
file_count=$(ls -1 $directory_path | wc -l | tr -d ' ')
#### Write the metric standard out
echo "FILE_COUNT $file_count $(hostname)"
Here is yet another snipet that collects and outputs the processor load in a single line of code:
echo $(uptime) $(hostname) | awk '{printf("LOAD_1_MINUTE %s %s\nLOAD_5_MINUTE %s %s\nLOAD_15_MINUTE %s %s\n",$8,$11,$9,$11,$10,$11)}'
Boundary Shell Plugin bundles several examples that illustrate how to create your metrics using a program or script:
- CPU Load
- File Space Capacity
- Process Count
- Port Scan
- Random
Collects the CPU load for the last 1,5,and 15 minute intervals.
Uses the following metrics:
BOUNDARY_CPU_LOAD_1_MINUTE
BOUNDARY_CPU_LOAD_5_MINUTE
BOUNDARY_CPU_LOAD_15_MINUTE
Requires the following on the Relay host:
- Bash shell
- Posix utilities:
awk
,hostname
,uptime
Example Command:
$ scripts/cpu-load.sh
Example Plugin Shell configuration:
- Name -
CPU Load
- Poll Time (sec) -
5
- Debug -
false
(unchecked) - Command -
scripts\cpu-load.sh
Collects spaced used of a file system as a percentage of total space.
useage: fsuseage.sh <mount point>
Uses the following metrics:
BOUNDARY_FILE_SPACE_CAPACITY
Requires the following on the Relay host:
- Bash shell
- Posix utilities:
awk
,tail
- python 2.6.6 or later
Example Command:
$ scripts/fsuseage.sh /
Example Plugin Shell configuration:
- Name -
Root File Space
- Poll Time (sec) -
5
- Debug -
false
(unchecked) - Command -
scripts\fsusage.sh /
Measures the number of processes running on a host.
Uses the following metrics:
BOUNDARY_PROCESS_COUNT
Requires the following on the Relay host:
- Bash shell
- Posix utilties:
egrep
,grep
,hostname
,ps
,tr
,wc
Example Command:
$ scripts/nprocs.sh
Example Plugin Shell configuration:
- Name -
Process Count
- Poll Time (sec) -
5
- Debug -
false
(unchecked) - Command -
scripts\nprocs.sh
Checks the availability of TCP/IP port on a specified host
Uses the following metrics:
BOUNDARY_PORT_AVAILABILITY
BOUNDARY_PORT_RESPONSE
Requires the following on the Relay host:
- Python 2.6.6 or later
Example Command:
$ scripts/portscan.py www.google.com 80
Example Plugin Shell configuration:
- Name -
Google Port 80
- Poll Time (sec) -
5
- Debug -
false
(unchecked) - Command -
scripts/portscan.py www.google.com 80
Example scripts that outputs a random number between the values input to the script:
usage: random.sh <min> <max>
where:
min is the smallest value to generate
max is the largest value to generate
Uses the following metrics:
BOUNDARY_RANDOM_NUMBER
Requires the following on the Relay host:
- Bash shell
Example Command:
$ scripts/random.sh 0 99
Example Plugin Shell configuration:
- Name -
Random
- Poll Time (sec) -
5
- Debug -
false
(unchecked) - Command -
scripts/random 0 99