Log-Nachricht

Prev Next

Siehe auch: Logging

Ereignisaktion - Kurzfassung

Zweck: Die Log-Nachricht-Ereignisaktion erzeugt abhängig vom Kontext einen Eintrag in einer Log-Datei des Lobster Data Platform / Orchestration-Servers oder der Browser-Konsole, sofern die Log Level-Einstellung dies für den beim Erzeugen der Nachricht zugeordneten Level vorsieht.

Tooltip

  • Verwendung: An einen per Name adressierten Logger wird eine Nachricht gesendet, die analog zur Sprachverwaltung Parameter enthalten kann. Ob ein Log-Eintrag geschrieben wird, hängt vom Abgleich zwischen dem Level der Nachricht und der Log Level-Einstellung für den adressierten Logger ab (Details s. Handbuch). Abhängig vom Level wird in eine der folgenden Log-Dateien geschrieben:

    • Lobster Data Platform / Orchestration/error.log für die Level FATAL und ERROR

    • Lobster Data Platform / Orchestration/message.log für alle anderen Level (außer OFF)

  • Parameter:

    • Name: Textwert, der den zu verwendenden Logger benennt

    • Nachricht: Textkörper der Nachricht, der Platzhalter für Parameter (adressiert per Index {0}, {1}, usw.)

    • Level: Einfachauswahl für den Log Level (statische Aufzählung) der Nachricht (Standardwert: DEBUG)

    • Parameter ({0},{1},...): Optionale Wert-Konfigurationen für Textwerte, die in Platzhalter in der Nachricht einfügt werden

  • Hinweise:

    • Der Server startet für jeden neuen Namen einen benutzerdefinierten Logger mit dem Log Level INFO, der über den Menüpunkt Logging angepasst werden kann.

    • Bei Ausführung im Client-Kontext betrifft die Ausgabe nur die Browser-Konsole und diesbezügliche Einstellungen für das Logging.

images/download/attachments/189440346/image-2024-11-29_16-0-41-version-1-modificationdate-1732892441484-api-v2.png

Die Log-Nachricht-Ereignisaktion erzeugt im Server-Kontext (in Ereignisbehandlungen) einen Eintrag in einer Log-Datei des Lobster Data Platform / Orchestration-Servers, sofern die Log Level-Einstellung für den per Name adressierten Logger dies für den beim Erzeugen der Nachricht zugeordneten Level vorsieht.

  • Nachrichten mit dem Level FATAL oder ERROR werden grundsätzlich in der Log-Datei Lobster Data Platform / Orchestration/error.log eingetragen. In der folgenden Tabelle sind betreffende Zellen hellblau schattiert.

  • Nachrichten mit einem anderen Level werden grundsätzlich in der Log-Datei Lobster Data Platform / Orchestration/message.log eingetragen. In der folgenden Tabelle sind betreffende Zellen hellrot schattiert.

Für den Abgleich zwischen dem Level einer Nachricht und dem über den Menüpunkt Logging eingestellten Log Level greift dabei folgende Logik:

Level → Logging

↓ Log-Nachricht

Log Level-Einstellung für den per "Name" adressierten Logger

OFF

FATAL

ERROR

WARN

INFO*

DEBUG

TRACE

ALL

(OFF)



FATAL


error.log

ERROR



error.log

WARN




message.log

INFO





message.log

DEBUG*






message.log

TRACE, ALL







message.log

*) In dieser Tabelle sind die Standardwerte für den Log Level mit einem Stern gekennzeichnet.

Hintergrund: Logger und Log Level

