Oracle-Datenbanken überwachen

Die hier vorgestellte Funktionalität ist die Vorschau auf ein neues Feature, das bis auf weiteres Wandel und Erweiterung unterworfen ist und daher als experimentell (experimental) bezeichnet wird. In diesem Zustand ist es möglich, dass Funktionalität nicht nur hinzugefügt, sondern auch so umgebaut wird, dass eine bereits vorhandene Konfiguration obsolet wird und Sie diese neu erstellen müssen. Wir bitten dafür um Verständnis.

1. Einleitung

In diesem Artikel erfahren Sie, wie Sie mit dem neuen Agentenplugin mk-oracle Oracle-Datenbanken überwachen können.

Wenn Sie Informationen zum alten Agentenplugin mk_oracle suchen, schauen Sie bitte in den gleichnamigen Artikel im 2.4.0er-Zweig des Handbuchs.

So können Sie mit dem Agentenplugin nicht nur Tablespaces oder die aktiven Sitzungen einer Datenbank abrufen, sondern zusätzlich noch viele andere Metriken. Eine vollständige Liste der Überwachungsmöglichkeiten mit unseren Check-Plugins können Sie im Katalog der Check-Plugins nachlesen.

Die Ausgaben von mk-oracle gleichen denen des alten Plugins, so das exakt die selben Check-Plugins weiterverwendet werden.

Das neue Agentenplugin für die Überwachung von Oracle ist eine ausführbare Binärdatei. Es wird bereitgestellt für IBM AIX (64 Bit POWER), Linux (x86_64), Oracle Solaris (x86_64) und Windows (x86_64). Wir werden das neue Agentenplugin in einer der kommenden Versionen von Checkmk auch für Linux auf aarch64 (64 Bit ARM) anbieten. Bis dahin müssen Sie auf dieser Architektur zum alten Shell-Skript greifen.

1.1. Überblick über diesen Artikel

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.

Wie Sie den Oracle Instant Client (OIC) installieren erfahren Sie im Kapitel „Oracle Instant Client (OIC) bereitstellen“.
Nutzende der Agentenbäckerei in den kommerziellen Editionen von Checkmk bekommen im Kapitel „Konfiguration für das Agentenplugin erstellen“ eine Erklärung der wichtigsten Optionen. Im Referenzteil dieses Artikels gehen wir dann nochmal auf alle Konfigurationsoptionen ein und zeigen an dieser Stelle auch, zu welchen Einträgen die Optionen aus der Regel Unified Oracle plug-in (experimental) in der Konfigurationsdatei mk-oracle.yml führt.
Sollten Ihnen die Datenpunkte, die das Agentenplugin „out-of-the-box“ mitbringt, nicht genügen, können Sie Ihre Datenbanken auch per benutzerdefinierten SQL-Abfragen (Custom SQLs) überwachen.
Nutzende, die vom mk_oracle auf mk-oracle umsteigen möchten, können unsere Skripte zur Regel- und Konfigurationsmigration verwenden, um sich den Umstieg zu erleichtern.

1.2. Wie funktioniert das Oracle-Monitoring mit Checkmk?

Um Oracle-Instanzen und deren -Datenbanken mit Checkmk zu überwachen, müssen auf dem jeweiligen Host der Checkmk-Agent und das Agentenplugin mk-oracle 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.

2. Voraussetzungen auf dem Oracle-Host schaffen

Auf jedem Host auf dem sie Oracle-Datenbanken bzw. -Instanzen überwachen möchten, müssen Sie zwei Voraussetzungen schaffen.

Die Client-Bibliothek Oracle Instant Client (OIC) muss für das Agentenplugin bereitgestellt werden. Wie Sie das erledigen können, lesen Sie im entsprechenden Kapitel.
Dem Agentenplugin mk-oracle muss Zugriff auf Ihre Oracle-Instanzen beziehungsweise -Datenbanken gewährt werden. Dafür haben Sie zwei verschiedene Möglichkeiten:
- Sie können auf dem Host einen Benutzer samt Passwort erzeugen, der ausschließlich für das Monitoring durch Checkmk verwendet wird. Diesen Weg erklären wir im Kapitel Datenbankbenutzer erstellen.
- Alternativ können Sie die Oracle-Wallet nutzen.

2.1. Oracle Instant Client (OIC) bereitstellen

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

Sie können OIC exklusiv für das Agentenplugin installieren. Dies ist die von uns empfohlene Methode, die wir hier beschreiben.
Alternativ können Sie OIC global auf dem Host installieren.
Falls OIC bereits auf dem Host installiert ist, und Sie diese Installation für die Überwachung durch Checkmk verwenden wollen, können Sie dem Agentenplugin mit einem Eintrag in der Konfiguration mitteilen, wo OIC zu finden ist. Link zu der Option in der Regel.

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

Linux

Windows

Linux

Für ein Linux x86-64 nehmen Sie beispielsweise das Basic Light Package (ZIP).

Prüfen Sie, wie das Plugin-Verzeichnis des Checkmk-Agenten auf Ihren Host lautet:

root@linux# plugindir=$(cmk-agent-ctl dump | grep "^PluginsDirectory" | head -1 | awk '{print $2}')
root@linux# echo "$plugindir"
/usr/lib/check_mk_agent/plugins

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Entpacken Sie die Archivdatei in eben jenes Plugin-Verzeichnis:

root@linux# mkdir -p "${plugindir}/mk-oracle"
root@linux# unzip -j instantclient-basiclite-linux.x64-23.26.2.0.0.zip -d "${plugindir}/mk-oracle"

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Da einige Zip-Dateien von Oracle Linux-User-IDs enthalten und damit möglicherweise ein vorhandener Nutzer mit dieser ID Eigentümer der Client-Bibliothek würde, ändern Sie sicherheitshalber Eigentümer und Zugriffsrechte:

root@linux# chown -R root:root "${plugindir}/mk-oracle"
root@linux# chmod -R go-w "${plugindir}/mk-oracle"

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Windows

Für Windows nehmen Sie beispielsweise das Basic Light Package (ZIP).

Entpacken Sie die das Archiv in das Unterverzeichnis packages\mk-oracle des Plugin-Verzeichnisses.

Standardmäßig lautet dieses auf einem Windows-Host lautet %PROGRAMDATA%\checkmk\agent\plugins\packages\mk-oracle.

OIC global installieren

Auf einem Linux-Host können Sie den Oracle Instant Client alternativ auch beispielsweise auch in /opt/ installieren.

OMD[central]:~$ sudo unzip -j instantclient-basiclite-linux.x64-23.26.2.0.0.zip -d /opt/checkmk/oracle-instant-client

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Auf einem Windows-Host können Sie den Oracle Instant Client auch in ein beliebiges Verzeichnis installieren. Dieses Verzeichnis müssen dann in der Umgebungsvariable PATH von Windows angeben.

2.2. Zugriffsrechte für das Agentenplugin gewähren

Dem Agentenplugin mk-oracle 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.

Einfacher Datenbank-Benutzer

Datenbank-Benutzer (Multi-tenant)

Wallet

Einfacher Datenbank-Benutzer

Wenn Sie für das Monitoring einen regulären Benutzer einrichten wollen, dann empfehlen wir, eben diesen Benutzer ausschließlich für Checkmk zu verwenden.

Verbinden Sie sich als erstes mit Ihren Oracle-Host und wechseln Sie zu dem Benutzer, unter dessen Kennung die Oracle Datenbank läuft. Meist ist dies oracle:

root@linux# su - oracle

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Hinterlegen Sie die Instanz, mit der sich sqlplus verbinden soll in einer Umgebungsvariablen:

oracle@linux$ export ORACLE_SID=MYINST1

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Starten Sie sqlplus. Geben Sie dabei an, mit welcher Rolle sqlplus starten soll.

