Quelltext der Seite Kettle Kurs Teil 2


Kettle für Fortgeschrittene - Monitoring, Embedding
Universität Wuppertal, 8.12.2022

Kettle ist ein Produkt von [https://www.hitachivantara.com/en-us/products/lumada-dataops/data-integration-analytics/download-pentaho.html Hitachi Vantara]

=Kursbeschreibung=
Der Online-Kurs führt Inhalte aus der [[Kettle-Grundlagen|Kettle-Grundlagenschulung]] fort und adressiert folgende Themen
* Monitoring von Kettle Jobs
** Mailversand
** Logging und Fehlerbehandlung
* Embedding Kettle
** in HISinone-BI
** Standalone unter Linux
* Versionierung von Quellcodes
Download Kursmaterial: https://superx-rocks.de/git/Memtext/Kettle-Schulung



=Monitoring/Logging von Kettle Jobs=
==Mailversand in Kettle==
===Mailversand Beispiel 1===
Unser erster Beispieljob versendet einfach nur eine Mail. Hier eine Gesamtübersicht der Schritte im Job:



[[Bild:kettle_jobmonitor_mail1.png|300px]]

Der Job führt nur einen Dummp-Step aus, und verschickt dann eine Mail. Dazu gibt es im Reiter "Design" einen Step:




[[Bild:kettle_jobmonitor_mail2.png|400px]]

In dem Dialog im Reiter "Adresses" spezifizieren Sie die Absender- und Empfängeradresse. Danach geben Sie Daten zum Mailserver an:



[[Bild:kettle_jobmonitor_mail3.png|400px]]

Unser Beispiel-Mailserver verlangs Zugangsdaten zum Mailversand, diese tippen wir einfach ein. Danach wird Betreff und Inhalt der Mail definiert:



[[Bild:kettle_jobmonitor_mail4.png|400px]]

Wir versenden eine einfache Testmail mit voreingestellten Kettle-Protokolldaten. Dann starten wir den Job:

[[Bild:kettle_jobmonitor_mail5.png|400px]]

Der Job war erfolgreich, und es müßte tatsächlich eine Mail ankommen:

[[Bild:kettle_jobmonitor_mail6.png|400px]]

Damit haben wir ein einfaches Beispiel zum Mailversand abgeschlossen.

===Mailversand mit Variablen===
Im obigen Beispiel haben wir die Angaben zum Mailversand "hartcodiert" in den Dialog eingetragen. Da es vermutlich mehrere Jobs mit Mailversand gibt, ist es sinnvoll die immer wiederkehrenden Angaben zum Mailserver etc. in Variablen auszulagern. Wir verfeinern also obiges Beispiel, indem wir dem Mailversand eine Transformation vorschalten, die die Variablen definiert und setzt. Hier eine Gesamtübersicht des Jobs:

[[Bild:kettle_jobmonitor_mail10.png|300px]]

Da in der Regel solche Angaben in einer Datenbank vorgehalten werden, wählen wir in der Transformation einen Table-Input Step:

[[Bild:kettle_jobmonitor_mail11.png|400px]]

Der Step selektiert die jew. Parameter, das Beispiel funktioniert unter Postgres und kann so leicht auf die eigene DB angepaßt werden.

[[Bild:kettle_jobmonitor_mail12.png|400px]]

Die Parameter werden dann über den "Set Variables"-Step zur Laufzeit im gesamten Job zur Verfügung gestellt:

[[Bild:kettle_jobmonitor_mail13.png|600px]]

Der folgende Dialog zum Mailversand wir dann statt "hartcodiert" mit Verweisen auf die Variablen versehen:

[[Bild:kettle_jobmonitor_mail14.png|600px]]

Im folgenden Reiter zum Mailserver sind die Angaben dann analog vorzunehmen. Der Job sollte danach genauso funktionieren wie das erste Beispiel.
===Mailversand mit ausgelagerten Variablen===
Im obigen Beispiel haben wir "sensitive" Angaben zum Mailversand (Benutzername, Passwort) "hartcodiert" in die Datenbank geschrieben. Hier ist es sinnvoll, diese Angaben aus Job und Datenbank herauszunehmen. Kettle bietet die Möglichkeit, zentrale bzw. systemspezifische Variablen in eine Datei "kettle.properties" auszulagern, Details dazu siehe [[Kettle_Kurs_Teil_2#Kettle.properties|unten]]. 

[[Bild:kettle_jobmonitor_mail20.png|300px]]

Das verschlüsselte Passwort und die Zugangskennung wird dann als Variable übergeben. 

[[Bild:kettle_jobmonitor_mail21.png|500px]]

Das Passwort-Feld ist maskiert, die Eingabe ist
 ${MAILPW}

{{Achtung|Bei einer Änderung der kettle.properties müssen Sie Spoon neu starten.}}

==Loglevel und -dateien==
Kettle bietet diverse Möglichkeiten zum Logging und zur Fehlerbehandlung:
* Logausgabe von Spoon / Kitchen
** In Jobs kann man diese verfeinern mit dem "Write to log"-Step
* Eine Transformation kann 
** die Logausgabe in einer dezidierten Logdatei speichern bzw. erweitern
** im Aufruf eines Jobs in eine Fehlerbehandlung laufen

Das folgende Beispiel zeigt die Nutzung, im Job wird eine Logdatei angelegt, und dann schreiben die einzelnen Transformationen in diese Logdatei. Diese wird dann am Ende per Mail als Anhang verschickt - egal ob es mit Fehler oder erfolgreich war:

[[Bild:kettle_jobmonitor_log1.png|600px]]

Im ersten Schritt wird die Logdatei "ladejob.log" angelegt bzw. geleert, wenn sie schon existiert:

[[Bild:kettle_jobmonitor_log2.png|600px]]

Die erste "Set variables"-Transformation wird im Reiter "Logging" so konfiguriert, dass die Ausgabe in die Logdatei "ladejob.log" geloggt wird.

[[Bild:kettle_jobmonitor_log3.png|600px]]

Ergänzend wollen wir auch die gesamt-Logausgabe des Jobs um eine Zeile erweitern, die die übergebene Mailkennung aus der kettle.properties ausgibt:

[[Bild:kettle_jobmonitor_log4.png|600px]]

Danach wird eine Transformation erstellt, die Postgres-spezifische Systemvariablen 
* selektiert und
* das Ergebnis in die Logdatei schreibt

[[Bild:kettle_jobmonitor_log5.png|600px]]

Da diese Operation aus der Datenbank liest und ggf. Fehler bewirken kann, wird neben der normalen Erfolgs-Ausgabe ein "Fehlerkanal" eingerichtet, der eine entsprechende Fehler-Mail verschickt:

[[Bild:kettle_jobmonitor_log6.png|600px]]

Im Reiter "Attached files" wird die Logausgabe des Jobs angehängt:

[[Bild:kettle_jobmonitor_log7.png|600px]]

Unser Job arbeitet von nun an mit einer Fehler- und Logbehandlung.

=Versionierung von Jobs=
Kettle Jobs und Transformationen sind XML-Dateien und lassen sich mit Versionskontrollsystemen (z.B.  git ) versionieren.  Es gibt allerdings ein paar Fallstricke:
* Kleinste Layoutänderungen in Spoon führen mitunter zu großen Änderungen im Quellcode, so dass Sie solche Änderungen eher in separate Commits trennen sollten, und den Layout-Comment in der Commit Message z.B. als "reine Layout-Änderung" kennzeichnen.
* Die Connection-Angaben müssen entfernt werden. Wie das geht zeigen wir nun.
==Entfernen der Connection-Elemente==
<blockquote>
Beim Speichern eines Jobs wird immer die Connection mitgespeichert. Daher muss sie vor dem Commit ins git  gelöscht werden. Hierzu ist der gesamte Tag sowohl im Job, als auch in den Transformationen zu löschen.

{{ImagePara |imgsrc=kettle_integration_1.png|width=600|caption=}}
</blockquote>
<blockquote>
Die Connection-Information in den einzelnen Schritten bleibt jedoch enthalten.

{{ImagePara |imgsrc=kettle_integration_2.png|width=600|caption=}}
</blockquote>
===Automatisierung mit Groovy===
Sie können mit dem Java-Tool [https://groovy.apache.org/ Groovy] und einem von uns mitgelieferten Script die Connection-Elemente automatisch entfernen. Gehen sie dazu wie folgt vor:
* Stellen Sie sicher dass am Arbeitsplatz-Rechner Java installiert ist
* Laden Sie Groovy [https://groovy.apache.org/download.html herunter], und entpacken Sie es in einem Ordner Ihrer Wahl (am besten ohne Leerzeichen im Pfadnamen).
* Fügen Sie den bin-Pfad der Groovy-Installation in Ihren PATH an, 
** unter Windows z.B.:
*** in der Systemsteuerung -> Erweiterterte Einstellungen -> Umgebungsvariablen -> PATH

{{ImagePara |imgsrc=kettle_groovy_dos1.png|width=300|caption=PATH unter Windows}}

* unter Linux z.B.:
 PATH=$PATH:~/tools/groovy/groovy-2.4.10/bin
 export PATH

* Wechseln Sie in der Shell (DOS oder Linux) in das Verzeichnis, wo die ETL-Jobs liegen (hier also /superx/superx/WEB-INF/conf/edustore/db/module/myjobs/etl ) 
* Legen Sie dort einen Unterordner an mit dem Namen einer Kopie des ETL-Verzeichnisses , hier also z.B. "jobmonitor_git".
* Dann führen Sie das Script aus
Unter Linux:
 groovy ~/git/myjobs/scripts/groovy/copy_kettlejob.groovy --strip-connections jobmonitor/jobmonitor.kjb jobmonitor_git
Unter Windows:
 groovy Z:\git\myjobs\scripts\groovy\copy_kettlejob.groovy --strip-connections jobmonitor/jobmonitor.kjb jobmonitor_git

Damit werden alle Connection Elemente in dem Job und in den darin aufgerufenen Transformationen entfernt:

{{ImagePara |imgsrc=kettle_groovy_dos2.png|width=600|caption=Groovy Ausgabe}}

Wenn das geklappt hat, können Sie die bereinigten Dateien in den "richtigen" Ordner "jobmonitor" kopieren und versionieren.

=Jobmanagement=
Im folgenden zeigen wir wie Sie Jobs "on demand" direkt aus HISinOne oder SuperX im Browser vom Nutzer starten lassen.
{{Achtung|Achten Sie darauf, dass Ihre lokale genutzte Version zu der in HISinOne-/SuperX integrierten Version paßt. Sonst könnte es ggf. Probleme geben.}}
{| border="0"
|-
| style="width:20%; padding:20px; text-align:center;"|<img src="/wiki/images/4/4a/attention.svg" alt="attention.svg" width="48" height="45" />
| style="width:80%; text-align:left;"|Achten Sie darauf, dass Ihre lokale genutzte Version zu der in HISinOne-/SuperX integrierten Version paßt. Sonst könnte es ggf. Probleme geben.
|}



{| class="wikitable"
|-
|Software<br />
|Version<br />
|Kettle Version<br />
|-
|HISinOne-BI<br />
|ab 2021.06<br />
|Kettle 8.3<br />
|-
|SuperX
|ab Kernmodul 4.9
|Kettle 6.0
|}

==Eigenes BI-Modul==
Ein Kettle Job ohne Eingabeparameter kann in einem eigenen "Mini"-Modul deklariert und über das HISinOne-Jobmanagement ausgeführt werden.
# Erstellen Sie ein minimales [http://www.superx-projekt.de/doku/kern_modul/admin/f_InstallationvonModulen.htm Modul] mit einer Modul-XML-Datei
#* Siehe z.B. https://superx-rocks.de/git/Memtext/Kettle-Schulung
# In der [http://www.superx-projekt.de/doku/entwicklerhandbuch/f_ModulXML.htm Modul-XML-Datei] im Bereich ETL können Sie Ladejobs deklarieren
# Das Modul können Sie auf eine SuperX- oder BI-Installation [[Memtext_Hochschul-git#Synchronisieren_des_Repository| synchronisieren]] oder die zip-Datei dort unter $SUPERX_DIR bzw. webapps/superx entpacken
# Danach ist es in der BI-Komponentenverwaltung sichtbar:

[[Bild:kettle_myjobs1.png|600px]]

Mit Klick auf das "Installations-"Icon wird es installiert

[[Bild:kettle_myjobs2.png|400px]]

und danach ist es auch in der Konnektorenübersicht sichtbar, inkl. Unter-Ladejobs: 

[[Bild:kettle_myjobs3.png|400px]]

Die Jobs können dann über das BI Jobmanagement ausgeführt werden.
Auch ein zeitgesteuertes Ausführen ist möglich , per [https://wiki.his.de/mediawiki/index.php/Komponenten_Update-HISinOne-BI? Kommandozeile].

Über die Browser-Oberfläche ist ebenfalls ein zeitgesteuerter Update möglich. Gehen Sie dazu in die Admin-Rolle, und wählen das Menü Administration -> Konfigurationsassistenten:

[[Bild:kettle_myjobs5.png|400px]]

Ajuf dem Reiter "Business Intelligence" können Sie den jew. Job markieren und so in die nächtliche Laderoutine aufnehmen:

[[Bild:kettle_myjobs6.png|400px]]

Weitere Details siehe die Beschreibung des Installationsassistenten bei [https://wiki.his.de/mediawiki/index.php/Konfigurationsassistent_Business_Intelligence HIS].

==BI Ladejob ausführen==
===Tomcat Konfiguration===
Vorab: Sie müssen die Umgebungsvariable CATALINA_OPTS erweitern:

 CATALINA_OPTS="... -DMODULE_PFAD=/var/lib/tomcat9/webapps/superx/WEB-INF/conf/edustore/db/module ..."

Unter Ubuntu Linux liegt das in der Datei 

 /etc/default/tomcat9

dort die Variable 

 JAVA_OPTS="... -DMODULE_PFAD=/var/lib/tomcat9/webapps/superx/WEB-INF/conf/edustore/db/module ..."

Danach muss man Tomcat neu starten.

===Job registrieren===
Um den Job im System bekannt zu machen wird ein Eintrag in der Tabelle sx_jobs angelegt. Sie erreichen die Bearbeitung über das Menü Administration -> Tabelle suchen.



[[Bild:kettle_ladejobs_schulung1.png|400px]]

Im Listenformular können Sie neue Jobs anlegen, oder vorhandene ändern. 

[[Bild:kettle_ladejobs_schulung2.png|600px]]

Hier unser Beispiel:

[[Bild:kettle_ladejobs_schulung3.png|500px]]

Das Ergebnis des Prüfprotokolls erscheint nach Ausführen des Jobs im Ladeprotokoll. Hier können Sie z.B. die Anzahl der Datensätze in einer Zieltabelle zählen.

===Ladejob-Masken erstellen=== 

: 
Die Masken, welche Ladejobs ausführen benötigen zwingend das Feld '''dokettlejob'''. Anhand dieses Feldes wird dem System mitgeteilt, dass ein Kettle-Job auszuführen ist. Das Feld darf versteckt werden.

{{ImagePara |imgsrc=kettle_integration_schulung_3.png|width=600|caption=Felder der Maske}}
: 
Um die auswählbaren Kettle-Jobs zu definieren wird auf die Tabelle sx_jobs zugegriffen.

{{ImagePara |imgsrc=kettle_integration_schulung_4.png|width=800|caption=Feld Job}}

Die Maske kann nach den vorhandenen SuperX-BI-Techniken mit speziellen Benutzer- und Gruppenrechten versehen werden. Auch neue Maskenfelder sind möglich, diese werden automatisch als Parameter an den Job übergeben (sofern der Kettle-Job den Parameter kennt).

===Ladejob-Masken nutzen===
Der Ladejob bietet eine einfache Browser-Oberfläche: 

{{ImagePara |imgsrc=kettle_ladejob_ausfuehren1.png|width=400|caption=Maske zum Starten}}

In der Maske wählen Sie den Ladejob, dies ist ein Pflichtfeld. Mit dem Abschicken wird der Job gestartet, und der oben definierte Test-SQL im Sinne einer "vorher-nachher"-Messung abgesetzt.

{{ImagePara |imgsrc=kettle_ladejob_ausfuehren2.png|width=400|caption=Maske nach Ausführung}}

=Kitchen=
Kitchen dient der Ausführung von Kettle Jobs via Kommandozeile. Wichtig ist die Umgebung, in der Kitchen gestartet wird. 
==Home-Verzeichnis==
Zunächst ist es wichtig, das Home-Verzeichnis von Kettle beim Aufruf von Kitchen  zu kennen. Standardmäßig liegt das Verzeichnis in HOME/.kettle, also unter Linux (3 Varianten):
 $HOME/.kettle
 ~/.kettle
 /home/Benutzername/.kettle
und unter Windows ( 2 Varianten):
 C:\users\Benutzername
 C:\Documents and Settings\{Benutzername}\.kettle
Im Home-Verzeichnis von Kettle werden Konfigurationsdateien gesucht. Sie können das Home-Verzeichnis auch variiieren, indem Sie die System-Umgebungsvariable KETTLE_HOME setzen.
 
==Umgebungsvariablen==
Im [[Kettle_Kurs_Teil_2#Home-Verzeichnis|Home-Verzeichnis]] wird nach zwei Dateien gesucht:
; kettle.properties: Allgemeine Umgebungsvariablen
; shared.xml: Datenbankverbindungen 
===Kettle.properties===
Sie können in der Textdatei beliebige Konfigurationen setzen, die Sie nicht in den Jobs / Transformationen oder in der Datenbank speichern wollen, z.B. Zugangsdaten für Email-Server.
Beispielinhalt:
 MAILUSER = schulung@superx-projekt.de
 MAILPW = anfang12
Sie können Passworte sogar verschlüsseln, indem Sie das Kommandozeilen-Tool "encr" nutzen. Unter Linux:
 encr.sh -kettle anfang12
Unter Windows:
 encr.bat -kettle anfang12

{{Achtung|Wenn Ihr Passwort Leerzeichen oder Sonderzeichen enthält, ist es sicherer das Passwort mit einfachem Hochkomma (Linux) oder doppelten Anführungsstrichen (Windows) zu umschließen.}}
 
Es wird ein verschlüsseltes Passwort ausgegeben:
 Encrypted 2be98afc86aa7f2e4aa17a871d095fe88
Dieses Passwort können Sie dann in die kettle.properties eintragen:
 MAILUSER = schulung@superx-projekt.de
 MAILPW =Encrypted 2be98afc86aa7f2e4aa17a871d095fe88
===Shared.xml===
Speziell für Datenbankverbindungen gibt es eine eigene Datei. Hier ein Beispiel:

 <?xml version="1.0" encoding="UTF-8"?>
 <sharedobjects>
   <connection>
    <name>eduetl</name>
    <server>localhost</server>
    <type>POSTGRESQL</type>
    <access>Native</access>
    <database>superx</database>
    <port>5432</port>
    <username>superx</username>
    <password>Encrypted 2be98afc86aa7f2e4aa17a871d095fe88</password>
    <servername></servername>
    <data_tablespace/>
    <index_tablespace/>
    <attributes>
      <attribute><code>PORT_NUMBER</code><attribute>5432</attribute></attribute>
     </attributes>
  </connection>
  <connection>
    <name>hisinone</name>
    <server>localhost</server>
    <type>POSTGRESQL</type>
    <access>Native</access>
    <database>hisinone_cust</database>
    <port>5432</port>
    <username/>
    <password>Encrypted 2be98afc86aa7f2e4aa17a871d095fe88</password>
    <servername/>
    <data_tablespace/>
    <index_tablespace/>
    <attributes>
      <attribute><code>PORT_NUMBER</code><attribute>5432</attribute></attribute>
    </attributes>
  </connection>
 </sharedobjects>
Es werden zwei Datenbankverbindungen konfiguriert, die dann in Kettle Transformationen im Element "connection" genutzt werden können.
{{Achtung| Bei der Entwicklung von Jobs und Transformationen werden die Connection-Elemente auch in den jew. Quelltext geschrieben und gespeichert. Und bei der Ausführung haben diese Elemente eine höherer Priorität als die shared.xml, so dass man diese Elemente vor dem Installieren im Zielsystem [[Kettle_Kurs_Teil_2#Entfernen_der_Connection-Elemente|entfernen]] muss.}}

=Kettle Goodies=
* Coole neue Features