Add custom probes

Any executable script or file can be added as a monitoring probe with the web interface to set up and pass args.

Each custom probe consists of two files:

  • the executable file (script or binary file),

  • the configuration file which describes the Monitoring section for this probe to pass corresponding arguments.

The configuration file must:

  • be placed to the folder with the executable file;

  • have the name of the executable file with the additional extension .conf:

/opt/saymon-agent/custom_tasks/mytask.sh
/opt/saymon-agent/custom_tasks/mytask.sh.conf

Executable files of custom probes can be grouped in subfolders with any number of sublevels:

/opt/saymon-agent/custom_tasks/cisco/task_1.sh
/opt/saymon-agent/custom_tasks/cisco/task_1.sh.conf
/opt/saymon-agent/custom_tasks/cisco/task_2.sh
/opt/saymon-agent/custom_tasks/cisco/task_2.sh.conf
/opt/saymon-agent/custom_tasks/hp/task_3.sh
/opt/saymon-agent/custom_tasks/hp/task_3.sh.conf
/opt/saymon-agent/custom_tasks/hp/task_4.sh
/opt/saymon-agent/custom_tasks/hp/task_4.sh.conf

The probes are grouped and displayed in the web interface taking into account the subfolders:

cisco - task_1
cisco - task_2
hp - task_3
hp - task_4

When adding or modifying custom probes the changes are applied with refreshing the page in a web browser.

Probe identifiers, which are used by the server and the agents, are created automatically. The identifiers are equal to the names of the executable files with the part of the path from the configured folder, e.g. cisco/task_1.

The identifier of a custom probe must not match the identifier of a standard probe. Otherwise, the custom probe will be ignored.

See the list of the standard probes identifiers - Hide unused probes.

Probe identifiers are case-sensitive.

Custom probes are executed by the agents locally, so it is required to copy the executable files to the same folder on each host, which is supposed to execute the probes on.

For configuration files, it is sufficient to put them on the hosts with the server of the system.

Folder for custom probes

Custom probes folder is set in the server configuration file /etc/saymon/saymon-server.conf.

It is necessary to:

  1. Add the monitoring section into the file.

  2. Set the full path to the folder where the custom tasks are stored in the parameter custom_tasks_path:

    ...
"monitoring": {
    "custom_tasks_path": "/opt/tasks"
},
...

  3. Restart the server:

    $ sudo service saymon-server restart

Parameters of the custom probe

Custom probe parameters are set in the JSON file named as executable_file_name.conf. For instance, if the executable file is named as mySensor.sh, then the configuration file must be named as mySensor.sh.conf.

The configuration file must be placed into the same folder as the executable file.

Probes without the configuration files are ignored.

The configuration file can contain the following fields:

Field Description

title

Probe name which is displayed in the web interface in a list of probes.

Optional field.

By default - the probe identifier, generated from the path and the name of the probe:

  • path to the file: <path_to_the_folder_with_probes>/cisco/task_1.sh

  • displayed probe name: cisco - task_1

icon

Icon from the Font Awesome kit, which is displayed with the name of the probe.

Optional field.

By default - image ('fa fa-cubes fa-fw')

excludeForClasses

List of object class IDs which the probe is not available for.

Optional field.

By default, the probe is available for all object classes.

args

The array of the arguments, which are set by users in the web interface and passed to the executable file.

args.id

Argument name, which is passed to the executable file.

Optional field.

args.default

The default value of the argument, which is entered into the corresponding field during the probe creation.

Optional field.

args.description

Description of the argument, which is displayed in the web interface.

Optional field.

args.name

Argument name, which is displayed in the web interface.

args.options

Applicable only for the select type ([args.type.select]).

Defines the list of argument values, which are displayed in the web interface.

By default, the first option is selected. In order to set another option as the default one, it is necessary to enter the value of the args.options.value field to the args.default field.

The following is passed to the executable file:

If the args.id field is not set, then only the argument value ([args.options.value]) is passed to the executable file.

If the args.options.value field is not set, then the argument name ([args.id]) is not passed to the executable file.

This logic can be used to implement the "Not selected" option and delimiters in the dropdown list.

args.options.description

Description of the argument value, which is displayed in the web interface.

Optional field.

By default the argument value ([args.options.value]) is displayed.

