# Gadgets

## Allgemeine Informationen

"Gadgets" sind kleine Programme, die Bilder aus Informationen erzeugen, die von NagVis geliefert werden. Die Hauptidee besteht darin, die Performance-Daten von Nagios an diese Programme zu liefern, um daraus nette Grafiken oder schicke Tachos, Thermometer oder ähnliches zu machen.
`share/userfiles/gadgets` enthält einige Beispiele, andere finden Sie unter Nagvis Exchange[1].

Die Gadgets können in jeder Sprache geschrieben werden, die von Ihrem Webserver interpretiert wird, wie z.B. PHP, Perl, ...

Gadgets werden nur für Services unterstützt. Ein Objekt kann in ein Gadget verwandelt werden, indem Sie view_type="gadget" und eine gültige gadget_url setzen.

NagVis unterstützt Gadgets ab Version 1.4[1].

NagVis 1.4 std_speedometer-Gadget auf einer Test-Map mit aktiviertem Label.

## Parameter

Die Gadgets bekommen ihre Informationen durch einen HTTP-Get-Aufruf von NagVis (wenn Sie `share/userfiles/gadgets/gadget_core.php` einbinden, werden zwei Arrays gefüllt. Mehr Informationen finden Sie in der (englischen) Beschreibung dort).

Die folgenden Parameter werden an die Gadgets geliefert:

Parameter | Beispielwert | Beschreibung | Variable
--- | --- | --- | ---
name1 | localhost | Der Name des Hosts | $aOpts['name1']
name2 | Current Load | Die Service-Beschreibung des Objekts | $aOpts['name2']
scale | 100 | Die Größe des Gadgets (in Prozent) | $aOpts['scale']
state | OK | Die Zeichenkette, die den aktuellen Status beschreibt (OK, WARNING, CRITICAL, UNKNOWN) | $aOpts['state']
stateType | HARD | Der Typ des aktuelles Status. Kann HARD oder SOFT sein | $aOpts['stateType']
ack | 0 | Wird auf 1 gesetzt, wenn der Status des entsprechenden Objekts bestätigt wurde (Neu in 1.5.4) | $aOpts['ack']
downtime | 0 | Wird auf 1 gesetzt, wenn sich das entsprechende Objekt in einer Ausfallzeit (Downtime) befindet (Neu in 1.5.4) | $aOpts['downtime']
perfdata | load1=0.960;5.000;10.000;0; load5=0.570;4.000;6.000;0; load15=0.540;3.000;4.000;0; | Die aktuellen Performance-Daten, die von Nagios geliefert werden. Es ist wichtig, gültige Performance-Daten zu haben! | $aPerfdata[<index>][<tag>]

Ein gültiger HTTP-get zum std_speedometer.php sieht wie folgt aus:

`std_speedometer.php?name1=localhost&name2=Current%20Load&state=OK&stateType=HARD&perfdata=load1=0.450;5.000;10.000;0;%20load5=0.260;4.000;6.000;0;%20load15=0.750;3.000;4.000;0;`

## wie ist es zu konfigurieren?

Bitte prüfen Sie die Parameter `view_type`, `gadget_url` und `gadget_opts` des Service-Objekts in der Formatbeschreibung der Map-Konfiguration. Hier eine Beispiel-Definition in Ihrer Map-Datei:

    define service {
       host_name=localhost
       service_description=root-volume
       x=50
       y=50
       view_type=gadget
       gadget_url=std_bar.php     // name of the file in share/userfiles/gadgets/
       // gadget_url=[http://localhost/nagvis/userfiles/gadgets/std_bar.php]     // valid as well
       // gadget_scale=200        // default is 100 (percent)
       // gadget_opts=columns=3 label=1    // gadget dependent
    }

## wie man ein eigenes Gadget anlegt

Mit Hilfe des Codes in gadgets_core.php werden zwei Arrays gefüllt. $aPerfdata enthält die Performance-Daten. $aOpts enthält die Optionen, die in gadget_opts gesetzt werden.

Das Einfachste ist, einen Blick auf std_speedometer zu werfen und die Kernbestandteile von dort anzupassen.

