Oracle-Datenbanken überwachen

Falls Sie nicht (fast) den ganzen langen Artikel lesen möchten, kommen hier ein paar Links mit Abkürzungen. Wenn Sie allerdings erstmalig das Oracle-Monitoring mit Checkmk aufsetzen, sollten Sie sich den Artikel vollständig durcharbeiten, um alle Möglichkeiten kennenzulernen.

Um Oracle-Instanzen und deren -Datenbanken mit Checkmk zu überwachen, müssen auf dem jeweiligen Host der Checkmk-Agent und das Agentenplugin mk-oracle-v2 installiert werden. Das Agentenplugin benötigt eine Konfiguration, welche Sie unter dem Namen mk-oracle.yml im Konfigurationsverzeichnis ablegen müssen. Außerdem ist das Agentenplugin auf Bibliotheken des Oracle Instant Client (OIC) angewiesen. Dieser muss also ebenfalls auf dem Host verfügbar sein.

Wie Sie OIC installieren können, erfahren Sie im Kapitel Voraussetzungen auf dem Oracle-Host schaffen.

Das Agentenplugin mk-oracle-v2 benötigt die Bibliotheken des Oracle Instant Client (OIC) um zu funktionieren. Sie haben drei Möglichkeiten, dass OIC zur Verfügung zu stellen.

Laden Sie zuerst das für Ihren Host passende Paket von der Seite Oracle Instant Client Downloads im ZIP-Format herunter.

Dem Agentenplugin mk-oracle-v2 muss Zugriff auf Ihre Oracle-Instanzen bzw. -Datenbanken gewährt werden. Dies können Sie entweder über einen Datenbank-Benutzer oder die Oracle Wallet machen.

Benutzer einer kommerziellen Edition von Checkmk können das Agentenplugin bequem über die Agentenregel Oracle databases (Experimental) konfigurieren. In diesem Kapitel konzentrieren wir uns dabei auf die Bereiche Authentifizierung, Verbindungsoptionen und datenbankspezifische Anmeldedaten. Alle weiteren Optionen, die der Regelsatz Oracle databases (Experimental) werden entweder schon hinreichend in der Inline-Hilfe erklärt oder im Referenzteil dieses Artikels erläutert.

Öffnen Sie jetzt also das Setup-Menü Ihrer Checkmk-Instanz und suchen Sie dort nach Oracle databases (Experimental) und öffnen Sie den Regelsatz. Klicken Sie auf Add rule und beginnen Sie mit der Konfigurations der Authentifizierungsmethode.

Im Referenzteil finden Sie Hinweise zu den Additional options.

Dieses Kapitel richtet sich an all diejenigen, die Checkmk Community verwenden oder auf die Verwendung der Agentenbäckerei verzichten möchten.

Sobald Sie die Voraussetzungen erfüllt haben, müssen Sie das Agentenplugin auf dem Oracle-Host installieren. An dieser Stelle sei bereits der Hinweis erlaubt, dass das etwas anders funktioniert, als Sie es womöglich von anderen Agentenplugins gewohnt sind.

Zu guter Letzt müssen Sie dem Agentenplugin noch eine Konfiguration mit auf den Weg geben.

Zuerst gehen wir nochmal die Voraussetzungen durch.

Checkmk bietet mit dem Agentenplugin bereits eine große Menge an SQL-Abfragen, mit denen Sie Ihre Datenbank-Instanzen überwachen können. Damit diese für eine möglichst große Menge an technischen und inhaltlichen Anforderungen passend sind, sind diese allgemein gehalten.

Um die individuellen Anforderungen eines jeden Unternehmens an das Monitoring einer konkreten Datenbank erfüllen zu können, bietet Checkmk die Möglichkeit, eigene, benutzerdefinierte SQL-Abfragen (Custom SQLs) zu erstellen und mit dem Agentenplugin abfragen zu lassen. Diese werden dann in Checkmk automatisch als Services erkannt und überwacht.

Um dem Agentenplugin Ihre Abfragen zu übergeben, haben Sie zwei Möglichkeiten:

Letzteres erleichtert die Wartbarkeit und auch eine Versionskontrolle wird erleichtert, wenn Inhalte in der Konfigurationsdatei des Plugins nicht vermischt werden. Wenn es allerdings ohnehin nur um eine kleine Anzahl an Abfragen geht, können Sie sich den zusätzlichen Aufwand gegebenenfalls auch sparen.