Der Konfigurationsparameter Name kann verwendet werden, um sich auf den Namen eines vordefinierten Loggers zu beziehen oder einen benutzerdefinierten Logger zu "benennen".

  • Wird als Name eine Zeichenfolge angegeben, die auf einen vordefinierten Logger verweist, wird abhängig von dem ggf. per Logging angepassten Log Level für diesen Logger entschieden, ob ein Log-Eintrag geschrieben wird.

    • Falls kein Name angegeben wird, bezieht sich die Log-Nachricht-Ereignisaktion auf den Logger für ihren Typ (de.lobster.scm.actionevent.actor.LogMessageActor).

  • Sobald ein serverseitig noch unbekannter Name erstmalig beim Ausführen der Log-Nachricht-Ereignisaktion verwendet wurde, erscheint beim nächsten Öffnen der Logging-Ansicht ein zusätzlicher Eintrag im Tab "Log-Informationen". Dort kann kann für diesen benutzerdefinierten Logger ein vom Standard (INFO) abweichender Log Level gesetzt werden.
    ►HINWEISE◄

    • Falls die erste Erwähnung des neuen Loggers per Log-Nachricht mit einem Level unterhalb des Standardwerts INFO erfolgt, wird kein Log-Eintrag angelegt. Der Logger erscheint allerdings trotzdem in der "Log-Informationen"-Liste.

    • Da der Log Level DEBUG als Standard für den Level einer Log-Nachricht-Ereignisaktion gilt, wird keine Nachricht erzeugt, wenn kein Level ausgewählt und der Name serverseitig noch unbekannt ist.

Im Client-Kontext (Client Workflow, Client Workflows) adressiert die Log-Nachricht-Ereignisaktion nur die Browser-Konsole, wo abhängig von den gewählten Einstellungen für das Logging eine Nachricht erscheint oder nicht.

Konfiguration

Konfigurationsbeispiel:

images/download/attachments/189440346/image-2024-12-2_9-52-4-version-1-modificationdate-1733129524028-api-v2.png

Der folgende Ausschnitt aus einem error.log von Lobster Data Platform / Orchestration verdeutlicht die Wirkung der Konfigurationsparameter.

images/download/attachments/189440346/image-2024-12-2_9-46-6-version-1-modificationdate-1733129166304-api-v2.png


Konfigurationsparameter

Element

Beschreibung

Name

Standardwert:
(...LogMessageActor)

Textfeld für Direkteingabe
oder
(zum Umschalten Pfeil in der linken unteren Ecke drücken!)
Wert-Konfiguration, deren Rückgabewert in einen String umgewandelt wird

Der Name benennt den zu verwendenden Logger. Der Name erscheint im Log-Eintrag als Präfix vor der Nachricht hervorgehoben durch eckige Klammern: [Name]

Im Beispiel (statischer Text): Name

Nachricht

Standardwert:
null

Die Nachricht erscheint am Ende des Log-Eintrags. Sie kann Platzhalter für Werte enthalten ({0}, {1}, ...), die über Parameter (s. u.) definiert werden.

Im Beispiel (statischer Text): Nachricht von {0}mit Platzhalter {0 } für die Firma der Session (s. Parameter)

Level

Standardwert:
DEBUG

Auswahlfeld/Combobox für Einfachauswahl aus der statischen Aufzählung "Log Level" (LogLevel)

Vom gewählten Level hängt ab, ob und ggf. in welche Log-Datei ein Log-Eintrag geschrieben wird. Außerdem erscheint der interne Name des Aufzählungswerts im automatisch erzeugten Vorspann des Log-Eintrags zwischen eckigen Klammern.

[ERROR]

Parameter ({0},{1},...)

Standardwert: null

Wiederholendes Element für Wert-Konfigurationen, deren Rückgabewert in einen String umgewandelt wird

Optional können Wert-Konfigurationen für Parameter bereitgestellt werden, die in der Nachricht über ihren Index (aufsteigend von 0) zwischen geschweiften Klammern adressiert werden können (s. Hinweise unten).

