JavaScript-Bibliothek agorum.dev/js/lib/logger

Mithilfe dieser JavaScript-Bibliothek können Sie die eingebaute Logging-Funktionalität von agorum core in Ihren Skripten verwenden.

Verwendung

---

Diese Bibliothek binden Sie stets am Anfang eines Skripts ein:

let logger = require('/agorum/roi/customers/agorum.dev/js/lib/logger');

Da die Bibliothek typischerweise dafür verwendet wird, um innerhalb eines Skripts in einen fest zugehörigen Knoten zu loggen, wird dieser zumeist auch mit angegeben:

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('log.node.name');

Eigene Log-Knoten registrieren

---

Einen Hauptknoten erstellen

Statt einen der vordefinierten Knoten zu verwenden, können Sie auch beliebige weitere Log-Knoten definieren, die im agorum core support tool angezeigt werden.

1. Legen Sie in der MetaDB unterhalb von MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes eine neue Gruppe mit dem Namen Ihrer Konfiguration an, sofern nicht schon vorhanden, etwa:

   MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]

2. Legen Sie unterhalb dieser Gruppe ein Bundle mit dem Namen an, den Sie dem Log-Knoten geben möchten. Bei kleineren Projekten ist das üblicherweise ebenfalls der Name der Konfiguration, etwa:

   MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]/my.project

3. Erzeugen Sie in diesem Bundle den Eintrag name, der denselben Namen enthält, und den Eintrag title mit einer längeren Bezeichnung für den neuen Knoten. Dieser Titel wird im Baum des agorum core support tools verwendet, um den Knoten darzustellen:

   MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]/my.project/name: my.project
   MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]/my.project/title: My Project

Wenn die logger-Bibliothek danach das nächste Mal geladen wird, werden die benötigten Knoten angelegt und können direkt verwendet werden.

Einen Unterknoten erstellen

Bei größeren Projekten bietet es sich an, unterhalb des neuen Log-Knotens weitere Unterknoten anzulegen, um verschiedene Bereiche im Log leichter voneinander unterscheiden zu können.

1. Legen Sie in der MetaDB innerhalb des vorhandenen Knotens ein Bundle mit dem Namen items an:

   MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]/my.project/items

2. Legen Sie darunter einen neuen Knoten an, wie unter Hauptknoten erstellen ab Schritt 2 beschrieben, etwa:

   MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]/my.project/items/sub1/name: sub1 MAIN_MODULE_MANAGEMENT/customers/agorum.dev/logging/nodes/[ my.project ]/my.project/items/sub1/title: Sub Node 1

Hauptfunktionen

---

Die angebotenen Funktionen untergliedern sich in drei Klassen:

• die hier beschriebenen Hauptfunktionen
• Funktionen des Log-Objekts
• Funktionen zum Erstellen eines Log-Eintrags

init

Diese Funktion wird automatisch beim Laden der Bibliothek ausgeführt und ist dafür verantwortlich, die in der MetaDB definierten Log-Knoten anzulegen. Sie müssen diese im Normalfall nicht selbst aufrufen.

Syntax

logger.init();

Beispiel

let logger = require('/agorum/roi/customers/agorum.dev/js/lib/logger');

logger.init();

get

Erzeugt ein Log-Objekt für den angegebenen Knoten und gibt dieses zurück.

Auf diesem Objekt können diverse Funktionen verwenden, um mit dem Log-Knoten zu arbeiten.

Syntax

logger.get('<node name>');

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
name	Definiert den Namen des zu verwendenden Log-Knotens. Hierbei kann es sich um einen eingebauten Knoten, etwa CoreStatistic, handeln oder um einen selbst erstellten, wie den oben beschriebenen my.project.	Ja	–

Beispiel

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('my.project.sub1');

Funktionen des Log-Objekts

---

Die hier beschriebenen Funktionen beziehen sich auf einen konkreten Log-Knoten.

debug, info, warning, error

Beginnt die Erstellung eines Log-Eintrags der entsprechenden Stufe.