Wir zeigen zunächst ein einfaches Beispiel, welches direkt in die Konfigurationsdatei des Plugins geschrieben wird.

Den Anfang macht eine Abfrage, welche bereits echte Daten aus einer Oracle-Instanz zurückliefert. Das Beispiel soll nur verdeutlichen, wie einfach es sein kann, benutzerdefinierte SQL-Abfragen einzubinden. Wie sinnvoll exakt diese Abfrage im Arbeitsalltag ist, sei dahingestellt.

Tasten Sie sich an die später produktiv verwendbare Abfrage heran, indem Sie Ihre Ideen für SQL-Abfragen zunächst als sysdba ausführen. Damit möglicherweise lange laufende Abfragen kein Produktivsystem ausbremsen, empfehlen wir die Verwendung einer Test-Instanz.

Den Kopf dieser Ausgabe können Sie — genauso wie es das Agentenplugin tut — ignorieren. Wichtig ist das in der Abfrage verwendete Schlüsselwort details. Die Zeile, die so beginnt, wird sich das Check-Plugin auf dem Checkmk-Server schnappen und daraus die Summary des Services erzeugen. Aber woher weiß Checkmk denn, wie der Service eigentlich heißen soll? Den Namen des Service legen Sie fest, wenn wir die SQL-Abfrage in die Konfiguration für das Agentenplugin übertragen:

Unser Beispiel zeigt drei Dinge:

Nachdem Sie diese Zeile auf Ihrem Oracle-Host in die Konfigurationsdatei des Agentenplugins eingefügt haben, können Sie schon wieder zurück zu Ihrem Checkmk-Server gehen. Führen Sie dort für den Oracle-Host eine Service-Erkennung durch. Sie erhalten dann diesen neuen Service:

Der Service-Name setzt sich dabei aus mehreren Komponenten zusammen:

In der Summary sehen Sie dann bereits Daten, die aus dem Ergebnis der SQL-Abfrage stammen.

Es wird sicherlich Fälle geben, in denen eine solche einfache Abfrage bereits das ist, was Sie brauchen. In diesem Fall ist der Service aber wahrscheinlich noch wenig hilfreich. Deshalb zeigen wir Ihnen im Kapitel Erweiterte benutzerdefinierte SQL-Abfragen, wie Sie mit wenigen Handgriffen einen umfangreicheren Service erstellen können.

Ausgehend von dem Beispiel im Kapitel Einfache benutzerdefinierte SQL-Abfragen, zeigen wir Ihnen jetzt, wie Sie mit wenigen Handgriffen einen Service mit einer Metrik erhalten.

Hierfür bietet es sich an, die SQL-Abfrage aus der Konfigurationsdatei den Agentenplugins auszulagern. Stattdessen geben Sie hinter dem Schlüssel custom_metrics eine Datei an, in der das Agentenplugin Ihre SQL-Abfragen finden kann.

Wenn Sie die Datei ohne Angabe eines absoluten Pfades eintragen, durchsucht das Agentenplugin in einer bestimmten Reihenfolge einige Verzeichnisse. Welche das sind und was dabei genau passiert, erklären wir im Referenzteil dieses Artikels.

Legen Sie jetzt im Konfigurationsverzeichnis des Checkmk-Agenten ein Unterverzeichnis namens orasql an und erstellen Sie darin eine Datei mit der Endung .sql, wie Sie sie hinter path: angegeben haben.

In diesem Beispiel gehen wir davon aus, dass das Konfigurationsverzeichnis auf einem Linux-Host /etc/check_mk/ heißt. Erzeugen Sie zunächst das unbedingt notwendige Unterverzeichnis orasql.

Erstellen Sie darin im Anschluss die Datei myadvancedservice.sql. Darin können Sie jetzt deutlich bequemer auch mehrzeilige SQL-Abfragen unterbringen. Wichtig bleibt dabei, dass die Schlüsselwörter für das Check-Plugin vorkommen.

