Configuration

Monitask configuration

All the configuration is done with two mechanisms:

• describing how to obtain, store and export system metrics via configuration files and
• programming the collection and export tasks via corresponding system tools (/etc/crontab file).

Shortcut version

After installation consider modifying the following settings in your monitask.ini file:

[datastore]
...
start_time = "2015-11-18" ; <-- set to current date
...

[export]
...
export_dir = "/home/www/monitask" ; <-- set to your web folder

Then configure crontab to automate metrics collection and export (include PATH environment since it may be restricted when crontab is run):

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
*/5 * * * * root /PF/run-monitask.php --collect && /PF/run-monitask.php --export

Configuring with INI files

Config files are used for the following purposes:

• define which plugin to use for datastore (default is csv),
• define which plugin to use for data export (default is gcharts),
• define periods for data collection (default is 4 periods)
• include other config files,
• define commands that will return system metrics,
• define blocks of graphs and
• describe characteristics of each graph, including displayed metrics.

Each config file consists of global settings and sections with local settings. Each setting is of form name = value, where name may contain [] notation to indicate arrays and value may contain references to environment variables and a special DIR constant, containing the program folder. value may be split on multiple lines if it is wrapped with double quote (") characters.

Sections are started with [section name] line. Settings on lines following [section name] line only apply to section name section.

Global settings precede the first section of each config file. After the first section declaration there is no way to declare any global setting.

For example, consider the following .INI file:

include[] = DIR"/ini/system.ini"
include[] = DIR"/ini/network.ini"
include[] = DIR"/ini/disk.ini"
include[] = DIR"/ini/mail.ini"
include[] = DIR"/ini/mysql.ini"

[datastore]
type = csv
filename = "/var/db/monitask.csv"
period['by day'] = "-2 days"
period['by week'] = "-9 days"
period['by month'] = "-45 days"
period['by year'] = "-450 days"
start_time = "2015-11-18"
bins = 100

[export]
type = gcharts
export_dir = "/home/www/monitask"
ajax_method = "POST"

This config file declares a global include array, a datastore section with type, filename, period, start_time and bins settings and an export section with type, export_dir and ajax_method settings.

JSON representation of include global setting:

[
  "/home/username/monitask/ini/system.ini",
  "/home/username/monitask/ini/network.ini",
  "/home/username/monitask/ini/disk.ini",
  "/home/username/monitask/ini/mail.ini",
  "/home/username/monitask/ini/mysql.ini"
]

As you may see, DIR const was replaced automatically by Monitask program folder, which in this example was /home/username/monitask.

JSON representation of period setting from datastore section:

{
  "by day":"-2 days",
  "by week":"-9 days",
  "by month":"-45 days",
  "by year":"-450 days"
}

And here is another example, one of the included files, mail.ini:

block = "Mail"

[commands]
mail.stats = "mailstats -P\
 | awk '/T/ {\
    print \"M_snt\", $2;\
    print \"M_rcv\", $4;\
    print \"M_rj\", $6;\
    print \"M_dsc\", $7;\
  }'"

[mail_stats]
class = "AreaChart"
title = "Sendmail traffic"
options[vAxis.title] = "messages"
M_rcv[title] = "received"
M_rcv[type] = increment
M_snt[title] = "sent"
M_snt[type] = increment
M_snt[eval] = "-M_snt"
M_rj[title] = "rejected"
M_rj[type] = increment
M_dsc[title] = "discarded"
M_dsc[type] = increment

Here are defined:

• block global setting,
• commands section with mail.stats entry,
• mail_stats section with class, title, options, M_rcv, M_snt, M_rj and M_dsc entries.

The rules for processing the directives in config file are the as follows:

• if main config file is not specified on command line, the default ini/monitask.ini file is processed;
• datastore and export sections are read from the main config file (one from the command line or default monitask.ini file). They may not appear in included files;
• include and block global setting, commands and other sections may appear in any config file;
• include list is processed after all other settings are registered;
• instructions from any included file may overwrite previously defined settings;

See Settings reference for detailed description of each setting.

See also:

• http://wikipedia.org/wiki/INI_file
• http://php.net/parse-ini-file

Programming crontab tasks

Before configuring the /etc/crontab file you must assure that the commands run smoothly without errors. Please run the following from your shell:

$ sudo /PF/run-monitask.php --collect
$ sudo /PF/run-monitask.php --export

Replace the two appearances of /PF/ by Monitask program folder.

For the collection process to start every 5 minutes and be followed by metrics export, create the following /etc/cron.d/monitask file:

# Monitask metrics collection and export every 5 minutes

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

*/5 * * * * root /PF/run-monitask.php --collect && /PF/run-monitask.php --export

Replace the two appearances of /PF/ by Monitask program folder. This way the collection and export processes will be launched on 5-minute interval under root user account. All errors during execution of cron scripts are sent to the corresponding mail account.

The export process will regenerate all the JSON files requested by template file with the new data.