oracle@linux$ sqlplus / as sysdba

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Erzeugen Sie jetzt einen Benutzer, welcher ausschließlich für die Überwachung von Oracle verwendet werden soll. Die Berechtigungen gelten für alle existierenden und zukünftigen Datenbanken.

sqlplus> create user checkmk identified by myPassword;
sqlplus> alter user checkmk set container_data=all container=current;
sqlplus> grant select_catalog_role to checkmk container=all;
sqlplus> grant create session to checkmk container=all;
sqlplus> exit

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Datenbank-Benutzer (Multi-tenant)

Wenn Sie für das Monitoring einen Benutzer einrichten wollen, dann empfehlen wir, eben diesen Benutzer ausschließlich für Checkmk zu verwenden.

Verbinden Sie sich als erstes mit Ihren Oracle-Host und wechseln Sie zu dem Benutzer, unter dessen Kennung die Oracle Datenbank läuft. Meist ist dies oracle:

root@linux# su - oracle

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Hinterlegen Sie die Instanz, mit der sich sqlplus verbinden soll in einer Umgebungsvariablen:

oracle@linux$ export ORACLE_SID=MYINST1

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Starten Sie sqlplus. Geben Sie dabei an, mit welcher Rolle sqlplus starten soll.

oracle@linux$ sqlplus / as sysdba

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Erzeugen Sie jetzt einen Benutzer, welcher ausschließlich für die Überwachung von Oracle verwendet werden soll. Das Präfix C## sorgt dafür, dass der Nutzer alle Datenbanken der Instanz sehen kann. Die Berechtigungen gelten für alle existierenden und zukünftigen Datenbanken.

sqlplus> create user C##checkmk identified by myPassword;
sqlplus> alter user C##checkmk set container_data=all container=current;
sqlplus> grant select_catalog_role to C##checkmk container=all;
sqlplus> grant create session to C##checkmk container=all;
sqlplus> exit

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Wallet

Alternativ dazu, den Benutzer direkt und mit Passwort in einer Konfigurationsdatei anzugeben, können Sie auch das Oracle-Wallet nutzen. Das hat den Vorteil, dass Sie nicht mehr die Zugangsdaten unverschlüsselt sowohl auf dem Checkmk-Server als auch auf dem Oracle-Host ablegen müssen. Denn selbst wenn Sie die Rechte der Konfigurationsdatei auf dem Oracle-Host entsprechend angepasst haben, haben die Zugangsdaten dennoch den Server verlassen und befinden sich auf dem Checkmk-Server, sofern Sie die Agentenbäckerei nutzen.

Das Oracle-Wallet wiederum legt die Zugangsdaten verschlüsselt auf dem zu überwachenden Host ab, sodass sie benutzt werden können, aber keine Login-Daten explizit bekannt gemacht werden müssen. Checkmk kann dieses Wallet nutzen, sodass die Zugangsdaten prinzipiell nur dem Datenbankadministrator (DBA) bekannt sein müssen. Dazu legen Sie — oder der DBA — ein Wallet auf dem entsprechenden Server an und legen diese im Konfigurationsverzeichnis in einer Datei namens oracle_wallet ab.

root@linux# mkstore -wrl /etc/check_mk/oracle_wallet -create

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Auf diese Datei wird das Agentenplugin später immer dann zugreifen, wenn eine Verbindung zu einer Instanz hergestellt werden soll. Damit die nötigen Benutzerdaten auch gefunden werden, müssen Sie diese einmalig in das Wallet eintragen. In dem folgenden Beispiel fügen Sie also den Benutzer checkmk für die Instanz MYINST1 hinzu:

root@linux# mkstore -wrl /etc/check_mk/oracle_wallet -createCredential MYINST1 checkmk myPassword

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Damit das Agentenplugin weiß, wo es nach dem Wallet suchen muss, muss es zwei Dateien finden. Die erste Datei ist sqlnet.ora in welcher hinterlegt wird, wo das Wallet zu finden ist. Die zweite Datei — tnsnames.ora — bestimmt die Adresse der Instanz, sodass diese auch über ihren Alias angesprochen werden kann. Damit das Agentenplugin diese Dateien findet, können Sie den Pfad unter Linux, Solaris und AIX über die Umgebungsvariable TNS_ADMIN setzen. Das ist vor allem dann von Vorteil, wenn die Dateien bereits existieren. Alternativ können Sie sie auch explizit anlegen. Unter Windows ist es sogar erforderlich, dass Sie diese manuell bestimmen.

Legen Sie zunächst die Datei sqlnet.ora an. In dieser Datei sucht das Agentenplugin alternativ nach den Zugangsdaten, sodass hier also der korrekte Pfad zu der eben erstellten Wallet-Datei angegeben werden muss. Achten Sie dabei darauf, dass Sie den Parameter SQLNET.WALLET_OVERRIDE auf TRUE setzen:

/etc/check_mk/sqlnet.ora

LOG_DIRECTORY_CLIENT = /var/log/check_mk/oracle_client
DIAG_ADR_ENABLED = OFF

SQLNET.WALLET_OVERRIDE = TRUE
WALLET_LOCATION =
 (SOURCE=
   (METHOD = FILE)
   (METHOD_DATA = (DIRECTORY=/etc/check_mk/oracle_wallet))
 )

Jetzt weiß das Plugin, welche Zugangsdaten benutzt werden sollen. Damit es auch die korrekte Adresse ansteuert, legen Sie als Datei die tnsnames.ora an. Die genaue Syntax können Sie der Oracle-Dokumentation entnehmen, aber als Beispiel könnte die Datei so aussehen:

/etc/check_mk/tnsnames.ora

MYINST1
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = MYINST1_ALIAS)
    )
  )

Sie können dem Wallet natürlich zu einem späteren Zeitpunkt weitere Zugangsdaten hinzufügen. Lediglich die Datei tnsnames.ora muss dann gegebenenfalls erweitert werden.

Zum Abschluss ändern Sie die Berechtigungen der in diesem Abschnitt manuell erstellten Dateien und Verzeichnisse, damit die Zugriffsrechte bei der Ausführung richtig gesetzt sind. Das Agentenplugin, das als root ausgeführt wird, wechselt zum Eigentümer der Oracle-Binärdateien (z.B. $ORACLE_HOME/bin/sqlplus), bevor es diese ausführt. Zumindest die Gruppe des Eigentümers der Oracle-Binärdateien benötigt daher lesenden Zugriff auf die manuell erstellten Dateien in /etc/check_mk/. Im folgenden Beispiel nehmen wir an, dass es sich bei der Gruppe um oinstall handelt.

Die folgenden Befehle ändern die Gruppe zu oinstall:

root@linux# chgrp oinstall /etc/check_mk/sqlnet.ora /etc/check_mk/tnsnames.ora
root@linux# chgrp -R oinstall /etc/check_mk/oracle_wallet

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Diese Befehle stellen dann sicher, dass die Gruppe das Verzeichnis oracle_wallet samt Inhalt lesen kann:

root@linux# chmod g+x /etc/check_mk/oracle_wallet
root@linux# chmod -R g+r /etc/check_mk/oracle_wallet

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Anschließend sollten die Berechtigungen etwa wie folgt aussehen:

root@linux# tree -ugpR /etc/check_mk
[drwxr-xr-x root     root    ]  /etc/check_mk
├── [drwxr-x--- root   oinstall ]  oracle_wallet
│   └── [-rw-r----- root   oinstall ]  cwallet.sso
│   └── [-rw-r----- root   oinstall ]  cwallet.sso.lck
│   └── [-rw-r----- root   oinstall ]  ewallet.p12
│   └── [-rw-r----- root   oinstall ]  ewallet.p12.lck
├── [-rw-r--r-- root   oinstall ]  sqlnet.ora
├── [-rw-r--r-- root   oinstall ]  tnsnames.ora

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Die Befehlsausgabe zeigt nur Dateien und Verzeichnisse, die für die Konfiguration der Oracle Wallet relevant sind.