Zusätzlich zu der ersten Zeile, die Sie schon aus dem einfachen Beispiel kennen, gibt das SQL-Skript nun eine Zeile aus, die mit perfdata beginnt. Daraus wird Checkmk eine Metrik erzeugen und automatisch einen Graphen anlegen. Mit dem Schlüsselwort exit können Sie außerdem Zustand des Service beeinflussen. In diesem Beispiel wird er fix auf 0 gesetzt, was für den Zustand OK steht. Die Schlüsselwörter benötigt das Check-Plugin auf dem Checkmk-Server, um aus den angelieferten Daten Services und Metriken erzeugen zu können. Die vier Schlüsselwörter details, perfdata, long und exit erklären wir im Kapitel Formatierung der Ausgabe und Schlüsselwörter genau.

Wenn Sie das alles so angelegt haben und erneut eine Service-Erkennung durchführen, wird der alte Service verschwinden und stattdessen ein neuer, dessen Name auf MY ADVANCED SERVICE endet, gefunden werden.

In Checkmk 2.5.0 hat das neue Agentenplugin mk-oracle-v2 eine Fähigkeit, die Benutzern von mk_oracle dabei hilft auf das neue Agentenplugin umzusteigen. Übertragen Sie dazu mk-oracle-v2 auf Ihren Oracle-Host und führen Sie das Agentenplugin mit der Option -M, gefolgt vom Namen einer Konfigurationsdatei im alten Format, aus. Das Agentenplugin liest dann die Konfiguration für das alte mk_oracle ein und gibt sie in dem Format aus, die das mk-oracle-v2 erwartet.

Das kann dann beispielsweise so aussehen:

Standardmäßig schreibt mk-oracle-v2 die migrierte Konfiguration auf die Standardausgabe. Wir empfehlen das auch unbedingt im ersten Schritt, damit Sie die Ausgabe erst einmal prüfen können. Der Output enthält zuerst Ihre alte Konfiguration als Kommentar. Zu Referenzzwecken bietet es sich an, diesen Kommentar eine Weile vorzuhalten.

Wenn alles passt, können Sie mk-oracle-v2 mit der Option --migrate-output dazu anweisen, den Output direkt in eine Datei zu schreiben.

Sollte der Migrationsbefehl Teile Ihrer alten Konfiguration nicht migrieren können, so wird dies als #WARNING klar in der Ausgabe angezeigt.

Der folgenden Tabelle können Sie entnehmen, welche Variablen der Konfiguration von mk_oracle auf welche Weise übersetzt werden:

Die Einträge in der folgenden Tabelle werden nicht automatisch migriert und müssen von Ihnen händisch an das neue Plugin angepasst werden:

Das alte Agentenplugin mk_oracle leitet benutzerdefinierte SQL-Abfragen über das Kommandozeilen-Tool sqlplus weiter. Das Plugin mk-oracle-v2 hingegen führt SQL-Abfragen hingegen direkt über den Treiber des Oracle Instant Clients aus. Aus diesem Wechsel des Ausführungsmodells ergeben sich zwei wesentliche Konsequenzen für bestehende SQL-Abfragen.

Die kommerziellen Editionen von Checkmk werden mit einem eingebauten Dashboards für Oracle ausgeliefert. Die Zahl der Dashboard für Oracle wird in den kommenden Wochen noch steigen. Behalten Sie dazu gerne unsere Werks zum Thema Oracle im Blick.

Der Einstieg geschieht dabei immer über das Dashboard Oracle databases, welches Sie über Monitor > Applications > Oracle databases erreichen.

Im Normalbetrieb ruft der Checkmk-Agent nicht das Binary selbst auf, sondern die beiden Hilfsprogramme für den synchronen und den asynchronen Modus. Für die Diagnose rufen Sie das Binary direkt auf. Dabei benötigt das Agentenplugin dieselben Umgebungsvariablen, die ihm sonst der Checkmk-Agent mitgibt: MK_CONFDIR für das Konfigurationsverzeichnis, MK_LIBDIR für das Verzeichnis, in dem unter anderem der mit dem Agentenplugin bereitgestellte Oracle Instant Client liegt, und MK_LOGDIR für die Log-Datei.

Mit der Option --no-spool gibt das Agentenplugin alle Sektionen aus — die synchronen wie die asynchronen — und verzichtet dabei auf die Markierung für zwischengespeicherte Daten. Sie erhalten also die vollständige, aktuelle Ausgabe.

