Monitoring

Allgemein

Informationen

• Der Monitoring-Dienst soll die automatisierte Überwachung der Komponenten des PLANTA-Dienstes ermöglichen.
• Als eigenständige Komponente fragt er bei Bedarf (= HTTP-Abfrage) die Komponenten nach Statusinformationen ab und generiert ein dementsprechendes HTML-Dokument, das den Status jeder überwachten Komponente anzeigt.
• Durch die HTTP-basierte Schnittstelle ist die Anbindung an verschiedene Überwachungssysteme möglich.
• Diese Dokumentation soll den Betreiber der PLANTA-Software in die Lage versetzen, die Monitoring-Komponente einzurichten und zu betreiben.
• Des Weiteren soll durch Beschreibung der Abfragesyntax und der Ausgabeformate die Nutzung der Statusinformationen in einer automatisierten Überwachungsinfrastruktur ermöglicht werden.

Installation

Details

• Im Server-Release-Paket kann nun auch die Monitoring-Komponente bei der Installation ausgewählt werden.
• Werden die Monitoring-Komponente und der Server bei der Installation gleichzeitig ausgewählt, werden die Parameter für das Datenbank- und das PLANTA-Server-Plug-in bereits eingetragen, sodass nur noch die folgenden Einstellungen vorgenommen werden müssen:
  • Port der Monitoring-Komponente: Auf diesem Port ist die Web-Schnittstelle zu erreichen.
  • Netzwerkschnittstelle: Kann im Normalfall auf dem Default-Wert 0.0.0.0 (von überall erreichbar) verbleiben.
  • Name des Dienstes: Hier ist ein eindeutiger Name vonnöten (Bitte vor allem bei Installation mehrerer Instanzen beachten!).
• Wenn der Server mitinstalliert wird, ist der Port für die Monitoring-Schnittstelle dort zu vergeben.
• Anderenfalls müssen das Installationsverzeichnis des bereits installierten PLANTA-Servers und ein Port für die Monitoring-Schnittstelle angegeben werden, da in diesem Fall eine Einstellung des PLANTA-Servers benötigt wird.

Konfiguration

Verbindungs- und Plug-in-Konfiguration mittels monitoring_configuration.xml

Information

• Die Konfiguration wird in XML-Syntax durchgeführt.

Details

• Beim Start der Monitoring-Komponente wird eine Prüfung der Syntax anhand der XML-Schema-Datei monitoring_configuration.xsd vorgenommen.
  • Auf Syntax-Fehler wird in der Log-Datei hingewiesen.
• In dem Hauptknoten Configure wird über das Attribut directory das Plug-in-Verzeichnis festgelegt.
  • Die Standardeinstellung sollte hier beibehalten werden:

<!--
* Monitoring configuration
* directory: the path where all directories are placed
-->
<Configure directory="plugins">

• Der intern verwendete Web-Server kann über den Knoten Server bzw. dessen Attribute host und port konfiguriert werden.
• Soll der Monitoring-Dienst nur lokal erreichbar sein, verwendet man "localhost", ansonsten ermöglicht "0.0.0.0" den Zugriff über alle Netzwerkschnittstellen.

<!--
Server configuration
* it is also possible to add multiple host/ports by adding another server-tag
* host-attribute: server-host where monitoring is accessable
* port-attribute: server-port
-->

<Server host="localhost" port="9092"/>
<Server host="0.0.0.0" port="9092"/>

• Das URL-Schema ist konfigurierbar.
• Hierzu existiert das Element UrlConfig, welches im nachfolgenden Konfigurationsauszug exemplarisch gezeigt wird.
• Im Attribut table_pattern wird ein Präfix konfiguriert, das für jede Seiten-URL des Monitoringdienstes gleich ist.
  • Das Abfragetrennzeichen "?" kann nur hier verwendet werden.
