Log Service
Dieses Modul bietet unter anderem einen REST-Endpunkt, um Monitor-Daten entgegenzunehmen und diese nach Elasticsearch und optional in eine Datenbank zu schreiben. Die betreffenden Monitor-"Clients" werden sofort per Websocket-Event über neue Daten informiert.
Soll auch in eine Datenbank geschrieben werden, dann müssen die Datenbanktabellen bereits angelegt sein. Diese werden nicht automatisch angelegt und bei Änderungen der Datenstruktur auch nicht automatisch angepasst. |
Falls in eine Datenbank geschrieben wird, dann werden über eine DB-Transaktion zuerst die Datenbankdaten geschrieben (ist normalerweise fehleranfälliger) und erst danach die Daten nach OpenSearch. Beim Schreiben in die Datenbank wird zuerst ein DB-Update (siehe keys-Einstellung) durchgeführt und wenn dies fehlschlägt ein DB-Insert. |
Wie bereits oben erwähnt, werden die Daten des Log-Service üblicherweise über den Monitor dargestellt.
Dieser verwendet einen Process-Index (= parent Daten) sowie einen History-Index (= child Daten). |
Endpunkte
Zur Verwendung der Endpunkte ist ein angemeldeter Benutzer bzw. API Key mit den jeweiligen Rollen/Rechten notwendig.
Als zusätzlichen Schutz kann über die "Log Service"-Moduleinstellung Security_ClientCertificateAuthMandatory
für alle Log Service Endpunkte die Client Certificate Authentication aktiviert werden.
Response im Fehlerfall
Bei jedem Fehler (Status != 200) wird eine JSON mit folgendem exemplarischen Aufbau zurückgeliefert:
{
"error": {
"code": 301,
"name": "MODULE_INSTANCE_NOT_FOUND",
"message": "Did not found the instance 'of_test2' of the module 'logservice'.",
"properties": {
"instanceId": "of_test2",
"moduleId": "logservice"
}
}
}
json
Die möglichen Error Codes
Error Code |
|
Info |
1 |
|
sollte nicht aufreten |
20 |
|
das 'Log Service' Modul wurde nicht gefunden |
21 |
|
die 'Log Service' Instanz wurde nicht gefunden |
10000 |
|
Es wurden keine Daten zum "loggen" übergeben |
10010 |
|
Die übergebenen Daten sind kein gültiges JSON bzw. entsprechen nicht dem hier genannten Aufbau |
20000 |
|
Die Zugangsdaten stimmen nicht mit den hinterlegten überein (Log Service Modul Einstellung) |
20001 |
|
Der Log-Service befindet sich derzeit im Wartungsmodus bzw. das DB und ES Logging sind deaktiviert |
20002 |
|
Ein vom Log Service benötigter Dienst steht nicht zur Verfügung |
20100 |
|
Beim DB Logging ist ein Fehler aufgetreten |
20101 |
|
Beim Löschen von DB Einträgen ist ein Fehler aufgetreten |
20102 |
|
Es wurde ein ungültiger Tabellenname angegeben |
20103 |
|
Die verwendete Datenbank-Tabelle konnte nicht gefunden werden |
20104 |
|
Die zu verwendende Datenbank-Spalte existiert nicht |
20105 |
|
Die Metadaten der Datenbank konnten nicht ausgelesen werden |
20106 |
|
Die angeforderte Funktionalität steht bei relationalen Datenbanken nicht zur Verfügung |
20201 |
|
Beim Zugriff auf Elasticsearch ist ein Fehler aufgetreten |
20202 |
|
Zum Bilden des Dokument-Schlüssels fehlen die erforderlichen Daten im zu loggenden Dokument |
20203 |
|
Beim Schreiben der Daten nach Elasticsearch kam es zu einem Problem |
20204 |
|
Beim Löschen von Dokumenten aus dem Elasticsearch Index ist ein Fehler aufgetreten |
20205 |
|
Es wurden mehr Daten angefordert als zur Verfügung stehen |
POST : Aufbau der zur übergebenden JSON Nachricht
Eintrag erstellen/aktualisieren
{
"entries": [
{
"parent": {
"feldname1": wert1,
"feldname2": wert2,
...
},
"childs": [
{
"feldname1": wert1,
"feldname2": wert2,
"datei_binary": base64_3,
...
},
{
"feldname1": wert3,
"feldname2": wert4,
"datei_binary": base64_5,
...
},
...
]
},
...
]
}
json
Einzelne Felder aktualisieren (Partial Update)
{
"entries": [
{
"partialUpdate": true,
"parent": {
"feldname1": wert1,
"feldname2": wert2
},
...
},
...
]
}
json
Infos zum Partial Update
Das Partial Update bezieht sich auf den Parent Eintrag und die Child Einträge. Das bedeutet, wenn man ein Parent Eintrag updaten möchte, sollte man keinen "neuen" Child Log im gleichen JSON Dokument erstellen. Wenn man beim Update eines Parent Eintrages einen neuen Child Log erstellen möchte, sollte es in zwei Log-Service-Calls implementiert werden. Es könnte beispielsweise wie folgt aussehen (siehe INFOBLOCK 1 und 2):
Werte der JSON Felder
Feldnamen Konvention
Über die Modulinstanz Einstellung fields
(siehe unten) können die Datentypen pro Feld festgelegt werden.
Dies ist für binary-Typen nicht unbedingt notwendig und kann auch über die Feldnamen Konvention FIELDNAME_binary (_binary als Postfix) durchgeführt werden.
Hintergrund: In Elasticsearch speichern wir Binärdaten Base64 encoded ab (so müssen diese auch im übergebenen JSON stehen). Diese wollen wir aber, wie bei der Replikation unter dem speziellen Typ 'attachment' ablegen. Da beides für Elasticsearch Strings sind, müssen wir dies wissen und ein spezielles Mapping durchführen.
Beispiel: Wenn wir ein Feld mit dem Namen 'datei' haben und die Namen frei vergeben können, dann kann daraus der Name 'datei_binary' werden und Elasticsearch legt die Daten als 'attachment' ab bzw. erstellt das Mapping dafür.
Beispiel Aufruf
curl -H "X-ApiKey: 1f697af5-c147-3d94-c529-e06f3f15bb87" \
-H "Content-Type: application/json" \
-XPOST 'localhost:8181/cxf/bpc-logservice/log/of_test' \
-d @logservice.json
Erläuterung:
Option |
Beschreibung |
|
Der API-Key mit der passenden Rolle bzw. passendem Recht |
|
Der Content-Type muss auf |
|
HTTP POST ist erforderlich |
|
|
|
das zu postende JSON (siehe unten) |
logservice.json (Eintrag erstellen/aktualisieren)
{
"entries": [
{
"parent": {
"processid": 40,
"name": "hello world",
"city": "Berlin",
"lastupdate": "2017-05-17T15:28:23.181Z"
},
"childs": [
{
"processid": 40,
"childid": 1,
"ersteller": "Oliver",
"kommentar": "Bild und langer Text",
"datei": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACAQMAAABIeJ9nAAAABlBMVEUAAAD///+l2Z/dAAAADElEQVQIHWNwYGgAAAFEAMGoX3f9AAAAAElFTkSuQmCC",
"langertext": "Dieser Text ist aber ziemlich .................... lang. :-)",
"lastupdate": "2017-05-17T15:28:23.181Z"
}
]
}
]
}
json