IN ENTWICKLUNG: Dieses HowTo ist noch nicht fertig
Dieser Leitfaden richtet sich an Plugin-Entwickler und erklärt die Standards und die Funktionsweise von Bloonix Plugins.
Ein Plugin ist ein einfaches Skript, welches ausgeführt wird, um den Status eines Service zu prüfen. Es gibt zum Beispiel das Plugin check-http, um einen Webservice über eine HTTP/HTTPS Abfrage zu prüfen. Zu jedem Plugin gibt es zusätzlich eine Datei, in der Metadaten abgelegt werden. Für das Plugin check-http ist das bespielsweise die Datei plugin-http, in der diese Metadaten stehen. Sie können sich beide Dateien einmal anschauen:
Zu beachten ist hier der Prefix beider Dateien. Für Skripts wird immer der Prefix check verwendet und für die Datei mit den Metadaten der Prefix plugin. Beide Dateien werden später benötigt, um die Metadaten in die Datenbank der WebGUI von Bloonix zu importieren, damit das Plugin in der WebGUI als Service eingerichtet werden kann.
Bloonix Plugins sollten in der Programmiersprache Perl entwickelt werden, da es für Perl ein Modul names Bloonix::Plugin gibt, mit dem die Entwicklung von Plugins deutlich vereinfacht und beschleunigt wird. Derzeit ist es nicht geplant, ein gleichwertiges Modul für andere Sprachen zu entwickeln.
Bevor Sie anfangen, ein Plugin für Bloonix zu entwickeln, sollten ein paar einfache Dinge beachtet werden. Die wohl wichtigste Regel ist:
Ein Plugin sollte so entwickelt sein, dass es nie länger als ca. 30 Sekunden benötigt, um einen Service zu prüfen. Wenn ein Service innerhalb von 30 Sekunden keine Antwort liefert, dann ist das als ein kritischer Status einzustufen. Wenn ein Service für gewöhnlich länger benötigt, um innerhalb von 30 Sekunden geprüft zu werden, dann ist der Service nicht dafür geeignet, um über ein Plugin geprüft zu werden. Stattdessen sollte ein Cronjob eingerichtet werden, der den Dienst auf irgendweine Weise prüft und den Status der Prüfung in eine Datei schreibt. Es kann daraufhin der Inhalt der Datei über ein Bloonix-Plugin geprüft werden.
Hier ein paar weitere einfache Regeln, an die sich ein Plugin-Entwickler halten sollte:
In diesem Abschnitt versuchen wir die Entwicklung eines Plugins von Bloonix anhand eines Beispiels aufzuzeigen. Dazu verwenden wir den Pluginnamen check-test. Beachten Sie bitte die Kommentare im Skript.
#!/usr/bin/perl
# Immer 'warnings' und 'strict' inkludieren.
use warnings;
use strict;
# Das Modul Bloonix::Plugin einbinden.
use Bloonix::Plugin;
# Ein neues Objekt von Bloonix::Plugin erzeugen und gleichzeitig
# die Versionsnummer des Plugins setzen.
my $plugin = Bloonix::Plugin->new(version => "0.1");
# Es sollte immer ein Beispiel angegeben werden, wie das Plugin
# ausgeführt werden kann. Ruft man die Hilfe auf, so wird das in
# der Ausgabe in etwa so aussehen:
# check-test --url https://www.bloonix.de/ --warning 3 --critial 5
$plugin->example(
description => "How to check a URL",
arguments => [
url => "https://www.bloonix.de/",
warning => 3,
critical => 5
]
);
# Mit der Methode add_option() wird eine Kommandozeilenoption
# definiert, in diesem Fall ist es die Option --url.
$plugin->add_option(
# Ein sprechender Name der Option. Der Name wird in der WebGUI
# im Formular zur Konfiguration von Services angezeigt.
name => "URL to check",
# Die Option, wie sie mit -- aufgerufen wird. Hier --url.
option => "url",
# Der Typ des Werts. Mögliche Angaben sind string, int, number.
# - string ist eine Zeichenkette
# - int ist eine Zahl von 0-n
# - number ist eine Zahl von 1-n
value_type => "string",
# Eine sehr kurze Beschreibung des Wertes. Die Beschreibung
# wird in der Hilfe angezeigt. Beispiel: --url <url to check>
value_desc => "url to check",
# Ist dies eine Pflichtoption? 1 für ja, 0 für nein.
mandatory => 1,
# Kann die Option mehrfach angegeben werden? 1 für ja, 0 für nein.
multiple => 0,
# Es kann mittels Regexp geprüft werden, ob der übergebene Wert
# korrekt ist. Hier wird beispielhaft geprüft, ob die URL
# einem bestimmten Format entspricht:
regex => qr!https{0,1}://[a-zA-Z0-9]+([.-][a-zA-Z0-9]+)*(:\d+){0,1}(/[^\s]*){0,1}\z!,
# Eine Beschreibung der Option.
description => "The URL you want to check."
);
$plugin->add_option(
name => "Warning threshold",
option => "warning",
value_type => "number",
value_desc => "seconds",
mandatory => 0,
multiple => 0,
default => 3,
description => "Trigger a WARNING status if the request takes longer."
);
$plugin->add_option(
name => "Crtitical threshold",
option => "critical",
value_type => "number",
value_desc => "seconds",
mandatory => 0,
multiple => 0,
default => 5,
description => "Trigger a CRITICAL status if the request takes longer."
);
# Die Argumente werden geprüft und validiert. Das Objekt $opt ist eine
# Hash-Referenz und enthält alle Argumente und Werte im Key-Value Format.
# Optionen wie zum Beispiel --use-ssl werden umgewandelt in den Hash-Key use_ssl.
my $opt = $plugin->parse_options;
# Bloonix::Plugin stellt die Methode runtime() zur Verfügung, um den Zeitabstand
# zwischen zwei Aufrufen zu messen. Beim erstmaligen Aufruf wird die Startzeit
# gespeichert.
$plugin->runtime;
# Nun prüfen wir vereinfacht, ob der Aufruf der URL erfolgreich war.
my @output = qx{curl '$opt->{url}' --retry 0 --silent --show-error --include 2>&1};
# Dieses Mal gibt runtime() die Zeit zurück, die seit dem ersten Aufruf
# vergangen ist.
my $time = $plugin->runtime;
if ($output[0] !~ m!^HTTP/1.1 200 OK!) {
$plugin->exit(
status => "CRITICAL",
message => "the request wasn't successful: $output[0]",
stats => {
time => $time
}
);
}
my $status = "OK";
# Zu guter Letzt prüfen wir die Antwortzeiten.
if ($opt->{critical} && $time >= $opt->{critical}) {
$status = "CRITICAL";
} elsif ($opt->{warning} && $time >= $opt->{warning}) {
$status = "WARNING";
}
# Die Methode exit() wird aufgerufen, um das Plugin zu beenden. Folgende Parameter sind erlaubt:
# status = Der Status der Prüfung. Dies kann OK, WARNING, CRITICAL oder UNKNOWN sein.
# message = Eine sprechende Statusmeldung.
# stats = Hier werden die Statistiken des Plugins im Format key->value gespeichert.
$plugin->exit(
status => $status,
message => "response time ${time}s",
stats => {
time => $time
}
);
Es folgen ein paar Beispiele zur Ausführung des Skripts:
# perl check-test --version
check-test v0.1
# perl check-test --help
Usage: check-test [ OPTIONS ]
Options:
--url <url to check>
Check the response time of a URL.
This option is mandatory.
--warning <seconds>
Trigger a WARNING status if the request takes longer.
Default: 3
--critical <seconds>
Trigger a CRITICAL status if the request takes longer.
Default: 5
--version
Print the version.
--help
Print the help.
--plugin-info
Print plugin information as JSON string.
--pretty
Print the plugin information in pretty format
Examples:
* Check the URL
check-test --url 'https://www.bloonix.de/' --warning '3' --critical '5'
Command line options as JSON string
* It's possible to pass the command line options as a JSON string:
check-test '{"option":"value","multiple":["value1","value"]}'
* It's also possible to pass the JSON string to STDIN of the plugin:
check-test --stdin <<EOT
{"option":"value","multiple":["value1","value"]}
EOT
# perl check-test --plugin-info --pretty
{
"plugin" : "check-test",
"version" : "0.1",
"flags" : "",
"options" : [
{
"name" : "URL to check",
"default" : null,
"description" : "Check the response time of a URL.",
"value_type" : "string",
"option" : "url",
"mandatory" : 1,
"multiple" : 0,
"value_desc" : "url to check"
},
{
"name" : "Warning threshold",
"default" : null,
"description" : "Trigger a WARNING status if the request takes longer.",
"value_type" : "number",
"option" : "warning",
"mandatory" : 0,
"multiple" : 0,
"default" : 3,
"value_desc" : "seconds"
},
{
"name" : "Crtitical threshold",
"default" : null,
"description" : "Trigger a CRITICAL status if the request takes longer.",
"value_type" : "number",
"option" : "critical",
"mandatory" : 0,
"multiple" : 0,
"default" : 5,
"value_desc" : "seconds"
}
],
"examples" : [
{
"command_line" : "check-test --url 'https://www.bloonix.de/' --warning '3' --critical '5'",
"arguments" : [
"url",
"https://www.bloonix.de/",
"warning",
3,
"critical",
5
],
"description" : [
"Check the URL"
]
}
]
}
# perl check-test --url https://www.bloonix.de/ --warning 3 --critical 5
{"status":"OK","stats":{"time":"0.016"},"message":"response time 0.016s"}
Entsprechend zum Skript wird die Datei plugin-test mit Metainformationen zum Plugin benötigt.
plugin {
id 100001
plugin Test.Check
command check-test
datatype statistic
category Test,HTTP,Network
netaccess yes
prefer remote
abstract TEST check
description Just a simple test script.
}
statistic {
statkey time
alias Response time
datatype float
units ms
description Time in milliseconds waiting for response.
}
chart {
id 1
title HTTP request - response time
options {
ylabel time in ms
chart-type area
series {
name time
color \#005467
}
}
}
Beschreibung plugin:
Parameter | Beschreibung |
---|---|
id | Eine eindeutige ID für das Plugin. Die ID darf sich nicht ändern und auch nicht für andere Plugins verwendet werden. Zu beachten ist, dass die IDs unter 100.000 für Bloonix selbst reserviert sind. Sollten Sie ein Plugin nur für eigene Zwecke entwickeln, so sollte eine ID ab 100.000 gewählt werden. |
plugin | Der Name des Plugins, welcher in der WebGUI angezeigt wird. |
command | Der Name des Skripts. |
datatype | Wenn das Plugin Statistiken ausgibt, sollte hier statistics angegeben werden, ansonsten none. |
category | Hier werden die Kategorien des Plugins angegeben. In der WebGUI kann nach Kategorien gefiiltern werden. |
netaccess | Hier wird angegeben, ob der Service, welcher geprüft wird, über eine Netzwerkverbindung geprüft werden kann. Mögliche Werte sind yes und no. |
prefer | Hier wird die bevorzugte Agent-Lokation angegeben, welche in der WebGUI standardmäßig ausgewählt ist. Mögliche Werte sind localhost, intranet und remote. |
abstract | Eine Kurzbeschreibung, welche in der WebGUI im Feld Beschreibung standardmäßig gesetzt wird. |
description | Eine Beschreibung des Plugins. |
Beschreibung statistic:
Parameter | Beschreibung |
---|---|
statkey | Der Schlüsselname der Statistik. |
alias | Ein Alias, welcher in den Charts statt des Schlüssels verwendet wird. |
datatype | Der Datentyp ist wichtig, denn die Statistiken werden validiert, bevor diese in der Datenbank gespeichert werden. Mögliche Werte sind smallint, integer, bigint, float und varchar(ZAHL). |
units | Hier wird angegeben, welche Einheit der statistische Wert hat. Gibt es keine Einheit, so kann der Parameter ausgelassen werden. Mögliche Werte sind: kilo, mega, giga, tera, peta, exa, zetta, yotta, bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, zettabytes, yottabytes, bits, kilobits, megabits, gigabits, terabits, petabits, exabits, zettabits, yottabits, ms, percent, temperature, unixtime |
description | Eine Beschreibung des statistischen Wertes. |
Beschreibung chart:
Parameter | Beschreibung |
---|---|
id | Eine eindeutige ID für den Chart. Diese ID darf innerhalb des Plugins nur einmal verwendet werden. Bitte beachten Sie, dass Benutzer in der WebGUI Chart-Views erstellen können. Zu diesen Chart-Views werden die Chart-IDs gespeichert. Eine Chart ID zu ändern bedeuted also, dass der Chart dann nicht mehr existiert. Eine Chart-ID zu ändern bedeuted, dass ein Benutzer eventuell etwas anderes angezeigt bekommt. |
title | Der Titel des Charts. |
options | Hier werden die Optionen für den Chart selber konfiguriert. |
Beschreibung chart -> options:
Parameter | Beschreibung |
---|---|
ylabel | Der Text auf der Y-Achse des Charts. |
chart-type | Mögliche Werte sind line und area. |
units | Hier wird die Grundlegende Einheit angegeben. Mögliche Werte sind bits, bytes und null. Die Einheit wird für die Umrechnung verwendet auf der Y-Achse verwendet. Sollte eine Umrechnung nicht erwünscht sein, so sollte hier null angegeben werden, was zum Beispiel für Prozentwerte sinnvoll ist. |
series | Unterhalb von Series gibt es nur zwei Parameter und zwar name und color. Geben Sie hier an, welche Statistik angezeigt werden soll und auch die gewünschte Farbe. |