►HINWEIS◄ Für die Verwendung von Parametern sind - analog zur Handhabung für Lokalisierungseinträge in der Sprachverwaltung - folgende Sonderfälle zu berücksichtigen:

  • Falls die Nachricht einen Parameter mit einem Index referenziert, für den unter Parameter ({0},{1},...) kein Eintrag existiert, dann erscheint die Referenz inkl. der geschweiften Klammern als Klartext (z. B. "Nachricht von {0}").

  • Falls die Wert-Konfiguration für einen in der Nachricht referenzierten Parameter entweder fehlt oder zur Laufzeit "Kein Wert" ($null) liefert, erscheint anstelle des Parameters der Klartext "null" (z. B. "Nachricht von null").

Beispiele

Einfacher Anwendungsfall: Erstanmeldung eines Gastbenutzerkontos als INFO loggen

Wenn sich ein Gastbenutzer erstmalig an Lobster Data Platform / Orchestration anmeldet, soll ein Log-Eintrag mit dem Level INFO mit einem Hinweis angelegt werden, der die ID des Gastbenutzers sowie die Firma der Session und die Rolle der Session benennt.

Der Log-Eintrag soll sich auf den Namen WELCOME beziehen, sodass ein benutzerdefinierter Logger mit diesem Namen erzeugt wird.

Laufzeitbeispiel:

16:49:37 NORMAL [600ms] [T231 /auth/clientEvent/CLIENT_LOGGED_IN [...]] [...] [INFO ] > > > > [WELCOME] Guest user #-8051 from Xflow AG as Querificus

►ANMERKUNG◄ Die "ID" (id) des Gastbenutzers erscheint hier als negative Ganzzahl (-8051), da sie direkt aus dem Rückgabewert des Benutzer der Session-Wertauflösers übernommen wird, der über das Vorzeichen Gastbenutzer und Benutzer differenziert.

Konfiguration:

Der Screenshot rechts zeigt einen Überblick der Konfiguration für die Ereignisbehandlung mit der Log-Nachricht-Ereignisaktion:

  • Die Prüfende Regel verwendet eine Mit-Regel, die feststellen soll, ob sich ein Gastbenutzer anmeldet, der nicht nie angemeldet war:

    • Der Objekt Feld Resolver definiert den Benutzer der Session als temporäres Bezugsobjekt für die nachfolgend ausgewerteten Regeln.

    • Unterhalb folgt eine UND-Verknüpfung (s. Verknüpfung) von zwei Regeln:

      • Die Typprüfung prüft, ob das Bezugsobjekt ein Gastbenutzer ist.

      • Die folgende Objekt-Feld-Regel vergleicht das Objekt-Feld "Anzahl Logins" (loginCount) mit der statischen Ganzzahl 0, um sicherzustellen, dass nur dann Aktionen ausgeführt werden, wenn der Gastbenutzer noch nie angemeldet war.

  • Als einzige Aktion bei bestandener Regel wird eine Log-Nachricht-Ereignisaktion ausgeführt, deren Parametrierung unten weiter ausgeführt wird.


images/download/attachments/189440346/image-2024-12-3_17-39-10-version-1-modificationdate-1733243950610-api-v2.png



  • Für die Log-Nachricht-Ereignisaktion wird statische Text WELCOME als Name per Direkteingabe eingetragen.

  • Die Nachricht mit drei Platzhaltern für Parameter (s. u.) wird ebenfalls per Direkteingabe statisch festgelegt:

    Guest user #{0} from {1} as {2}

    ►ANMERKUNG◄ Da in den Log-Dateien überwiegen englischer Inhalt zu finden ist, wird hier darauf verzichtet, die Sprachverwaltung zu beanspruchen (s. Wert aus Sprachverwaltung).

  • Der Level wird durch Auswahl in der als Standard vorgegeben Combobox als INFO festgelegt. Technisch kommt hier ein Statische Aufzählung-Wertauflöser zum Einsatz, der sich auf die statische Aufzählung "Log-Level" (LogLevel) bezieht.

  • Es folgen drei Wert-Konfigurationen für Parameter ({0},{1},...):

    • {0}: Die erste Wert-Konfiguration liest das Objekt-Feld id aus dem Rückgabewert des Benutzer der Session-Wertauflösers.

    • {1}: Die zweite Wert-Konfiguration liest das Feld "Name"(address.Name1) aus der Adresse des Firmenkontos, das der Firma der Session-Wertauflöser zurückgibt.

    • {2}: Die dritte Wert-Konfiguration liest das Feld "Rollenname" (roleName) aus dem Rückgabewert des Rolle der Session-Wertauflösers.