Kann das Agentenplugin keine Verbindung zu einer Oracle-Instanz herstellen, finden Sie dazu in der Sektion <<<oracle_instance:sep(124)>>> eine Zeile der Form <SID>|FAILURE|<Fehlermeldung>. Schlägt dagegen nur eine einzelne Abfrage fehl, steht eine solche Zeile anstelle des Ergebnisses in der betroffenen Sektion. Die Fehlermeldung enthält jeweils den Oracle-Fehlercode (ORA-xxxxx), mit dessen Hilfe Sie einfache Konfigurationsprobleme, wie falsche Zugangsdaten oder eine unbekannte Instanz, schnell identifizieren können.

Wenn das Agentenplugin gar keine Daten liefert, liegt das häufig daran, dass es keinen nutzbaren Oracle Instant Client findet. Mit der Option --find-runtime zeigt Ihnen das Agentenplugin, welche Client-Bibliothek und welches ORACLE_HOME es verwenden würde, ohne eine Verbindung zu einer Oracle-Instanz aufzubauen:

Die Ausgabe besteht aus Zeilen der Form VARIABLE=Wert: LD_LIBRARY_PATH (unter Windows PATH) mit dem Verzeichnis der Client-Bibliothek, gegebenenfalls ORACLE_HOME und gegebenenfalls RUN_AS.

Die Zeile RUN_AS erscheint, wenn das Agentenplugin unter Linux, Solaris oder AIX als root läuft und die Client-Bibliothek einem anderen Benutzer gehört — zum Beispiel oracle bei einer regulären Oracle-Installation. Das Agentenplugin wechselt dann vor der ersten Verbindung zu diesem Benutzer. Dieser Benutzer muss daher alle Dateien lesen können, auf die der Oracle-Client danach zugreift: sqlnet.ora, tnsnames.ora, das Oracle Wallet sowie Ihre Dateien mit benutzerdefinierten SQL-Abfragen.

Bevor das Agentenplugin die Client-Bibliothek lädt, prüft es außerdem deren Zugriffsrechte. Darf ein Unbefugter die Bibliothek oder eines der übergeordneten Verzeichnisse verändern, verweigert das Agentenplugin die Verwendung und nennt den Grund in seiner Ausgabe und in der Log-Datei. Korrigieren Sie in diesem Fall die Zugriffsrechte. Über die Optionen permissions_safe_entries und permissions_check in der Konfigurationsdatei können Sie diese Prüfung anpassen beziehungsweise als letzten Ausweg abschalten.

Welche Oracle-Instanzen das Agentenplugin auf dem lokalen Host findet, zeigt Ihnen die Option --detect-sids:

Das Agentenplugin listet dann die Instanzen aus der Datei oratab (unter Windows aus der Registry) mit SID, Status, ORACLE_HOME und ORACLE_BASE auf. Unter Linux, Solaris und AIX zeigt der Status zusätzlich, ob für die Instanz ein PMON-Prozess läuft. Unter Windows wird der Status nicht ermittelt.

Das Agentenplugin schreibt bei jeder Ausführung in die Log-Datei mk-oracle.log im Log-Verzeichnis des Agenten (MK_LOGDIR), unter Linux standardmäßig /var/log/check_mk_agent, unter Windows C:\ProgramData\checkmk\agent\log. Die Log-Datei wird rotiert, sobald sie 500.000 Byte erreicht. Dabei werden standardmäßig 5 Log-Dateien aufbewahrt.

Standardmäßig protokolliert das Agentenplugin auf der Stufe info. Stufe, Dateigröße und Anzahl der Log-Dateien legen Sie im Abschnitt system der Konfigurationsdatei fest:

Wenn Sie die Konfiguration über die Agentenbäckerei verteilen, wird mk-oracle.yml beim nächsten Update des Agenten überschrieben. Tragen Sie den Abschnitt system in diesem Fall in die Datei mk-oracle.user.yml im Verzeichnis des Agentenplugins ein (unter Linux /usr/lib/check_mk_agent/plugins/libexec/mk-oracle-v2/). Das Agentenplugin führt beide Dateien beim Start zusammen, wobei Ihre Angaben in mk-oracle.user.yml Vorrang haben.

Für eine einzelne manuelle Ausführung können Sie die Stufe des Loggings auch beim Aufruf bestimmen und die Log-Meldungen direkt im Terminal ausgeben lassen:

