Monitis Custom Bash SDK

Monitis Custom Bash SDK is a set of scripts allowing to create custom monitors and add results. It has the following structure.

Monitis Open API wrapper  

    monitis_api.sh          monitis API wrapper functions  
    monitis_constant.sh     monitis api wrapper constants (and configuration)  
    monitis_global.sh       monitis api wrapper global variables  
    monitis_util.sh         monitis api wrapper utility functions  

Additional part  

    ticktick.sh           JSON processing library
    monitor_getdata.sh    Retrieve data from Monitis

Processing part  

    monitor_start.sh      Main executable script
    monitor_controller.sh start/stop/restart monitor as a deamon processes (for production use)

Test part  

    monitor_constant.sh    monitor specific constants
    monitor.sh             custom monitor implementation
				 	

Usage

To use existing scripts you need to do some additions and changes that will correspond your account and data

  • in monitis_constant.sh

    • replace ApiKey and SecretKey by your keys values (can be obtained from your Monitis account)
  • in monitor_constant.sh

    • replace MONITOR_NAME, MONITOR_TAG and MONITOR_TYPE by your desired names
    • replace RESULT_PARAMS and ADDITIONAL_PARAMS strings by data formats definition of your monitor
    • you can also add some additional parameters that have to use your script
    • you may do also definition of DURATION between measurements and sending results (currently it is declared as 5 min)
  • replace monitor.sh by your measuring script. Please take into account the following

    • script should contain function named get_measure()
    • the get_measure() will be called periodically. It should fill return_value parameter which consists of two parts:

      • fixed part that should correspond to definition for RESULT_PARAMS in the monitor_constants.sh
      • dynamic part that should correspond to definition for ADDITIONAL_PARAMS in the monitor_constants.sh
    • both parts should be joined by | symbol (e.g. return_value="$param | $details" )
    • besides, this script should returning standard return code. As usually, 0 mean successful processing.

That's all. Now you can run monitor_start.sh and monitoring process will be started.

Please note that you can run monitor_start.sh script with command line parameters which allow to tune monitor without doing changes in the monitor_constant.sh script.

    monitor_start.sh -d <duration in min>
					

Usage monitor as a daemon process

Quite often it is necessary to run the monitor as a daemon process to avoid its stopping when your session is closed.

To do so the monitor_controller.sh script is added into the scripts bunch.
Use the following pattern to use it

    monitor_controller.sh [command]
					

where allowed commands: start (default); stop; restart.

You can also getting monitoring data from monitis

To do so you should use monitor_getdata.sh script by following pattern

    monitor_getdata.sh -d <number of days to get data for> -p <folder path to storing data-files> -f <file name prefix> -m <monitor id> 

    where
        -d parameter specifies how many days data do you want to get (default value is 1 day)
           NOTE: each day's data will be stored in the separate files
        -p parameter specifies the directory which will keep the data-files to (by default it is current directory)
        -f parameter specifies the prefix for file name which will contain data (by default it is monitor name defined in monitor_constats.sh)
        -m monitor registration ID 
					

Notice that all parameters are optional.
The monitor registration ID should be specified in extreme situation only, e.g. if you have several monitors with same name or some monitor was deleted by accidentally but its data is very important.

Testing

To check the correctness of Bash API workability, the simple test is provided.
It consist of two scripts:

    monitor_constant.sh    monitor specific constants
    monitor.sh             simplest custom monitor implementation
					

The test monitor is very simple - it generates random integers in range (0 - RANGE).
The status of data will be OK in case of generated integer less than THRESHOLD. Otherwise, it will generate NOK status.

Naturally, you can view the graph representation of measured data

Double-clicking on any line lead to alternate view which shows additional data about FTP server state at problematic time.

You can also look through some monitors implemented via bash SDK.
FTP-monitor, Log-Files-Monitor, Process-monitor, etc.