►ANMERKUNG◄ Für Gastbenutzer sind eindeutige Auswahl für die Felder "Firma" (companyId) und "Rolle" (roleId) verpflichtend. Wie die internen Feldnamen nahelegen, referenziert das Gastbenutzerkonto "Firma" und "Rolle" dabei allerdings nur, ohne deren Detaildaten einzubinden. Da die betreffenden Parameter in der Nachricht mit Klartext versorgt werden sollen, ist der Zugriff über Firma der Session und Rolle der Session hier eleganter.


images/download/attachments/189440346/image-2024-12-3_17-41-13-version-1-modificationdate-1733244072762-api-v2.png


Komplexerer Anwendungsfall: Level für error.log-Eintrag dynamisch zuweisen

In Anlehnung an das vorherige Beispiel soll beim Anmelden eines Gastbenutzers mit einer anderen als der designierten Rolle "XF_GUEST" nicht nur die Sitzung beendet, sondern auch eine Log-Nachricht ins error.log geschrieben werden.

Für die Nachricht soll abhängig von der verwendeten Rolle entweder der Level FATAL ("Super user", "Super user limited") oder ERROR (andere Rollen) zugewiesen werden.

Laufzeitbeispiel:

18:29:02 [596ms] [T1499 /auth/clientEvent/CLIENT_LOGGED_IN [...]] [...] [FATAL] > > > > [WELCOME] Denied access to Guest user -8051 as Super user limited

Konfiguration:

  • Als Aktionen bei bestandener Regel sollen zwei Ereignisaktionen ausgeführt werden:

    • Die Log-Nachricht-Ereignisaktion stellt sicher, dass der Vorfall einer "unangemessenen" Anmeldung als Gastbenutzer im error.log nachvollziehbar ist.

    • Die nachfolgende Abbrechen-Ereignisaktion stellt sicher, dass die formal legitime Sitzung in diesem Fall sofort wieder beendet wird.

►ANMERKUNG◄ Da der abgemeldete Benutzer eine beim Abbrechen ausgelöste Fehlermeldung sowieso nicht mehr angezeigt bekommt, ist dabei der Modus "Unterdrücken" ausgewählt.

images/download/attachments/189440346/image-2024-12-3_18-41-29-version-1-modificationdate-1733247688696-api-v2.png

Die Log-Nachricht-Eregnisaktion wird wie rechts abgebildet konfiguriert:

  • Als Name wird (wie oben) per Direkteingabe der statische Text WELCOME eingegeben.

  • Die Nachricht mit zwei Platzhaltern für Parameter wird ebenfalls per Direkteingabe angelegt:

    Denied access to Guest user {0} as {1}

  • Der Level wird über einen Bedingter Wert-Wertauflöser definiert, der zwei Fälle unterscheidet:

    • Falls eine Rollenregel zutrifft, die besonders "mächtigen" Rollen als Positivliste verwendet, wird der Level "Fatal" (FATAL) zugewiesen.

    • Anderenfalls wird der Level "Fehler" (ERROR) zugewiesen.

  • Die beiden Parameter in der Nachricht werden mit das Daten aus den Rückgabewerten für Benutzer der Session und Rolle der Session versorgt.

images/download/attachments/189440346/image-2024-12-3_18-54-18-version-1-modificationdate-1733248458308-api-v2.png