Die Option -l gibt die Log-Meldungen auf der Standardfehlerausgabe statt in der Log-Datei aus. Mit -v setzen Sie die Stufe auf debug, mit -vv auf trace. Auf der Stufe debug nennt das Log zum Beispiel jede verwendete SQL-Datei und jede ausgeführte SQL-Abfrage und misst die Dauer von Verbindungen, Sektionen und Abfragen. Die Stufe trace liefert die umfangreichste Ausgabe und sollte daher nur als letztes Mittel eingesetzt werden.

Über den Konfigurationsschlüssel custom_metrics definieren Sie Ad-hoc-SQL-Abfragen, deren Ausgaben auf dem Checkmk-Server durch das Check-Plugin oracle_sql ausgewertet werden. Jeder Eintrag wird durch einen Item-Namen identifiziert, der in Checkmk als Teil des Service-Namens angezeigt wird.

Im diesem Kapitel erklären wir alle Optionen, die zur Konfiguration des Agentenplugins existieren. Egal ob Sie das Agentenplugin über den Regelsatz Oracle databases (Experimental) konfigurieren oder ob Sie es manuell konfigurieren.

Die Erklärungen hier im Handbuch gehen mitunter über den Inhalt der Inline-Hilfe hinaus, wenn es beispielsweise interessante Hintergrundinformationen zu einer Option gibt und eine längere Erklärung für bestimmte Anwendungsfälle angebracht sind. Dazu geben wir jeweils auch an, welche Eintragung durch eine gewählte Option in der Konfigurationsdatei mk-oracle.yml entsteht.

Zusätzlich finden alle Interessierten die Beschreibung aller Optionen der mk-oracle.yml in unserer Beschreibung auf GitHub.

Maximale Anzahl der zu öffnenden Datenbank-Verbindungen.

Maximale Anzahl der Abfragen, die pro Verbindung ausgeführt werden dürfen.

Hier können Sie zwischen standard und wallet wählen.

Wählen Sie wallet sind keine weiteren Einstellungen an dieser Stelle nötig. Oracle Wallet bietet eine sichere Möglichkeit, sich bei Oracle-Datenbanken zu authentifizieren, ohne Passwörter im Klartext in Konfigurationsdateien zu speichern.

standard steht an dieser Stelle für die Authentifizierung per Benutzername und Passwort. Die Angabe von username und password ist dann auch zwingend notwendig.

Haben Sie sich für die Authentifizierung per Benutzername und Passwort entschieden, können Sie optional die Rolle des Benutzers angeben.

In dieser Option legen Sie die Verbindungsparameter auf Netzwerkebene fest, die für alle Instanzen gelten, sofern sie nicht in den datenbankspezifischen Einstellungen überschrieben werden.

Mit der Option Cache age können Sie die Gültigkeitsdauer des Caches von Sektion bestimmen, welche Sie asynchron überwachen.

Über die Optionen unter Instance discovery können Sie genau steuern, welche Instanzen Sie mit Checkmk überwachen möchten und welche Sie gegebenenfalls vom Monitoring ausschließen möchten. Die Option auch nur dann eine Funktion, wenn sich das Agentenplugin auf dem selben Host, wie die Instanzen befinden.

Mit dieser Option können Sie zielgenau festlegen, welche Daten über Ihre Instanzen und Datenbanken überhaupt durch das Agentenplugin abgefragt werden sollen. Zusätzlich können Sie pro Sektion festlegen, ob die Daten synchron oder asynchron abgefragt werden sollen. Die Angaben zu is_async im folgenden Beispiel zeigen unsere Standardeinstellungen.

Wenn einzelne oder gar alle Oracle-Instanzen auf einem Host unterschiedliche Login-Daten oder Verbindungseinstellungen aufweisen, dann müssen Sie diese im Abschnitt Databases to monitor einzeln konfigurieren. Um die einzelnen Datenbanken zu identifizieren, habe Sie die Auswahl aus SID, Alias, Service Name. Konsultieren Sie an dieser Stelle die Inline-Hilfe in der Regel, um mehr über die drei Optionen zu erfahren. In unserer Beschreibung auf GitHub finden Sie außerdem einige weitere Konfigurationsbeispiele.

Die folgenden Beispielkonfigurationen können Sie als Ausgangspunkte für die manuelle Einrichtung Ihres Oracle-Monitorings verwenden.