• Das Attribut json_suffix steuert das Suffix, mit dem die JSON-Ansicht erreicht werden kann.
• Der Platzhalter "page" verweist auf die Knoten "Page".
• Für die Kategorien und Komponenten existieren jeweils Platzhalter, welche durch den Namen ersetzt werden.

<!--
URL configuration
* category and component are variable parameters
* category = categoryname in node "Category"
* component = Plug-In-Title
-->
<UrlConfig table_pattern="/monitoring?monitoring[page]" json_suffix="/view=json">
<Page id="overview" url=""/>
<Page id="detail" url="=detail"/>
<Page id="category" url="=[category]"/>
<Page id="component" url="=component&amp;component=[component]"/>
</UrlConfig>

• Im Knoten PlugIn wird ein Plug-in konfiguriert, das die Erreichbarkeit einer Komponente abprüft.
• Es erhält die Zuordnung zu einer Kategorie, unter der das Plug-in gruppiert werden kann.
• Die Timeout-Einstellungen ermöglichen die Erreichbarkeit der Monitoring-Komponente auch bei langsamer oder gar blockierter Rückmeldung des Plug-ins.
• Zusätzliche Konfigurationsknoten existieren zur internen Konfiguration des Plug-ins; dies ist Plug-in-spezifisch.

<PlugIn filename="planta_plugin" title="PlantaServer" plugin_data_lifetime="20000" request_timeout="1000" hard_timeout="20000">
<Category>Application</Category>
<PlugInConfig host="127.0.0.1" port="27777"/>
</PlugIn>

Details zu den Attributen plugin_data_lifetime, request_timeout und hard_timeout (alle Werte in Millisekunden):

• • plugin_data_lifetime
    • Soll eine Komponente bei sehr häufigen oder zeitintensiven Abfragen entlastet werden, cached der Monitoring-Dienst die Daten für die angegebene Zeitspanne.
  • request_timeout
    • Bei Laufzeiten von Komponentenanfragen, die über der angegeben Zeitspanne liegen, wird der Status Timeout gesetzt und die Anfrageergebnisse erst bei erneuter Nutzeranfrage abgerufen.
  • hard_timeout
    • Wie bei request_timeout, die Komponentenanfrage wird jedoch abgebrochen.
• Ein Plug-in kann auch mehrfach konfiguriert werden, wobei unterschiedliche Namen im title -Attribut verwendet werden müssen.
  • So können mehrere PLANTA-Server-Instanzen oder mehrere Datenbanken überwacht werden.
• Der Auslieferungszustand der Konfigurationsdatei enthält bereits Konfigurationsschemata aller mitgelieferten Plug-ins, so dass diese nur angepasst bzw. kopiert werden müssen.

Plug-in-spezifische Einstellungen

PLANTA-Server

Informationen

• Zur Nutzung des Plug-ins muss der entsprechende PLANTA-Service für den Monitoring-Dienst konfiguriert sein.
• Dies ist über die hier beschriebenen Parameter monitoring, monitoring_interface und monitoring_port erreichbar.
• Entsprechend des Installationsortes bzw. der Konfiguration des PLANTA-Services sind die Attribute host und port des Knotens PluginConfig zu setzen:

<PluginConfig host="<Rechnername/IP des Servers, auf dem PLANTA-Service läuft>" port="<wie in globals.conf - monitoring_port angegeben>" />

Datenbank

Informationen

• Mit diesem Plugin kann der Status der Datenbank bzw. deren Verwendbarkeit durch den PLANTA-Service über einen Datenbankbenutzer geprüft werden.
• Die Konfigurationswerte können und sollten der Konfigurationsdatei hibernate.cfg.xml entnommen werden.
• host, port und sid entsprechen den drei durch : (Doppelpunkt) getrennten Werten im Text in hibernate.connection.url (Schema: <...>@host:port:sid).
• user und password entsprechen den jeweiligen Werten in hibernate.connection.username und hibernate.connection.password.
• license erhält den dreistelligen Lizenzschlüssel der Installation. Dieser muss in der DT345 Systemparameter vorhanden sein.
• Beispiel