Auf dem hier zurückgegebenen Objekt können diverse Funktionen verwendet werden, um den Log-Eintrag zu befüllen und zu erstellen.

Syntax

log.debug();
log.info();
log.warning();
log.error();

clearSticky

Entfernt einen als sticky markierten Log-Eintrag wieder.

Syntax

log.clearSticky('<sticky key>');

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
key	Definiert den exakten Schlüssel, der für die Erstellung des Log-Eintrags verwendet wurde.	Ja	–

Beispiel

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('my.project.sub1');

log.clearSticky('my.sticky.key');

ifDebug

Ruft die übergebene Funktion auf, sofern sich dieser Knoten gerade im debug-Modus befindet.

Syntax

log.ifDebug(<fn>);

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
fn	Definiert die aufzurufende Funktion.	Ja	-

Beispiel

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('my.project.sub1');

log.ifDebug(() => {
  // do something
});

Verwendung

Diese Funktion verwenden Sie typischerweise, wenn zur Erstellung einer debug-Ausgabe weitere Schritte nötig sind, etwa dem Laden von Metadaten oder sonstige E/A-Operationen. Damit stellen Sie sicher, dass diese Schritte nur ausgeführt werden müssen, wenn der Log-Eintrag überhaupt sichtbar ist.

Funktionen zum Erstellen eines Log-Eintrags

---

Auf dem durch eine der Funktionen debug, info, warning oder error zurückgegebenen Log-Eintrags-Objekt sind die hier beschriebenen Funktionen vorhanden, mit denen dieser Eintrag Schritt für Schritt gefüllt und am Ende geschrieben werden kann.

detail, log

Diese Funktionen fügen dem Log-Eintrag eine oder mehrere Detailinformationen hinzu. Hierbei kann es sich um einfache Werte wie Zahlen und Strings oder auch komplexere Datenstrukturen wie verschachtelte Objekte, agorum core-Objekte oder JavaScript/Java-Fehler handeln.

Die Funktion log schließt den bisher erzeugten Log-Eintrag im Gegensatz zur Funktion detail auch ab und besitzt zusätzlich eine Sonderbehandlung für ihren ersten Parameter. Sofern es sich um einen String handelt, wird dieser außerdem als Log-Nachricht verwendet.

Syntax

entry.detail(<detail 1>, <detail 2>, ...);
entry.log(<detail 1>, <detail 2>, ...);

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
detail 1-n	Definiert die Detailinformation, die mit protokolliert wird.	Nein	-

Beispiel

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('my.project.sub1');
let objects = require('common/objects');

try {
  throw new Error('oops');
} catch (err) {
  log
    .info()
    .detail(123, '456')
    .detail({ a: [true, false] })
    .detail(err)
    .detail(objects.find('/'))
    .log('Something went wrong');
}

object

Fügt dem Log-Eintrag eine Referenz zu einem agorum core-Objekt hinzu.

Syntax

entry.object(<object>);

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
object	Definiert das hinzuzufügende agorum core-Objekt, entweder als Objektreferenz oder als numerische oder stringbasierte ID.	Ja	-

Beispiel

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('my.project.sub1');

log.debug().object(9999).log('root folder');

sticky

Markiert den Log-Eintrag als sticky, wodurch dieser im agorum core support tool separat angezeigt wird und (für warning und error) auch den zugehörigen Log-Knoten optisch hervorhebt.

Syntax

entry.sticky('<sticky key>');

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
key	Definiert einen eindeutigen Schlüssel, mit dem der Eintrag gekennzeichnet wird und mit dem er wieder entfernt werden kann.	Ja	-

Beispiel

let log = require('/agorum/roi/customers/agorum.dev/js/lib/logger').get('my.project.sub1');

let STICKY_KEY = 'my.sticky.key';

try {
  // ...

  // everything went well, remove the sticky entry, if it exists
  log.clearSticky(STICKY_KEY);
} catch (err) {
  // an error occurred, add or update the sticky entry
  log.error().sticky(STICKY_KEY).log(err);
}