EN | DE

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:

ParameterBeschreibung
idEine 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.
pluginDer Name des Plugins, welcher in der WebGUI angezeigt wird.
commandDer Name des Skripts.
datatypeWenn das Plugin Statistiken ausgibt, sollte hier statistics angegeben werden, ansonsten none.
categoryHier werden die Kategorien des Plugins angegeben. In der WebGUI kann nach Kategorien gefiiltern werden.
netaccessHier wird angegeben, ob der Service, welcher geprüft wird, über eine Netzwerkverbindung geprüft werden kann. Mögliche Werte sind yes und no.
preferHier wird die bevorzugte Agent-Lokation angegeben, welche in der WebGUI standardmäßig ausgewählt ist. Mögliche Werte sind localhost, intranet und remote.
abstractEine Kurzbeschreibung, welche in der WebGUI im Feld Beschreibung standardmäßig gesetzt wird.
descriptionEine Beschreibung des Plugins.

Beschreibung statistic:

ParameterBeschreibung
statkeyDer Schlüsselname der Statistik.
aliasEin Alias, welcher in den Charts statt des Schlüssels verwendet wird.
datatypeDer 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).
unitsHier 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
descriptionEine Beschreibung des statistischen Wertes.

Beschreibung chart:

ParameterBeschreibung
idEine 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.
titleDer Titel des Charts.
optionsHier werden die Optionen für den Chart selber konfiguriert.

Beschreibung chart -> options:

ParameterBeschreibung
ylabelDer Text auf der Y-Achse des Charts.
chart-typeMögliche Werte sind line und area.
unitsHier 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.
seriesUnterhalb 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.
Über Bloonix - Über Bloonix | Über Bloonix - Lizenzen | Über Bloonix - Wie funktioniert Bloonix | Über Bloonix - Feature Liste | Über Bloonix - Plugins | Über Bloonix - Systemanforderungen | Sicherheit - Allgemein | Sicherheit - Agent und Satellit | Installation - Wichtige Information vorab | Installation - Repositories | Installation - Elasticsearch | Installation - PostgreSQL | Installation - MySQL/MariaDB | Installation - Nginx | Installation - Bloonix-WebGUI | Installation - Bloonix-Server | Installation - Bloonix-Plugins | Installation - Bloonix-Agent | Installation - Bloonix-WTRM | Installation - Manuelle Installation | Installation - Quick Guide für CentOS 7 und PostgreSQL | Installation - Quick Guide für CentOS 7 und MariaDB | Installation - Quick Guide für Debian 8 und MariaDB | Konfiguration - Allgemeines | Konfiguration - Bloonix-WebGUI | Konfiguration - Bloonix-Server | Konfiguration - Bloonix-Service-Checker | Konfiguration - Bloonix-Agent | Konfiguration - Skripte und Cronjobs | HowTos - Plugins entwickeln | HowTos - Coding mit Stil | HowTos - Dokumentation auf Bloonix.org | HowTos - Verteilte Überwachung mit dem Bloonix-Satelliten | HowTos - Automatische Registrierung von Hosts | FAQ - Wie überwacht Bloonix Hosts und Services | WebGUI - Die Bloonix-WebGUI | WebGUI - Commpanies und wie diese funktionieren | WebGUI - Einen neuen Host anlegen | WebGUI - Host Parameter im Detail | WebGUI - Host Variablen | WebGUI - Host Templates | WebGUI - Klassen von Hosts | WebGUI - Einen neuen Service anlegen | WebGUI - Service Parameter im Detail | WebGUI - Host-Alive-Checks | WebGUI - Web-Transactions | WebGUI - Abhängigkeiten | WebGUI - Geplante Wartungsarbeiten | WebGUI - Kontakte und Benachrichtigungen | WebGUI - Benutzer- und Gruppenverwaltung | WebGUI - Eigene Charts erstellen | WebGUI - Notification Screen | WebGUI - Die Bloonix JSON API | WebGUI - Den Bloonix-Agenten installieren | WebGUI - Den Bloonix-Agenten konfigurieren