args.options.value

Argument value.

Optional field.

If this field is not set, then the argument name is not passed to the executable file. These options can be used in order to implement the "Not selected" option and delimiters in the dropdown list.

args.required

Indicates if the argument value is required.

  • true | the value is required,

  • false | the value is optional.

Optional field.

By default false.

args.type

Type of the argument value.

Optional field.

By default | text.

args.type.checkbox

Switcher.

By default it is disabled.

When it is enabled the value of the [args.id] field (argument name) is passed to the executable file. If the field is not set, then the index number of the argument is passed to the executable file (starting from 0).

args.type.password

The text field with masking of input characters.

args.type.select

Dropdown list with predefined argument values.

The list of values is set in the [args.options] field.

Argument description (the [args.description] field) is not displayed for this type. It is necessary to use the corresponding field for each argument value instead ([args.options.description]).

args.type.text

Text field to enter argument value.

args.type.textarea

Text field to enter argument value.

Allows to enter multiline text.

Custom probe example

To demonstrate the custom probe script and different argument types we have prepared two files.

Place the files to the custom probes folder, create a new object with this probe in the web interface and try to change argument values.

This custom probe displays all passed arguments:

hello_world.sh
#!/bin/bash
#
# Use this script as the custom monitoring sensor
# to check or test arguments configuration file.

i=0
echo "Custom probe got the following args:"
for arg in $*
do
  i=$((i + 1))
  echo -ne $arg; echo -ne " "
done

if [ $i = 0 ]
then
  echo "(no args)"
  exit 2
fi

This configuration file contains examples for all argument types:

hello_world.sh.conf
{
    "title": "Custom probe example",
    "icon": "fa fa-folder fa-fw",
    "excludeForClasses": [1,2],
    "args": [
        {
            "name": "Unnamed (positional) arg"
        },
        {
            "name": "Named arg",
            "id": "--name"
        },
        {
            "name": "Behold the description on the right",
            "description": "Here I am!",
            "id": "--description"
        },
        {
            "name": "Arg with defaul value",
            "description": "and description",
            "id": "--defval",
            "default": "default_value"
        },
        {
            "name": "Required arg",
            "description": "This field is required to fill in",
            "id": "--required",
            "required": true
        },
        {
            "name": "Type - Text",
            "description": "This and all above fields have got text type",
            "id": "--text",
            "type": "text"
        },
        {
            "name": "Type - Text Area",
            "description": "This field is text area. \nIt is resizable in most browsers. \nAnd allows to enter multiline texts.",
            "id": "--textarea",
            "type": "textarea"
        },
        {
            "name": "Type - Checkbox",
            "description": "This is the checkbox type",
            "id": "--checkbox",
            "type": "checkbox"
        },
        {
            "name": "Type - Password",
            "description": "This is the password field",
            "id": "--pass",
            "default": "qwerty",
            "type": "password"
        },
        {
            "name": "Type - Select",
            "description": "This is the select type. This description is not displayed in the web interface. Use description for each option instead.",
            "id": "--select",
            "default": "option2",
            "type": "select",
            "options": [
                {
                    "description": "== Not selected =="
                },
                {
                    "value": "option1", "description": "OK"
                },
                {
                    "description": "== Divider =="
                },
                {
                    "value": "option2", "description": "Warning"
                },
                {
                    "value": "option3", "description": "Error"
                }
            ]
        }
    ]
}

Using operating system utilities

If some utilities, which can be used for data collection and monitoring, have been installed in the operation system, it is possible to reuse those creating a reference to the executable file in the custom probes folder and adding the configuration file.

Here is the example of adding the cURL command-line tool.

  1. Go to the custom probes folder:

    $ cd /opt/saymon-custom-monitoring

  2. Get the path to the cURL binary:

    $ which curl

> /usr/bin/curl

  3. Create the reference with the cURL name and /usr/bin/curl path:

    $ ln -s /usr/bin/curl cURL

  4. Create the configuration file for the probe:

    nano cURL.conf
    {
    "title": "cURL reuse",
     "args": [
        {
            "name": "URL to cURL",
            "description": "e.g. https://google.com",
            "required": true
        }
     ]
}

After refreshing the browser page you will see cURL reuse probe in the list. This probe has only one required argument.