Skip to content
Snippets Groups Projects
Commit aeb4671d authored by Hahn Axel (hahn)'s avatar Hahn Axel (hahn)
Browse files

update docs

parent e33e7b0d
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/10_Introduction.md
+ 0
− 8
View file @ aeb4671d
...@@ -24,11 +24,3 @@ With command line parameter `--ini=<INIFILE>` it processes the checks that are d ...@@ -24,11 +24,3 @@ With command line parameter `--ini=<INIFILE>` it processes the checks that are d
* A binary for your platform must be available for download or must be built. Linux x86_64 is the 1st target platform * A binary for your platform must be available for download or must be built. Linux x86_64 is the 1st target platform
* no other requirements/ dependencies * no other requirements/ dependencies
### To built a new binary
* git
* wget
* PHP 8 cli client (no special modules needed)
Tested on Linux only so far.
docs/30_Usage.md
+ 13
− 61
View file @ aeb4671d
...@@ -3,7 +3,7 @@ ...@@ -3,7 +3,7 @@
```text ```text
./amcli -h ./amcli -h
IML Appmonitor as CLI client 0.4 IML Appmonitor as CLI client 0.5
This client performs appmonitor checks and puts the results as JSON to stdout. This client performs appmonitor checks and puts the results as JSON to stdout.
It contains all checks that are available in the PHP appmonitor client. It contains all checks that are available in the PHP appmonitor client.
...@@ -31,12 +31,15 @@ You find example snippets in the source code of this project in tests/config/. ...@@ -31,12 +31,15 @@ You find example snippets in the source code of this project in tests/config/.
🔷 OPTIONS: 🔷 OPTIONS:
-h, --help Print this help and exit -h, --help Print this help and exit
-i, --ini Set an INI File to parse
-l, --list list available checks and exit -i, --ini Set an INI File to parse
-m, --modules list available Php modules in this binary and exit -v, --verbose Enable verbose output (written to STDERR)
-v, --verbose Enable verbose output (written to STDERR)
-V, --version Show version and exit -b, --buildinfos show build information and exit
-l, --list list available checks and exit
-m, --modules list available Php modules in this binary and exit
-V, --version Show version and exit
👉 EXAMPLES: 👉 EXAMPLES:
...@@ -57,61 +60,10 @@ To execute it use the `--ini` parameter and reference the file (as absolute path ...@@ -57,61 +60,10 @@ To execute it use the `--ini` parameter and reference the file (as absolute path
`[<PATH>]amcli --ini=<FILENAME>` `[<PATH>]amcli --ini=<FILENAME>`
## Define checks Recommendations:
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>]` - define one check per section.
First an example:
```ini
[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. * The output is JSON in a single line. You can use `jq` to beautify it, eg `[<PATH>]amcli --ini=<FILENAME> | jq`
* If the bahaviuor seems to be unwanted use `-v` to enable verbose mode. You get more debug output during the execution, showing parsed ini file and more. `[<PATH>]amcli --ini=<FILENAME> -v`
## Exitcodes ## Exitcodes
......
docs/40_Configuration.md 0 → 100644
+ 223
− 0
View file @ aeb4671d
## 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:
```ini
[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:
```ini
[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:
```ini
[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:
```php
$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:
```ini
["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:
```txt
API_URL="https://www.example.com/api/v1/"
```
it can be expanded if your ini contains `$API_URL`:
```txt
["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
```ini
params[directory]="/tmp"
params[warning]="1GB"
params[critical]="500MB"
```
it looks like this:
```ini
params='{
"directory": "/tmp",
"warning": "1GB",
"critical": "500MB"
}'
```
⚠️ Keep in mind that within JSON you cannot expand variables.
docs/40_Embed.md → docs/50_Embed.md
+ 1
− 19
View file @ aeb4671d
...@@ -8,7 +8,7 @@ To embed the cli tool into your web application you need to ...@@ -8,7 +8,7 @@ To embed the cli tool into your web application you need to
* if it is `0` then the excution was successful - we have a result. You can send the JSON after setting the content type as http response header * if it is `0` then the excution was successful - we have a result. You can send the JSON after setting the content type as http response header
* if it is `> 0` the response is no JSON syntax. You should send the output that the error is seen in the appm nitor server. * if it is `> 0` the response is no JSON syntax. You should send the output that the error is seen in the appm nitor server.
Don't forget to protect the ini file and the monitoring request. See page Security. ⚠️ Don't forget to protect the ini file and the monitoring request. See page Security.
## PHP ## PHP
...@@ -31,27 +31,9 @@ if ($iRc == 0) { ...@@ -31,27 +31,9 @@ if ($iRc == 0) {
echo implode("\n", $aOut); echo implode("\n", $aOut);
``` ```
To test it:
(1)
Start PHP webserver
```txt
$ cd examples
$ php -S localhost:9000
[Fri Mar 7 09:01:52 2025] PHP 8.4.4 Development Server (http://localhost:9000) started
```
(2)
In a webbrowser open <http://localhost:9000/embed_example.php>
## Cronjob ## Cronjob
You can setup a cronjob starting every minute. Its output you can write into a json file that is accessible by the webservice. You can setup a cronjob starting every minute. Its output you can write into a json file that is accessible by the webservice.
You can
(1) (1)
......
docs/50_Security.md → docs/70_Security.md
+ 0
− 0
View file @ aeb4671d
File moved
docs/60_Build.md → docs/80_Build.md
+ 3
− 1
View file @ aeb4671d
## Requirements ## Requirements
### Linux
To update and test the command line tool you need To update and test the command line tool you need
* git * git
...@@ -81,7 +83,7 @@ You need to re-run install.php + build.php if ...@@ -81,7 +83,7 @@ You need to re-run install.php + build.php if
* there is a newer appmonitor client version * there is a newer appmonitor client version
* you compile with a newer php version * you compile with a newer php version
* you change the set of included php modules. * you change the set of included php modules. For database access are included sqlite, mysql and postgres. For other database types supported by PHP you need to add the module in inc_vars.php `$php_libs="..."` and recompile the binary: `php installer.php && php build.php;`.
The build.php (without install.php) needs to be executed if the src/amcli.php was changed. The build.php (without install.php) needs to be executed if the src/amcli.php was changed.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment