IN ENTWICKLUNG: Dieses HowTo ist noch nicht fertig

HowTo: Plugins entwickeln

Dieser Leitfaden richtet sich an Plugin-Entwickler und erklärt die Standards und die Funktionsweise von Bloonix Plugins.

Allgemeines

Was ist ein Plugin

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:

• check-http - das Skript, welches ausgeführt wird
• plugin-http - Metadaten zum Plugin sowie die Konfiguration der Charts

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.

Programmiersprache Perl

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.

Regeln, die beachtet werden sollten

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:

• Ein Plugin sollte bei blockierenden Aktionen dafür sorgen, dass es selbstständig auf einen Timeout läuft.
• Ein Plugin ist nicht dafür geeignet, Services zu starten, zu stoppen oder zu konfigurieren.
• Ein Plugin sollte niemals blind alle Parameter verwenden, die über die WebGUI konfiguriert werden.
• Sollte ein Plugin eine spezielle Konfiguration benötigen, so ist diese unter /etc/bloonix/agent abzulegen.
• Beim Öffnen oder Schreiben von Dateien sollten ".." Angaben im Pfad zur Datei einen Fehler auslösen.
• Bitte nur die englische Sprache in Plugins verwenden.

Plugins entwickeln

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.

Entwicklung: check-test

#!/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"}

Entwicklung: plugin-test

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:

Beschreibung statistic:

Beschreibung chart:

Beschreibung chart -> options: