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

Die erzeugten Log-Einträge können im agorum core support tool über Show Log eingesehen und über Configure Log nach Severity gefiltert werden, siehe Schaltflächen im Log.

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.

MetaDB-Felder für Log-Knoten

Feld	Beschreibung	Pflicht
name	Der technische Name des Log-Knotens. Dieser wird in der get()-Funktion verwendet.	Ja
title	Der Anzeigetitel im agorum core support tool.	Ja
description	Eine optionale Beschreibung des Log-Knotens für zusätzliche Informationen.	Nein
parent	Optionale Angabe eines übergeordneten Knotens. Überschreibt die automatische Hierarchie basierend auf der MetaDB-Struktur.	Nein

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 verwendet werden, 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();

 

Rückgabewert

Ein neues Builder-Objekt zum Erstellen des Log-Eintrags.

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	-

 

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.

 

Beispiel

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

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

 

Funktionen zum Erstellen eines Log-Eintrags

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

detail

Diese Funktion fügt 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.

Syntax

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

Parameter

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

 

Rückgabewert

Ein neues Builder-Objekt mit den hinzugefügten Details.

 

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');
}

log

Diese Funktion schließt die Erstellung des Log-Eintrags ab und schreibt ihn. Sie besitzt eine Sonderbehandlung für ihren ersten Parameter.

 

Syntax

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

 

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
first	Erster Parameter. Falls es sich um einen String handelt, wird dieser als Haupt-Nachricht des Log-Eintrags verwendet. Andernfalls wird er als Detail hinzugefügt.	Nein	–
detail 2-n	Alle weiteren Parameter werden ausschließlich als Details hinzugefügt (siehe detail).	Nein	–

 

Verhalten der log()-Funktion

• Erster Parameter ist ein String: Wird als Haupt-Nachricht des Log-Eintrags verwendet. Alle weiteren Parameter werden nur als Details hinzugefügt.
• Erster Parameter ist kein String: Alle Parameter (einschließlich des ersten) werden als Details hinzugefügt. Die Haupt-Nachricht bleibt leer.
• Keine Parameter: Nur die zuvor via detail() hinzugefügten Informationen werden protokolliert.

 

Beispiele

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

// Beispiel 1: Nachricht mit Details
log.info().detail('User ID:', userId).log('User logged in successfully');

// Beispiel 2: Nur Details, keine explizite Nachricht
log.debug().detail('Processing', itemCount, 'items').log();

// Beispiel 3: Erster Parameter kein String
log.warning().log(errorCode, 'Additional info');

// Beispiel 4: Mehrere Parameter
log.error().log('Error occurred', errorCode, errorDetails);

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);
}