<PlugIn filename="database_plugin" title="Database" plugin_data_lifetime="20000" request_timeout="1000" hard_timeout="20000">
<Category>Backend</Category>
<PlugInConfig host="orasrv.mycompany.com" port="1521" sid="orasrv" user="PL1" password="secret" license="100" />
</PlugIn>

Logging-Konfiguration mittels =logback.xml

Informationen

• Die Monitoring-Komponente nutzt als Rahmenwerk für Lognachrichten SLF4J, während als Backend Logback verwendet wird.
• Konfigurationsdetails sind in der Projektdokumentation von Logback nachzuschlagen.
• Über die Konfiguration des Schwellwertes kann im Fehlerfall durch erhöhte Verbosität Ursachenforschung ermöglicht werden.
  • Log-Schwellwerte (nach aufsteigender Verbosität sortiert)
    • error > warn > info > debug > trace
• Hierzu ist, wie im folgenden Ausschnitt der Konfigurationsdatei, das level -Attribut des Knoten root auf einen Schwellwert mit höherer Verbosität zu setzen:

<root level="debug">
<appender-ref ref="FILE" />
<appender-ref ref="STDOUT" />
</root>

Nutzungsdetails

Informationen

• Auf Informationen zu den Komponenten kann über URLs zugegriffen werden.
• Die Informationen sind sowohl im HTML-Format (v.a. zur manuellen Betrachtung) als auch im JSON-Format (zur maschinellen Verarbeitung geeignet) abrufbar.
• Für die JSON-Ausgabe wird das an die URL der HTML-Ausgabe angehängte konfigurierte json_suffix verwendet (in der Standardkonfiguration /json).
• Im Folgenden werden die Möglichkeiten zur Abfrage und die Ausgabeformate am Beispiel eines auf localhost mit Port 9092 konfigurierten Monitoring-Servers erläutert.

Erläuterung des Rückgabeformates

Informationen

• In der folgenden Tabelle sind die Überschriften der zurückgegebenen HTML-Tabelle bzw. die Schlüssel des in der JSON-Abfrage zurückgegebenen Verzeichnisses für die Komponentenansicht angegeben.
• Alle anderen Ansichten enthalten eine Untermenge dieser Attribute.
• Die Übersichtsseite fasst die Attribute State und Component State zusammen, so dass State hier immer NOK ist, wenn eines der Statusattribute NOK ist.

Details

Überschrift/Schlüssel	Rückgabewert	Beschreibung
Title	Name	Bezeichnung der Komponente
Description	Text	Beschreibung der Komponente
Release Date	Datum/Zeitstempel	Freigabe-Zeitstempel
Release Version	Versionsbezeichnung
Build Date	Datum/Zeitstempel	Erstell-Zeitpunkt
Build Version	Versionsbezeichnung
State	OK/NOK/TIMEOUT	Status der Komponenten-Plug-in-Instanz
Component State	OK/NOK	Status der Komponente
Comment	Text	Zusatzinformationen, z.B. Exception
Response Time	Dauer in ms	Reaktionszeit des Komponenten-Plug-ins
Required System Properties	Text
Start Time	Zeitstempel	Start-Zeitpunkt der Komponente, falls vorhanden
Extended	zusätzliches Verzeichnis	Enthält weitere Plug-in-spezifische Attribute

Übersicht

Informationen

• Konfiguration: Page-ID overview
• Eine Übersicht über alle Kategorien sowie der darin verwalteten Komponenten erhält man in der Standardkonfiguration durch:

http://localhost:9092/monitoring

• Der Status der Komponenten ist hier die Hauptinformation
• Die Aktualität dieses Status ist hier mit angegeben, um die Aussagekraft bewerten zu können.

Detailübersicht

Informationen

• Konfiguration: Page-ID detail
• Detailliertere Information zu allen Komponenten sind über /monitoring=detail abrufbar:

http://localhost:9092/monitoring=detail

Kategorieübersicht

Informationen

• Konfiguration: Page-ID category - die Variable [category] wird dann mit dem Kategorienamen ersetzt
• Die Kategorieübersicht zeigt detaillierte Informationen über alle in der Kategorie verwalteten Komponenten an (hier für die Kategorie Application gezeigt):

http://localhost:9092/monitoring=Application

Komponentenübersicht

Informationen

• Konfiguration: Page-ID component - Die Variable [component] wird dann durch den Komponenten-Namen ersetzt
• Soll nur eine einzelne Komponente überwacht werden, bietet der Aufruf der Komponentenansicht alle erfassten Informationen (hier für die Komponente mit Namen PlantaServer gezeigt):

http://localhost:9092/monitoring=component&component=PlantaServer

Betriebsinformationen

Dienstverwaltung

Informationen

• Der Dienst wird sowohl unter Windows als auch unter Linux während der Installation automatisch eingerichtet.
• Zur gleichen Zeit wird auch der Name des Dienstes vergeben.
• Der Betreiber kann den Dienst im Verzeichnis [Installationsort]/yajsw/bat über die folgenden Skripte verwalten (Administrationsrechte werden benötigt):

Aktion	Linux	Windows
Abfrage des aktuellen Status	queryDaemon.sh	queryService.bat
Starten des Dienstes	startDaemon.sh	startService.bat
Stoppen des Dienstes	stopDaemon.sh	stopService.sh
Installieren des Dienstes	installDaemon.sh	installService.bat
Löschen des Dienstes	uninstallDaemon.sh	uninstallService.bat

Logging

Informationen

• Im Verzeichnis log/ am Installationsort werden Log-Dateien angelegt.
• Diese sind bei einem vorkonfigurierten Log-Schwellwert von warn mit täglicher Rotation konfiguriert.
• Sollte der Betrieb der Monitoring-Komponente Probleme bereiten, sind diese Log-Dateien zu kontrollieren, da sie Hinweise auf die Ursachen aufzeigen können.
• Eine ausführlichere Ausgabe von Log-Nachrichten ist wie in Abschnitt Logging-Konfiguration beschrieben erreichbar.

Monitoring-Schnittstelle des PLANTA Server

Informationen

• Die durch den Monitoring-Dienst genutzte Schnittstelle im PLANTA Server ist auch direkt verwendbar.
• So kann auch eine Anbindung an andere Monitoringsysteme, wie z.B. Nagios, ermöglicht werden.
• Funktionen, die der Monitoring Dienst implementiert, sind dann nicht verfügbar, z.B. Datenbank-Überwachung oder Caching bei aufwendigen Monitoring-Funktionen.
• Die Server-Schnittstelle wird über die Parameter monitoring, monitoring_interface und monitoring_port in der Konfigurationsdatei globals.conf aktiviert und konfiguriert.
• Beispiel: auf dem Server test1.example.com werden die Parameter wie folgt gesetzt:
  • monitoring=true: aktiviert die Server-Schnittstelle.
  • monitoring_interface=0.0.0.0: ermöglicht Zugriff über alle Netzwerkschnittstellen.
  • monitoring_port=27777: Port, auf dem die Schnittstelle lauscht.
• Bei einem entsprechend konfigurierten PLANTA Server können Serverinformationen nun über die URL test1.example.com:27777/monitoring abgefragt werden.
• Zurückgegeben wird ein Verzeichnis im JSON-Format; zur maschinellen Auswertung ist die Dekodierung des Strings vonnöten.
• Beispielrückgabe:

{"Component State":"OK","Release Date":"Fri Feb 28 13:57:14 CET 2014",
"Start Time":"Wed Mar 05 21:55:25 CET 2014","Release Version":"46656",
"Build Date":"Fri Feb 28 13:57:14 CET 2014","Build Version":"46656"}