3. Konfiguration des Agentenplugins

Nachdem Sie auf dem Oracle-Host die Voraussetzungen für das Monitoring mit Checkmk geschaffen haben, müssen Sie nun eine Konfiguration für das Agentenplugin erstellen.

Nutzer unserer kommerziellen Editionen und der Agentenbäckerei finden im Kapitel Konfiguration für das Agentenplugin per Regel erstellen was zu tun ist.
Falls Sie Ihre Oracle-Instanzen mit Checkmk Community überwachen möchten oder die Konfiguration aus anderen Gründen manuell vornehmen möchten, lesen Sie jetzt bitte das Kapitel Überwachung von Oracle manuell einrichten.

3.1. Per Agentenregel und Agentenbäckerei

Nutzer einer kommerziellen Edition von Checkmk können das Agentenplugin bequem über die Agentenregel Unified Oracle Plugin (Experimental) konfigurieren. In diesem Kapitel konzentrieren wir uns dabei auf die Bereiche Authentifizierung, Verbindungsoptionen und Datenbank spezifische Anmeldedaten. Alle weiteren Optionen, die der Regelsatz Unified Oracle Plugin (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 Unified Oracle Plugin (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.

Authentifizierungstyp einstellen

Je nachdem für welchen Weg Sie sich im Kapitel Voraussetzungen auf dem Oracle-Host schaffen entschieden haben, wählen Sie unter Authentication type die passende Option aus und tragen die zugehörigen Daten ein.

Optional haben Sie über Role die Möglichkeit anzugeben, welche Rolle das Agentenplugin bei der Authentifizierung annehmen soll. Und wenn Sie für die ASM Authentication ein anderer Nutzername verwendet werden soll, können Sie auch das hier eintragen.

Verbindungsoptionen konfigurieren

Im nächsten Block können Sie Details zu den Verbindungsoptionen konfigurieren. Neben dem Host-Namen und dem Port Ihrer Oracle-Instanz, können Sie auch den TNS_ADMIN directory path angeben. Wenn Sie hier nichts eintragen, geht mk-oracle davon aus, das es sich Dabei um das Konfigurationsverzeichnis des Agenten handelt. Mit der Option Oracle Local Registry path können Sie dem Agentenplugin mitteilen, wo die lokalen Registrierungsdateien Ihres Oracle-Cluster liegen. Die Instanzerkennung des Agentenplugins wird dann diese Informationen heranziehen, und die darin beschriebenen Instanzen überwachen.

Datenbankspezifische Anmeldedaten

Gerade in größeren Umgebungen wird es mitunter nötig sein, dass verschiedene Instanzen Ihrer Oracle-Umgebung mit unterschiedlichen Zugangsdaten und Verbindungsoptionen ausgestattet sind. Dafür ist die Sektion Databases to monitor da. Hier können Sie instanzspezifische Anmeldedaten und Verbindungsoptionen angeben. Ihre Angaben unter Default settings beziehen sich dann nur noch auf die Instanzen, welche Sie unter Databases to monitor nicht explizit angegeben haben.

Weitere Konfigurationsmöglichkeiten

Alle weiteren Optionen der Regel Unified Oracle Plugin (Experimental) werden im Kapitel Referenzen beschrieben.

Bedingungen einstellen

Denken Sie zum Abschluss daran Ihre neue Regel Unified Oracle plug-in über die Conditions auf Ihre Oracle-Hosts einzuschränken.

Speichern Sie nun die Regel, backen Sie das neue Agentenpaket und installieren Sie dieses auf dem Oracle-Host. Übertragen Sie das neue Agentenpaket nun auch Ihren Oracle-Host und installieren Sie es. Danach können Sie in Checkmk die Service-Erkennung auf Ihrem Oracle-Host durchführen.

3.2. Manuelle Konfiguration

Dieses Kapitel richtet sich an all diejenigen, die CRE 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.

Voraussetzungen für die manuelle Einrichtung

Bevor Sie mit der manuellen Einrichtung starten können, prüfen Sie, ob die folgenden beiden Voraussetzungen erfüllt sind:

Auf dem Oracle-Host muss der Checkmk-Agent bereits installiert und registriert sein. Wie Sie das bewerkstelligen, erklären wir bereits in den Artikeln Linux überwachen bzw. Windows überwachen.
Außerdem müssen Sie bereits dafür gesorgt haben, dass der Oracle Instant Client auf dem Host verfügbar ist.

Sobald alle Voraussetzungen erfüllt sind, können Sie sich daran machen, das Agentenplugin zu installieren.

Agentenplugin installieren

Das Agentenplugin mk-oracle kommt mit zwei Helfern daher, die letzten Endes nur dafür da sind, um mk-oracle selbst im synchronen oder im asynchronen Modus zu starten. Diese beiden Helfer müssen Sie ebenfalls auf dem Host installieren, was wir zuerst zeigen.

Linux

Windows

Linux

Zusätzlich zum Agentenplugin mk-oracle benötigen Sie noch die Dateien oracle_unified_sync und oracle_unified_async. Sie finde alle drei Dateien in CRE Checkmk Community über Setup > Agents > Other operating systems > Plug-ins. In den kommerziellen Editionen gelangen Sie im Setup-Menü über Agents > Windows, Linux, Solaris, AIX zunächst in die Agentenbäckerei, wo Sie die gebackenen Pakete finden. Von dort aus kommen Sie mit dem Menüeintrag Related > Other operating systems zur Liste der Agentendateien.

Wenn Sie Dateisystemzugriff haben, finden Sie alle benötigten Dateien im Verzeichnis ~/version/lib/python3/cmk/plugins/oracle/agents/ Ihrer Checkmk-Instanz.

Übertragen Sie die drei Dateien auf beliebigem Weg auf den Oracle-Host. Wenn auf dem Host wget zur Verfügung steht, könnten Sie so vorgehen:

root@linux# wget -P /tmp http://mycmkserver/mysite/check_mk/agents/mk-oracle
root@linux# wget -P /tmp http://mycmkserver/mysite/check_mk/agents/oracle_unified_sync
root@linux# wget -P /tmp http://mycmkserver/mysite/check_mk/agents/oracle_unified_async

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Hier werden die drei Dateien in das Verzeichnis /tmp auf dem Oracle-Host heruntergeladen. Von diesem Speicherort gehen die weiteren Schritte jetzt auch aus.

Installieren Sie das Plugin auf dem Oracle-Host in das Plugin-Verzeichnis des Agenten (im Standardfall /usr/lib/check_mk_agent/plugins). Wie das Plugin-Verzeichnis auf Ihrem Host lautet, können Sie in der Ausgabe des Checkmk-Agenten ablesen. Im folgenden Befehl wird das Plugin-Verzeichnis in die Variable MK_LIBDIR geschrieben. Die weiteren Befehle nutzen dann auch $MK_LIBDIR. Sollte der nächste Befehl bei Ihnen keinen sinnvollen Output liefern, weil beispielsweise awk nicht zur Verfügung steht, dann schreiben Sie das tatsächliche Plugin-Verzeichnis einfach selber in MK_LIBDIR rein, damit Sie danach wieder mit den angegebenen Befehlen arbeiten können.

# Pfad dynamisch ermitteln und in Variable speichern
root@linux# export MK_LIBDIR=$(cmk-agent-ctl dump | awk '/^PluginsDirectory:/ {print $2; exit}')
# Testen, ob es geklappt hat
root@linux# echo $MK_LIBDIR
/usr/lib/check_mk_agent/plugins

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Jetzt liegen die notwendigen Dateien auf dem Oracle-Host und in der Variable $MK_LIBDIR steht, wo sich das Plugin-Verzeichnis befindet. Damit schließen Sie die Installation von mk-oracle auf dem Host ab:

root@linux# install -D -m 755 /tmp/mk-oracle "$MK_LIBDIR/packages/mk-oracle/mk-oracle"
root@linux# install -m 755 /tmp/oracle_unified_sync "$MK_LIBDIR/oracle_unified_sync"
root@linux# install -D -m 755 /tmp/oracle_unified_sync "$MK_LIBDIR/600/oracle_unified_async"

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

In obigem Beispiel wurde die Datei oracle_unified_async in das Unterverzeichnis 600 installiert. Das bedeutet, dass alle Sektionen, die Sie später für die asynchrone Abholung einrichten, ein maximales Cache-Alter von 600 Sekunden bekommen. Passen Sie die Zahl 600 also bitte Ihren Bedürfnissen an.

Windows

Zusätzlich zum Agentenplugin mk-oracle benötigen Sie noch die Dateien oracle_unified_sync.ps1 und oracle_unified_async.ps1. In den kommerziellen Editionen gelangen Sie im Setup-Menü über Agents > Windows, Linux, Solaris, AIX zunächst in die Agentenbäckerei, wo Sie die gebackenen Pakete finden. Von dort aus kommen Sie mit dem Menüeintrag Related > Other operating systems zur Liste der Agentendateien.

Die eigentliche Installation des Agentenplugins läuft etwas anders ab, als Sie es womöglich von anderen Plugins kennen.

Die mitgelieferten Plugins für Windows finden Sie alle auf dem überwachten Host im Installationsverzeichnis des Agenten unter C:\Program Files (x86)\checkmk\service\plugins. Sie werden dort abgelegt, damit sie auch direkt zur Verfügung stehen. Alternativ liegen die Plugins auch auf dem Checkmk-Server unter ~/share/check_mk/agents/windows/plugins, die beiden Hilfsprogramme unter ~/version/lib/python3/cmk/plugins/oracle/agents/.

Kopieren Sie die drei Dateien von dort aus in die folgenden Verzeichnisse:

Dateiname Zielverzeichnis

Dateiname	Zielverzeichnis
`mk-oracle`	`%ProgramData%\checkmk\agent\plugins\packages\mk-oracle\`
`oracle_unified_sync.ps1`	`%ProgramData%\checkmk\agent\plugins\`
`oracle_unified_async.ps1`	`%ProgramData%\checkmk\agent\plugins\`

mk-oracle

%ProgramData%\checkmk\agent\plugins\packages\mk-oracle\

oracle_unified_sync.ps1

%ProgramData%\checkmk\agent\plugins\

oracle_unified_async.ps1

%ProgramData%\checkmk\agent\plugins\

Sobald Sie Dateien an Ort und Stelle sind, müssen Sie der Datei, die für die Ausführung der asynchronen Sektionen zuständig ist – also oracle_unified_async.ps1 –, noch eine entsprechende Konfiguration mitgeben.

Wie das geht erklären wir im Kapitel Ausführung eines speziellen Plugins anpassen im Handbuchartikel zur Überwachung von Windows.

Die Installation des gesamten Agentenplugins ist hiermit abgeschlossen. Damit das Agentenplugin jetzt auch versteht, was es tun soll, müssen Sie noch eine Konfiguration für das Plugin erstellen.

Konfiguration für Agentenplugin erstellen

Im Konfigurationsverzeichnis des Checkmk-Agenten müssen Sie jetzt eine Datei mit dem Namen mk-oracle.yml anlegen.

Linux

Windows

Linux

Wie das Konfigurationsverzeichnis auf Ihrem Host lautet finden Sie leicht mit dem folgenden Befehl heraus:

OMD[central]:~$ sudo sudo cmk-agent-ctl dump | grep "^AgentDirectory" | head -1
AgentDirectory: /etc/check_mk

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Legen Sie in diesem Verzeichnis mit Ihrem bevorzugten Editor die Datei mk-oracle.yml an.

Windows

Legen Sie im Verzeichnis %PROGRAMDATA%\checkmk\agent\config mit Ihrem bevorzugten Editor die Datei mk-oracle.yml an.

Um nicht bei Null starten zu müssen, gibt es im Kapitel Beispielkonfigurationen etwas, womit Sie erstmal starten können.

Eine ganz einfache Konfiguration für eine frisch installierte Oracle AI Database Free, die Sie womöglich zu Testzwecken aufgesetzt haben, könnte etwa so aussehen:

mk-oracle.yml

---
oracle:
  main:
    authentication:
      password: mypassword
      type: standard
      username: mymonitoringuser
    cache_age: 600
    connection:
      hostname: localhost
    custom_metrics_cache_age: 600
    instances: []

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Mit diesem Beispiel könnten Sie also erstmal starten. Im Referenzteil dieses Artikel erklären wir alle weiteren Konfigurationsoptionen aus denen Sie sich bedienen können.

Sobald das Agentenplugin dann auch über eine Konfiguration verfügt, können Sie bereits auf dem Checkmk-Server eine Serviceerkennung auf dem jeweiligen Host durchführen. Damit ist die grundlegende Einrichtung des Monitoring abgeschlossen. Wenn Ihnen Sie Services, die das Agentenplugin von selbst mitbringt nicht genügen, können Sie gleich mit den Benutzerdefinierte SQL-Abfragen weitermachen.

4. Benutzerdefinierte SQL-Abfragen (Custom SQLs) einrichten

Benutzerdefinierte SQL-Abfragen (Custom SQLs) können nicht über die Regel Unified Oracle Plugin (Beta) definiert werden. Sie müssen die notwendige Konfiguration direkt auf dem Host vornehmen, von dem aus Sie Ihre Oracle-Instanzen und -Datenbanken überwachen.

4.1. Warum benutzerdefinierte SQL-Abfragen?

Checkmk bietet mit dem Agentenplugin bereits eine große Menge an SQL-Abfragen, mit denen Sie Ihre Datenbankinstanzen ü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 die Überwachung 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:

Entweder schreiben Sie die Abfragen direkt in die Konfigurationsdatei mk-oracle.yml.
Oder Sie geben in der Konfigurationsdatei stattdessen an, wo das Agentenplugin Dateien finden kann, in denen Ihre benutzerdefinierte SQL-Abfragen gespeichert sind.

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.

4.2. Einfache benutzerdefinierte SQL-Abfragen einrichten

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.

oracle@linux$ sqlplus / as sysdba

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

sqlplus> SELECT 'details:Free memory: ' || ROUND(SUM(bytes)/1024/1024, 2) || ' MB' FROM v$sgastat WHERE name = 'free memory';
'DETAILS:FREEMEMORY:'||ROUND(SUM(BYTES)/1024/1024,2)||'MB'
----------------------------------------------------------------
details:Free memory: 230,86 MB

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

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:

mk-oracle.yml

---
oracle:
  main:
    connection:
      hostname: localhost
    authentication:
      username: mymonitoringuser
      password: mypassword
      type: standard
    custom_metrics:
      - My service:
          sql: "SELECT 'details:Free memory: ' || ROUND(SUM(bytes)/1024/1024, 2) || ' MB' FROM v$sgastat WHERE name = 'free memory'"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Unser Beispiel zeigt drei Dinge:

Um benutzerdefinierte SQL-Abfragen einzufügen, benötigen Sie immer einen Schlüssel namens custom_metrics.
Darauf folgt eine Liste (hier: My service). Eine solche Liste beginnt in YAML mit einem -. Der Name dieser Liste wird in Checkmk Teil des Service-Namens und kann frei gewählt werden.
Dann kommt die Zeile, die die Abfrage enthält. Sie muss mit sql: beginnen und die Abfrage selbst muss in doppelten Anführungsstrichen stehen. Achten Sie hier auch darauf, dass die Abfrage nicht mit einem Semikolon abgeschlossen werden darf.

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 Serviceerkennung durch. Sie erhalten dann diesen neuen Service:

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

Der Name beginnt immer mit ORA.
Es folgt die SID (hier: FREE).
Das anschließende SQL ist der Hinweis darauf, dass dieser Service durch eine benutzerdefinierte SQL-Abfrage entstanden ist.
Darauf folgt der String, den Sie in der Konfigurationsdatei frei wählen konnten in Großbuchstaben.

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.

4.3. Erweiterte benutzerdefinierte SQL-Abfragen einrichten

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.

mk-oracle.yml

---
oracle:
  main:
    connection:
      hostname: localhost
    authentication:
      username: mymonitoringuser
      password: mypassword
      type: standard
    custom_metrics:
      - My advanced service:
          path: 'myadvancedservice.sql'

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

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.

root@linux# mkdir /etc/check_mk/orasql

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

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.

/etc/check_mk/orasql/myadvancedservice.sql

SELECT 'details:Free memory: ' || REPLACE(ROUND(SUM(bytes) / 1024 / 1024, 2), ',', '.') || ' MB' FROM v$sgastat WHERE name = 'free memory'
UNION ALL
SELECT 'perfdata:free_ram_mb=' || REPLACE(ROUND(SUM(bytes) / 1024 / 1024, 2), ',', '.') FROM v$sgastat WHERE name = 'free memory'
UNION ALL
SELECT 'exit:0' FROM dual

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

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 den Status des Service beeinflussen. In diesem Beispiel wird er fix auf 0 gesetzt, was für den Status 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 Serviceerkennung durchführen, wird der alte Service verschwinden und stattdessen ein neuer, dessen Name auf MY ADVANCED SERVICE endet, gefunden werden.

5. Migration von `mk_oracle` zu `mk-oracle`

5.1. Migration der Konfiguration des Agentenplugins

In Checkmk 2.5.0 hat das neue Agentenplugin mk-oracle eine Fähigkeit, die Nutzern von mk_oracle dabei hilft auf das neue Agentenplugin umzusteigen. Übertragen Sie dazu mk-oracle 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 erwartet.

Das kann dann beispielsweise so aussehen:

root@linux# /usr/lib/check_mk_agent/plugins/packages/mk-oracle/mk-oracle -M /etc/check_mk/mk_oracle.cfg
# --- Converted from /etc/check_mk/mk_oracle.cfg at 2026-06-29 19:00:00 UTC ---
# # Syntax
# # DBUSER='USERNAME:PASSWORD:ROLE:HOST:PORT:TNSALIAS'
# DBUSER='checkmk:myPassword'

 DBUSER_MYINST1='cmk_specific1:myPassword1:SYSDBA:localhost:1521'
# DBUSER_MYINST2='cmk_specific2:myPassword2::localhost::INST2'

 ASMUSER='cmk_asm:myASMPassword:SYSASM'
# --- Known environment variables defined in legacy config ---
# DBUSER_MYINST2 cmk_specific2:myPassword2::localhost::INST2
# ASMUSER cmk_asm:myASMPassword:SYSASM
# DBUSER checkmk:myPassword
# DBUSER_MYINST1 cmk_specific1:myPassword1:SYSDBA:localhost:1521
# --- Unified Config ---
---
oracle:
  main:
    connection:
      hostname: localhost
    authentication:
      username: "checkmk"
      password: "myPassword"
      type: standard
      asm_username: "cmk_asm"
      asm_password: "myASMPassword"
      asm_role: sysasm
    instances:
      - sid: $ORACLE_SID
        alias: $ORACLE_SID
      - sid: MYINST2
        alias: INST2
        connection:
          hostname: localhost
        authentication:
          username: "cmk_specific2"
          password: "myPassword2"
          type: standard
      - sid: MYINST1
        connection:
          hostname: localhost
          port: 1521
        authentication:
          username: "cmk_specific1"
          password: "myPassword1"
          type: standard
          role: sysdba

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Standardmäßig schreibt mk-oracle 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 mit der Option --migrate-output dazu anweisen, den Output direkt in eine Datei zu schreiben.

root@linux# /usr/lib/check_mk_agent/plugins/packages/mk-oracle/mk-oracle \
    -M /etc/check_mk/mk_oracle.cfg \
    --migrate-output /etc/check_mk/mk-oracle.yml

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

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:

Alte Variable… …wird migriert zu:

Alte Variable…	…wird migriert zu:
`DBUSER` (required)	Top-level `connection:` (Host-Name, Port) und `authentication:`, zusätzlich den ersten Eintrag bei `instances:`
`DBUSER_<SID>`	Ein Eintrag `instances:` für jede `SID` mit Einträgen für `connection:` und `authentication:` pro Instanz
`ASMUSER`	`asm_username`, `asm_password`, `asm_role` unterhalb von `authentication:`
`REMOTE_INSTANCE_<ID>`	Ein Eintrag `instances:` pro ID inklusive des `piggyback_host:` (nur Linux/AIX)
`SYNC_SECTIONS` / `ASYNC_SECTIONS`	`sections:` mit Attribut `is_async: false` / `true`
`SYNC_ASM_SECTIONS` / `ASYNC_ASM_SECTIONS`	`sections:` mit Attribut `affinity: "asm"` (`"all"` )
`CACHE_MAXAGE`	`cache_age:`
`SQLS_MAX_CACHE_AGE`	`custom_metrics_cache_age:`
`MAX_TASKS`	`options.threads:` (Nur für Werte ≥ 2, maximal jedoch 8)
`ONLY_SIDS`	`discovery.include:` (mit `detect: true`)
`SKIP_SIDS`, `EXCLUDE_<SID>="ALL"`	`discovery.exclude:` (mit `detect: true`)
`TNS_ADMIN`	`connection.tns_admin:`
`OLRLOC`	`connection.oracle_local_registry:`
`SQLS_SECTIONS` + pro Sektion `SQLS_*`	`custom_metrics:`

DBUSER (required)

Top-level connection: (Host-Name, Port) und authentication:, zusätzlich den ersten Eintrag bei instances:

DBUSER_<SID>

Ein Eintrag instances: für jede SID mit Einträgen für connection: und authentication: pro Instanz

ASMUSER

asm_username, asm_password, asm_role unterhalb von authentication:

REMOTE_INSTANCE_<ID>

Ein Eintrag instances: pro ID inklusive des piggyback_host: (nur Linux/AIX)

SYNC_SECTIONS / ASYNC_SECTIONS

sections: mit Attribut is_async: false / true

SYNC_ASM_SECTIONS / ASYNC_ASM_SECTIONS

sections: mit Attribut affinity: "asm" ("all" )

CACHE_MAXAGE

cache_age:

SQLS_MAX_CACHE_AGE

custom_metrics_cache_age:

MAX_TASKS

options.threads: (Nur für Werte ≥ 2, maximal jedoch 8)

ONLY_SIDS

discovery.include: (mit detect: true)

SKIP_SIDS, EXCLUDE_<SID>="ALL"

discovery.exclude: (mit detect: true)

TNS_ADMIN

connection.tns_admin:

OLRLOC

connection.oracle_local_registry:

SQLS_SECTIONS + pro Sektion SQLS_*

custom_metrics:

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

alte Variable Hinweis zur manuellen Migration

alte Variable	Hinweis zur manuellen Migration
`SQLS_DBUSER`, `SQLS_DBPASSWORD`, `SQLS_DBSYSCONNECT`	Anmeldedaten pro benutzerdefiniertem SQL; verwenden Sie stattdessen instanzspezifische Überschreibungen unterhalb des Schlüssels `authentication:`
`SQLS_PARAMETERS`	Die Übergabe von SQL*Plus-Parametern wird nicht unterstützt.
`EXCLUDE_<SID>="<section> …"`	Ausschluss einzelner Abschnitte pro SID; nur `EXCLUDE_<SID>="ALL"` wird konvertiert
`ORACLE_HOME`, `REMOTE_ORACLE_HOME`	Die OIC-Laufzeitumgebung — gegebenenfalls `use_host_client` angeben.
`ID_BY`	Wählt `SID=` gegenüber `SERVICE_NAME=` in der alten Verbindungskonfiguration aus; verwenden Sie stattdessen die Instanzfelder `sid:` / `service_name:`

SQLS_DBUSER, SQLS_DBPASSWORD, SQLS_DBSYSCONNECT

Anmeldedaten pro benutzerdefiniertem SQL; verwenden Sie stattdessen instanzspezifische Überschreibungen unterhalb des Schlüssels authentication:

SQLS_PARAMETERS

Die Übergabe von SQL*Plus-Parametern wird nicht unterstützt.

EXCLUDE_<SID>="<section> …"

Ausschluss einzelner Abschnitte pro SID; nur EXCLUDE_<SID>="ALL" wird konvertiert

ORACLE_HOME, REMOTE_ORACLE_HOME

Die OIC-Laufzeitumgebung — gegebenenfalls use_host_client angeben.

ID_BY

Wählt SID= gegenüber SERVICE_NAME= in der alten Verbindungskonfiguration aus; verwenden Sie stattdessen die Instanzfelder sid: / service_name:

5.2. Migration von benutzerdefinierten SQL-Abfragen

Das alte Agentenplugin mk_oracle leitet benutzerdefinierte SQL-Abfragen über das Kommandozeilen-Tool sqlplus weiter. Das Plugin mk-oracle 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.

Grundlegende Einschränkungen und Ausführungsmodell

Keine SQL*Plus-Befehle

Befehle wie PROMPT, SET, COLUMN, SPOOL, EXEC/EXECUTE oder VAR/VARIABLE sind Funktionen des Client-Werkzeugs sqlplus und kein Bestandteil der Datenbanksprache SQL. Sie funktionieren unter dem OIC-Treiber nicht.
Keine anonymen PL/SQL-Blöcke: Anonyme Blöcke im Format DECLARE/BEGIN {…} END; können nicht direkt als Skript ausgeführt werden. Es werden ausschließlich reine SQL-Statements unterstützt.

Das Agentenplugin im Migrationsmodus überprüft jede referenzierte SQL-Datei und gibt bei Abweichungen eine Warnung im Terminal sowie in der generierten Konfigurationsdatei aus. Die betroffenen Sektionen werden zwar migriert, müssen jedoch von Ihnen manuell angepasst werden, da die Abfragen sonst zur Laufzeit fehlschlagen werden.

Eigenschaften des neuen Ausführungsmodells

Mehrere Statements: Eine SQL-Datei kann mehrere, durch Semikolon getrennte SQL-Statements auf oberster Ebene enthalten. Diese werden der Reihe nach ausgeführt und ihre Ergebnisse verkettet.
Jedes zurückgegebene Ergebnis muss den Vorgaben zur Formatierung der Ausgabe und Schlüsselwörter entsprechen.

Entfernen von SQL*Plus-Befehlen

Formatierungsbefehle und interaktive Befehle aus sqlplus besitzen kein Äquivalent im Treiber des Oracle Instant Clients. Sie müssen diese daher ersatzlos löschen. Das Agentenplugin gibt jede zurückgegebene Datenzeile direkt aus.

Als Nächstes zeigen wir zuerst eine SQL-Datei, wie sie für für mk_oracle noch funktioniert hat:

SET PAGESIZE 0
SET FEEDBACK OFF
COLUMN details FORMAT A80
PROMPT collecting session count ...
SELECT 'details:' || COUNT(*) || ' sessions' FROM v$session;

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Eine solche Datei müssen Sie für mk-oracle folgendermaßen umschreiben, damit sie mit OIC funktioniert:

SELECT 'details:' || COUNT(*) || ' sessions' FROM v$session

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Umwandlung von PL/SQL-Blöcken in reine SELECT-Abfragen

Anonyme PL/SQL-Blöcke lassen sich in den meisten Fällen durch Standard-SQL-Konstrukte ersetzen: * PL/SQL-Variablen werden zu WITH-Klauseln (Common Table Expressions). * IF/ELSIF-Bedingungen werden durch CASE-Anweisungen ersetzt. * DBMS_OUTPUT.PUT_LINE-Ausgaben werden über UNION ALL oder separate, durch Semikolons getrennte Statements abgebildet.

Im folgenden Beispiel zeigen wir eine SQL-Datei, welche einen PL/SQL-Block enthält:

SET SERVEROUTPUT ON
DECLARE
    invalid_count NUMBER;
BEGIN
    SELECT COUNT(*) INTO invalid_count
      FROM dba_objects
     WHERE status = 'INVALID';
    IF invalid_count > 10 THEN
        DBMS_OUTPUT.PUT_LINE('exit:2');
    ELSE
        DBMS_OUTPUT.PUT_LINE('exit:0');
    END IF;
    DBMS_OUTPUT.PUT_LINE('details:' || invalid_count || ' invalid objects');
END;

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Eine solche Datei müssen Sie für mk-oracle in reines SQL umschreiben. Das könnte beispielsweise so aussehen:

WITH invalid AS (
    SELECT COUNT(*) AS cnt
      FROM dba_objects
     WHERE status = 'INVALID'
)
SELECT 'exit:' || CASE WHEN cnt > 10 THEN '2' ELSE '0' END FROM invalid
UNION ALL
SELECT 'details:' || cnt || ' invalid objects' FROM invalid

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Auslagern komplexer PL/SQL-Logik in Stored Functions

Erfordert die Logik zwingend PL/SQL (z. B. bei Schleifen, komplexer Fehlerbehandlung oder temporären Zuständen), muss die Logik in die Datenbank selbst als Pipelined Function ausgelagert werden.

Dafür müssen Sie die Pipelined Function einmalig in Ihrer Datenbank einrichten:

CREATE OR REPLACE FUNCTION checkmk_invalid_objects
    RETURN sys.odcivarchar2list PIPELINED
AS
    invalid_count NUMBER;
BEGIN
    SELECT COUNT(*) INTO invalid_count
      FROM dba_objects
     WHERE status = 'INVALID';

    -- Beliebige PL/SQL-Logik ist hier erlaubt
    PIPE ROW ('details:' || invalid_count || ' invalid objects');
    PIPE ROW ('perfdata:invalid_objects=' || invalid_count || ';10;100');
    PIPE ROW (CASE WHEN invalid_count > 10 THEN 'exit:2' ELSE 'exit:0' END);
    RETURN;
END;
/

GRANT EXECUTE ON checkmk_invalid_objects TO checkmk;

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Sobald Sie diese Pipelined Function eingerichtet ist, können Sie durch das Agentenplugin aufrufen lassen:

SELECT column_value FROM TABLE(checkmk_invalid_objects)

Befehl(e) in die Zwischenablage kopieren

Befehl(e) erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Liegt die Funktion in einem anderen Schema, muss der Schema-Name vorangestellt werden: TABLE(owner.checkmk_invalid_objects).

6. Dashboards und Ansichten

6.1. Oracle-Dashboards

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.

7. Referenzen

7.1. Benutzerdefinierte SQL-Abfragen (Custom SQLs)

Ü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.

Grundlagen und Konfiguration

Die SQL-Abfragen können Sie entweder direkt als String übergeben oder aus einer Datei laden lassen. In der folgenden Beispielkonfiguration finden Sie eine SQL-Abfrage im globalen Abschnitt, die durch den Schlüssel oracle.main bezeichnet wird. Unterhalb des Schlüssels oracle.main.instances können Sie wiederum einen Schlüssel custom_metrics angeben, der dann natürlich nur für diese Instanzen ausgeführt wird.

mk-oracle.yml

---
oracle:
  main:
    connection:
      hostname: localhost
    authentication:
      username: mymonitoringuser
      password: mypassword
      type: standard
    custom_metrics:
      - product_price: # Item-Name -> wird zum Service "<SID> SQL PRODUCT_PRICE"
          sql: "SELECT 'details:Price OK' FROM dual"
    instances:
      - service_name: FREE
        custom_metrics:
          - last_sessions: # Wird nur gegen diese spezifische Instanz ausgeführt
              sql: "SELECT 'details:per-instance' FROM dual"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Eine Instanz führt immer global definierten und ihre eigenen instanzspezifischen SQL-Abfragen aus.
Teilen sich ein globaler und ein instanzspezifischer Eintrag denselben Item-Namen, hat der Eintrag der Instanz immer Vorrang.

Externe SQL-Dateien (path:)

Anstatt SQL-Abfragen via sql: direkt in die Konfigurationsdatei des Agentenplugins zu schreiben, können Sie mit path: auf externe .sql-Dateien verweisen. Dies funktioniert sowohl für custom_metrics als auch für vordefinierte Sektionen.

Varianten der Pfadangabe

mk-oracle.yml

custom_metrics:
  # 1. Absoluter Pfad zu einer Datei
  - heavy_query:
      path: '/opt/checkmk/sql/heavy_query.sql'

  # 2. Relativer Pfad
  # Wird zuerst in MK_LIBDIR/... und dann in MK_CONFDIR/... gesucht
  - product_price:
      path: 'queries/product_price.sql'

  # 3. Verzeichnispfad
  # Der Dateiname wird automatisch aus dem Item-Namen abgeleitet (hier: "sessions_stats.sql")
  - sessions_stats:
      path: 'queries/'

  # 4. Datei mit Inline-Fallback
  # Kann die Datei nicht aufgelöst werden, wird das Inline-SQL verwendet
  - last_resort:
      path: 'queries/last_resort.sql'
      sql: "SELECT 'details:fallback' FROM dual"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Auflösungsregeln (Resolution rules)

Absolut vs. Relativ: Absolute Pfade werden 1:1 übernommen. Relative Pfade werden zuerst unter MK_LIBDIR/plugins/packages/mk-oracle/orasql/ und anschließend unter MK_CONFDIR/orasql/ gesucht. Existiert die Datei in beiden Verzeichnissen, gewinnt die Datei im MK_LIBDIR.
Datei vs. Verzeichnis: Ein Pfad kann auf eine spezifische Datei (mit oder ohne .sql-Endung) oder auf ein Verzeichnis verweisen. Verweist er auf ein Verzeichnis, wird der Dateiname bei custom_metrics aus dem Item-Namen und bei vordefinierten Sektionen aus dem Sektionsnamen abgeleitet.
Versionsabhängige Varianten: Neben der Basisdatei (<name>.sql) können Sie Oracle-spezifische Varianten im Format <name>@<min_version>.sql bereitstellen (z.B. sessions@12010000.sql). Das Plugin wählt automatisch die Datei mit der höchsten min_version, die kleiner oder gleich der Version der verbundenen Oracle-Instanz ist. Als Versionsformat wird ein 8-stelliges numerisches Format genutzt (MMmmRRSSSS` für Major / Minor / Release / Patch). Beispiel: 12.1.0.2 → 12010002.
Fallback-Kette: Die Reihenfolge zur Ermittlung der SQL-Abfrage lautet: path: > (Inline) sql: > mitgelieferter Standard-Code (nur bei vordefinierten Sektionen). Schlägt path: fehl und es ist kein sql: definiert, generiert die Sektion keine Ausgabe.

SQL-Parameter

Sie können benannte Parameter definieren, die vor der Ausführung in den SQL-Code eingesetzt werden. Jeder Platzhalter im Format ${<name>} wird rein textuell durch den konfigurierten Wert ersetzt. Dies funktioniert sowohl für Inline-SQL als auch für .sql-Dateien.

mk-oracle.yml

---
custom_metrics:
  - test:
      sql: 'SELECT ${parameter_1} FROM dual; SELECT ${parameter_2} FROM dual'
      sql_params:
        parameter_1: 'value_1'
        parameter_2: '${ENV_VAR_1}'

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

${ENV_VAR_1} wird dabei aus den Umgebungsvariablen aufgelöst.
Textuelle Ersetzung (keine Bind-Variablen): Alle Werte werden unverändert in das Statement eingefügt. Sie können somit auch Spalten- oder Tabellennamen übergeben.
Umgebungsvariablen: Ein Wert kann auf Umgebungsvariablen verweisen (Format $VAR oder ${VAR}). Diese werden beim Einlesen der Konfiguration aufgelöst. Ist eine referenzierte Variable nicht gesetzt, wird der Parameter mit einer Warnung übersprungen. Der Platzhalter bleibt im SQL-Code stehen (was i. d. R. zu einem SQL-Fehler führt, statt eine Abfrage mit leeren Werten auszuführen).
Unbenutzte Parameter: Platzhalter ohne passenden Parameterwert werden ignoriert und bleiben im Code unverändert stehen.

Formatierung der Ausgabe und Schlüsselwörter

Das Agentenplugin mk-oracle fügt selbstständig den Sektions-Header <<<<<oracle_sql:sep(58)>>> sowie den Subsektions-Header [[[<SID>|<item>]]] ein. Das auszuführende SQL ist ausschließlich für den Body der Ausgabe verantwortlich. Jede SQL-Abfrage muss Zeilen mit einer einzigen Zeichenfolgen-Spalte (String Column) zurückgeben. Der Wert muss mit einem der folgenden Präfixe beginnen, damit das Checkmk-Plugin diesen korrekt interpretieren kann:

details: Hier können Sie bestimmen, was im Summary des erzeugten Service ausgegeben werden soll. Die Zeile wird mit dem Schlüsselwort und einem Doppelpunkt eingeleitet. Der Rest der Zeile ergibt die Ausgabe.
perfdata: Metriken werden mit diesem Schlüsselwort übergeben. Innerhalb einer Zeile können Sie beliebig viele Metriken — getrennt durch ein Leerzeichen — erzeugen. Sie können die Ausgabe der Metriken auch über mehrere Zeilen verteilen. Beginnen Sie dabei einfach immer mit dem Schlüsselwort perfdata:.
long: Wenn der Service eine lange Ausgabe für das Feld Details haben soll, können Sie diese hier angeben. Auch dieses Schlüsselwort können Sie mehrmals verwenden, um mehrere Zeilen in den Details zu erzeugen.
exit: Soll die Ausgabe in einem bestimmten Status resultieren, können Sie diesen hier bestimmen. Es stehen Ihnen dabei die bekannten Zuordnungen 0, 1, 2, 3 für die Status OK, WARN, CRIT, UNKNOWN zur Verfügung.

7.2. Konfigurationsoptionen

Im diesem Kapitel erklären wir alle Optionen, die zur Konfiguration des Agentenplugins existieren. Egal ob Sie das Agentenplugin über den Regelsatz Unified Oracle Plugin (Beta) 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.

Additional Options > Maximum connections

Maximale Anzahl der zu öffnenden Datenbankverbindungen.

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    options:
      max_connections: <int>

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Additional Options > Maximum queries

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

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    options:
      max_queries: <int>

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Additional Options > Ignore database name

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    options:
      IGNORE_DB_NAME: "0|1"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Additional Options > Oracle Instant Client options

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    options:
      use_host_client: "auto|never"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Authentication > Authentication type > Oracle Wallet

Oracle Wallet bietet eine sichere Möglichkeit, sich bei Oracle-Datenbanken zu authentifizieren, ohne Passwörter im Klartext in Konfigurationsdateien zu speichern.

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    authentication:
      type: wallet

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Authentication > Type

Hier können Sie zwischen standard und wallet wählen. Wählen Sie wallet sind keine weiteren Einstellungen an dieser Stelle nötig. standard steht an dieser Stelle für die Authentifizierung per Benutzername und Passwort. Die Angabe von username und password ist dann auch zwingend notwendig.

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    authentication:
      type: "standard|wallet"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Authentication > Authentication type > User & password

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    authentication:
      username: 'myuser'
      password: 'mypassword'
      type: 'standard'

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Authentication > Role

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

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    authentication:
      username: 'myuser'
      password: 'mypassword'
      type: 'standard'
      role: "sysdba|sysoper|sysasm|szsbackup|sysdg|syskm"

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Connection options

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.

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    connection:
       hostname: 'myhostname' # optional, Standard: 'localhost'
       port: 1521 # optional, default: 1521
       timeout: 5 # optional, default: 5 (Sekunden)
       tns_admin: '/path/to/oracle/config/files/' # optional, Standard: MK_CONFDIR
       oracle_local_registry: '/etc/oracle/olr.loc' # optional, Pfad zur Oracle Local Registry

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Cache age

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

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    cache_age: <int> # Standard: 600 (Sekunden)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Custom Metrics cache age

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    custom_metrics_cache_age: <int> # Standard: 600 (Sekunden)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Instance discovery

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

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    discovery:
      detect: yes # So schalten Sie die automatische Instanzerkennung ein
      include: ['PROD', 'DEV'] # optional, es werden nur die hier angegebenen Instanzen überwacht
      exclude: ['TEST'] # optional, die hier angegebenen Instanzen werden ignoriert

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Sections — data to collect

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.

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    sections:
    - instance:
        is_async: false
    - asm_instance:
        is_async: false
    - asm_diskgroup:
        is_async: true
    - dataguard_stats:
        is_async: false
    - locks:
        is_async: false
    - logswitches:
        is_async: false
    - longactivesessions:
        is_async: false
    - performance:
        is_async: false
    - processes:
        is_async: false
    - recovery_area:
        is_async: false
    - recovery_status:
        is_async: false
    - sessions:
        is_async: false
    - systemparameter:
        is_async: false
    - undostat:
        is_async: false
    - iostats:
        is_async: true
    - jobs:
        is_async: true
    - resumable:
        is_async: true
    - rman:
        is_async: true
    - tablespaces:
        is_async: true

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Databases to monitor

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.

Konfigurationsdatei (Beispiel)

mk-oracle.yml

---
oracle:
  main:
    instances:
      - service_name: MYSERVICE
      - sid: MYSID
      - alias: MYALIAS

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

7.3. Beispielkonfigurationen

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

Minimale Konfiguration

mk-oracle.yml

---
oracle:
  main:
    authentication:
      password: mypassword
      type: standard
      username: mymonitoringuser
    cache_age: 600
    connection:
      hostname: localhost
    custom_metrics_cache_age: 600
    instances: []

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

(Fast) vollständiges Beispiel

Seit der Erstellung dieses Beispiels sind noch Optionen hinzugekommen. Das Beispiel wird demnächst ergänzt.

mk-oracle.yml

system:
  logging:
    level: 'warn'
    max_size: 1000000
    max_count: 5

oracle:
  main:
    options:
      max_connections: 6
      use_host_client: never
      IGNORE_DB_NAME: 0
    connection:
      hostname: 'localhost'
      port: 1521
      timeout: 5
      tns_admin: '/etc/check_mk'
    authentication:
      username: 'mymonitoringuser'
      password: 'mypassword'
      role: 'sysdba'
      type: 'standard'
    discovery:
      detect: yes
      include: ['PROD', 'DEV']
      exclude: ['TEST']
    instances:
      - service_name: 'ORCL'
        sid: 'ORCL'
      - alias: 'REMOTE_DB'
    sections:
      - instance:
          affinity: 'db'
      - tablespaces:
          is_async: yes
      - performance:
      - sessions:
    cache_age: 600
    custom_metrics_cache_age: 600
    piggyback_host: 'mypiggybackhost'

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Letzte Änderung: Fri, 14 Aug 2026 08:56:08 GMT via Commit d6dd0579f

Auf dieser Seite

1. Einleitung
- 1.1. Überblick über diesen Artikel
- 1.2. Wie funktioniert das Oracle-Monitoring mit Checkmk?
2. Voraussetzungen auf dem Oracle-Host schaffen
- 2.1. Oracle Instant Client (OIC) bereitstellen
- 2.2. Zugriffsrechte für das Agentenplugin gewähren
3. Konfiguration des Agentenplugins
- 3.1. Per Agentenregel und Agentenbäckerei
- 3.2. Manuelle Konfiguration
4. Benutzerdefinierte SQL-Abfragen (Custom SQLs) einrichten
5. Migration von mk_oracle zu mk-oracle
- 5.1. Migration der Konfiguration des Agentenplugins
- 5.2. Migration von benutzerdefinierten SQL-Abfragen
6. Dashboards und Ansichten
- 6.1. Oracle-Dashboards
7. Referenzen

Oracle-Datenbanken überwachen

1. Einleitung

1.1. Überblick über diesen Artikel

1.2. Wie funktioniert das Oracle-Monitoring mit Checkmk?

2. Voraussetzungen auf dem Oracle-Host schaffen

2.1. Oracle Instant Client (OIC) bereitstellen

2.2. Zugriffsrechte für das Agentenplugin gewähren

3. Konfiguration des Agentenplugins

3.1. Per Agentenregel und Agentenbäckerei

Authentifizierungstyp einstellen

Verbindungsoptionen konfigurieren

Datenbankspezifische Anmeldedaten

Weitere Konfigurationsmöglichkeiten

Bedingungen einstellen

3.2. Manuelle Konfiguration

Voraussetzungen für die manuelle Einrichtung

Agentenplugin installieren

Konfiguration für Agentenplugin erstellen

4. Benutzerdefinierte SQL-Abfragen (Custom SQLs) einrichten

4.1. Warum benutzerdefinierte SQL-Abfragen?

4.2. Einfache benutzerdefinierte SQL-Abfragen einrichten

4.3. Erweiterte benutzerdefinierte SQL-Abfragen einrichten

5. Migration von mk_oracle zu mk-oracle

5.1. Migration der Konfiguration des Agentenplugins

5.2. Migration von benutzerdefinierten SQL-Abfragen

Grundlegende Einschränkungen und Ausführungsmodell

Keine SQL*Plus-Befehle

Eigenschaften des neuen Ausführungsmodells

Entfernen von SQL*Plus-Befehlen

Umwandlung von PL/SQL-Blöcken in reine SELECT-Abfragen

Auslagern komplexer PL/SQL-Logik in Stored Functions

6. Dashboards und Ansichten

6.1. Oracle-Dashboards

7. Referenzen

7.1. Benutzerdefinierte SQL-Abfragen (Custom SQLs)

Grundlagen und Konfiguration

Externe SQL-Dateien (path:)

Varianten der Pfadangabe

Auflösungsregeln (Resolution rules)

SQL-Parameter

Formatierung der Ausgabe und Schlüsselwörter

7.2. Konfigurationsoptionen

Additional Options > Maximum connections

Additional Options > Maximum queries

Additional Options > Ignore database name

Additional Options > Oracle Instant Client options

Authentication > Authentication type > Oracle Wallet

Authentication > Type

Authentication > Authentication type > User & password

Authentication > Role

Connection options

Cache age

Custom Metrics cache age

Instance discovery

Sections — data to collect

Databases to monitor

7.3. Beispielkonfigurationen

Minimale Konfiguration

(Fast) vollständiges Beispiel

5. Migration von `mk_oracle` zu `mk-oracle`