Sie sollten einen Beispiel-Performance-Daten-String in den Gadget-Code einfügen, indem Sie die Variable $sDummyPerfdata nutzen. Dies erlaubt es, das Gadget mit Dummy-Daten in der WUI anzuzeigen. Es ist viel einfacher, die Maps zu erstellen, wenn die Gadgets dort angezeigt werden. Wichtig: die Variable muss gesetzt werden, bevor gadgets_core.php über den include-Befehl geladen wird.

Ein zweites Beispiel finden Sie in std_speedometer2.php. Im Gegensatz zu std_speedometer unterstützt es auch check_multi-Ausgaben. Verschiedene Optionen beeinflussen das Verhalten des Gadgets:

Parameter | Beispielwert | Beschreibung
--- | --- | ---
label | 1 | 1 = Anzeige von Host-Name / Service-Beschreibung in der linken oberen Ecke des Graphen; 0 = Informationen nicht anzeigen (Default)
current | 1 | 1 = Anzeige des aktuellen Performance-Daten-Wertes (Default); 0 = Informationen nicht anzeigen
columns | 5 | Graphen können in Spalten angezeigt werden. Die Zahl der Zeilen wird anhand der maximalen Anzahl von Performance-Daten-Elementen ermittelt. Default ist 3
string | pct | Das Performance-Daten-Label muss die Zeichenkette enthalten, damit der Graph angezeigt wird. Im Falle von check_multi-Ausgaben wird nur der letzte Teil untersucht. Default ist eine leere Zeichenkette

NagVis 1.5 std_speedometer2-Gadget im normalen, warnenden und kritischen Zustand

Ein drittes Beispiel basiert auf einer Idee auf Nagvis Exchange. Performance-Daten werden als horizontaler Balken dargestellt. Das letzte Viertel des Graphs wechselt auf gelb oder rot, wenn die Performance-Daten WARNING oder CRITICAL andeuten. Der Status ist nicht der Zustand des Service! Das liegt daran, dass die Daten ggf. mehrere Datenreihen enthalten. In vielen Fällen sind nicht alle Datenreihen eines Service WARNING oder CRITICAL, so dass Sie sonst falsche Alarme bekommen würden (neu in 1.5.7 oder git neuer als 2010.12.12).

Parameter | Beispielwert | Beschreibung
--- | --- | ---
label | 1 | 1 = Anzeige von Host-Name / Service-Beschreibung im letzten Viertel des Graphen (Default); 0 = Informationen nicht anzeigen
current | 1 | 1 = Anzeigen der aktuellen Performance-Daten (Default); 0 = Informationen nicht anzeigen
columns | 5 | Graphen können in Spalten angezeigt werden. Die Zahl der Zeilen wird anhand der maximalen Anzahl von Performance-Daten-Elementen ermittelt. Default ist 3
string | pct | Das Performance-Daten-Label muss die Zeichenkette enthalten, damit der Graph angezeigt wird. Im Falle von check_multi-Ausgaben wird nur der letzte Teil untersucht. Default ist eine leere Zeichenkette
threshold | value | Legt fest, ob die WARNING- und CRITICAL-Schwellwerte in Prozent (Default) oder als Zahlenwert angezeigt werden

NagVis 1.5 std_bar-Gadget im normalen, warnenden und kritischen Zustand

Anmerkung: Dieses Gadget benutzt einen TrueType-Font, dessen Position und Name hartkodiert ist (Variablen $fontDir und $fontName). Wird die Datei nicht gefunden, dann wird ein eingebauter Font benutzt. Der Wert von $fontDir wechselt zwischen den Distributionen. Falls der Font nicht korrekt skaliert, dann prüfen Sie bitte die Einstellung (sie ist korrekt für OpenSuSE, andere Einstellungen sind auskommentiert).

[1] Die Verzeichnisstruktur hat sich zwischen NagVis 1.4.x und NagVis 1.5 geändert. Gadgets wurden in `nagvis/nagvis/gadgets` abgelegt und werden nun in `share/userfiles/gadgets` gespeichert. Gadgets von NagVis Exchange benutzen möglicherweise die alte Struktur, so dass Sie die Dateien ggf. an die neue Stelle kopieren müssen (z.B. `cp -pr <Quelle>/nagvis/nagvis/gadgets/<Gadget> <Ziel>/share/userfiles/gadgets/`).