Configuration

Table of Contents

How to check an app?

To read about the PHP client have a look to the introdction https://os-docs.iml.unibe.ch/appmonitor/Client/Introduction.html

The binary is compiled PHP code containing the classes to perform checks.

To use the checks inside that binary the must be defined in an ini file.

It contains:

  • meta information for the app
  • all checks

The output is a JSON. The structure is described on 📗 https://os-docs.iml.unibe.ch/appmonitor/Client/Description_of_response.html.

Introduction

The infomation for the checks is structured in sections.

  • [meta] - defines the meta information for the web application, its hostname and more. This section is optional but I am naerly sure you want to override the defaults
  • [notifications] - define application specific receivers that get a message from appmonitor server on status change of this app.
  • [<OTHER>] - all other section except meta and ntifications are checks. Define one check per section.

First an example:

[meta]
host = "www.example.com"
website = "Company website"
ttl = 300
tags[]="monitoring"

[notifications]
email[]="support@example.com"
email[]="webmaster@example.com"

slack["#support-channel"]="https://hooks.slack.com/services/XXXXXX/YYYYYY/ZZZZZ"

; -----------------------------------------------------------------------
; CHECKS
; -----------------------------------------------------------------------

["hello plugin"]
description="I sust wanna say hello"
function="hello"
params[message]="Here is ${USER}"

Types of values

The binary uses the php function parse_ini_file - see 🌐 https://www.php.net/manual/en/function.parse-ini-file.php.

  • The section is in brackets eg. [<SECTION>]

  • In each section is a set of keys and values, separated by =

  • keys (variable):

    • a string with letters, digits, underscore
    • Use multiple <VARNAME>[] to create an an array with list items
    • <VARNAME>[<KEY>] is used for slack notifications and one of the possible options for [check] -> params

  • values

    • numbers of integer, float (no quoting)
    • strings in single quotes or double quotes
    • Specialty: In [check] -> params you can use JSON syntax: It is aquoted string using single quotes '. The JSON key and value must be quoted with double quotes.
    • Environment variables or PHP configuration values can be embedded using ${<VARMAME>}; it works with unquoted value or double quoted strings but not inside single quotes (or JSON).

The values for each check are check specific. Have a look to the origin docs for each check - see 📗 https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/index.html.

To have a minimal working example have a the folder tests/configs or here 🌐 https://git-repo.iml.unibe.ch/iml-open-source/appmonitor-cli-client/-/tree/main/tests/configs?. These ini files do NOT contain all supported keys.

Meta information

Section [meta]

key type description
host string hostname where the app is running. example: “www.example.com”; default: automatic detection
website🔸 string Name of the app, eg. “Company website”;
ttl int Ttl value in seconds. Tis cycle will be used by the appmonitor server to refresh the information
tags array array of tags (optional) You can send tags to describe kind of tool, department/ developer team, whatever. In the server webgui you will see a list of all tags of all monitors and can filter them

🔸 required

👉 Example:

[meta]
host = "www.example.com"
website = "Company website"
ttl = 300
tags[]="monitoring"

Section [notifications]

You can define application specific receivers on status changes. This section is optional.

Currently supported are

  • email addresses
  • Slack channels
key type description
email array array of email receivers
slack hash key-value list with a readable label for the target channel and the Slack webhook url

👉 Example:

[notifications]
email[]="support@example.com"
email[]="webmaster@example.com"

slack["#support-channel"]="https://hooks.slack.com/services/XXXXXX/YYYYYY/ZZZZZ"

Check sections

Transform PHP hash to ini

All other sections except “meta” and “notifications” are checks. Define one check per section.

All available checks are described here: 📗 https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/index.html.

Each section corresponds to a call of a single check.

Conventions to describe a check in an ini section instead of using $oMonitor->addCheck(<hash>) snippets:

  • “name” - is the section name
  • “description” - use key “description” (1:1)
  • section “check” - this keyword is missed in ini files. Its subkeys are are taken 1 as keys
    • check->function - use “function”
    • check->params - use “params” as a hash

Let’s have a look to an example: this is the PHP code for the Diskfree check https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/diskfree.html:

👉 Example:

$oMonitor->addCheck(
    [
        "name" => "Check free diskspace in /tmp",
        "description" => "The file storage have some space left",
        "check" => [
            "function" => "Diskfree",
            "params" => [
                "directory" => "[directory]",
                "warning"   => [size],
                "critical"  => [size],
            ],
        ],
    ]
);

The same described in ini format:

["Free disk space /tmp"]
description="The file storage have some space left"
function="Diskfree"
params[directory]="/tmp"
params[warning]="1GB"
params[critical]="500MB"

Dynamic values

OK, the ini file has keys and values. If have environment variables (maybe by an earliear loaded .env file) then you can use them by adding a dollar sign in front.

👉 Example:

If you have this variable in the environment before starting amcli:

API_URL="https://www.example.com/api/v1/"

it can be expanded if your ini contains $API_URL:

["Http content"]
description="Check if API is online"
function="HttpContent"
params[url]: "$API_URL"

JSON

The params are written as a hash. It works as long the value is string/ integer/ bool value.

It does not work on an array or hash. But there is a specialty (that is not part of the ini format): if the given value is a string then you can write a JSON.

  • use single quotes for the string
  • use double quotes for quoting key and value
  • multiline strings are posiible - and recommended for better readability

👉 Example:

When using the JSON format of

params[directory]="/tmp"
params[warning]="1GB"
params[critical]="500MB"

it looks like this:

params='{
    "directory": "/tmp",
    "warning": "1GB",
    "critical": "500MB"
}'

JSON strings can be used for

  • meta->tags
  • notifications->email
  • notifications->slack
  • <check>->params

⚠️ Keep in mind that within JSON you cannot expand variables.