#Logger

NocoBase bietet ein leistungsstarkes Logging-System, das auf pino basiert. Überall dort, wo Sie Zugriff auf den context haben, können Sie eine Logger-Instanz über ctx.logger abrufen. Diese Instanz dient dazu, wichtige Logs während der Laufzeit von Plugins oder des Systems zu erfassen.

#Grundlegende Verwendung

// Fatalen Fehler protokollieren (z. B. Initialisierungsfehler)
ctx.logger.fatal('Anwendungsinitialisierung fehlgeschlagen', { error });

// Allgemeine Fehler protokollieren (z. B. API-Request-Fehler)
ctx.logger.error('Daten konnten nicht geladen werden', { status, message });

// Warnungen protokollieren (z. B. Performance-Risiken oder unerwartete Benutzeraktionen)
ctx.logger.warn('Das aktuelle Formular enthält ungespeicherte Änderungen');

// Allgemeine Laufzeitinformationen protokollieren (z. B. Komponente geladen)
ctx.logger.info('Benutzerprofil-Komponente geladen');

// Debug-Informationen protokollieren (z. B. Statusänderungen)
ctx.logger.debug('Aktueller Benutzerstatus', { user });

// Detaillierte Trace-Informationen protokollieren (z. B. Rendering-Ablauf)
ctx.logger.trace('Komponente gerendert', { component: 'UserProfile' });

Diese Methoden entsprechen verschiedenen Log-Ebenen (von hoch nach niedrig):

#Log-Format

Jede Log-Ausgabe erfolgt im strukturierten JSON-Format und enthält standardmäßig die folgenden Felder:

Beispielausgabe:

{
  "level": 30,
  "time": 1730540153064,
  "pid": 12765,
  "hostname": "nocobase.local",
  "msg": "HelloModel rendered",
  "a": "a"
}

#Kontextbindung

ctx.logger injiziert automatisch Kontextinformationen, wie das aktuelle Plugin, Modul oder die Request-Quelle. Dadurch können Logs präziser ihrer Herkunft zugeordnet werden.

plugin.context.logger.info('Plugin initialized');
model.context.logger.error('Model validation failed', { model: 'User' });

Beispielausgabe (mit Kontext):

{
  "level": 30,
  "msg": "Plugin initialized",
  "plugin": "plugin-audit-trail"
}

#Benutzerdefinierter Logger

Sie können in Plugins benutzerdefinierte Logger-Instanzen erstellen, die die Standardkonfigurationen erben oder erweitern:

const logger = ctx.logger.child({ module: 'MyPlugin' });
logger.info('Submodule started');

Child-Logger erben die Konfiguration des Haupt-Loggers und fügen automatisch den Kontext hinzu.

#Hierarchie der Log-Ebenen

Pinos Log-Ebenen folgen einer numerischen Definition von hoch nach niedrig, wobei kleinere Zahlen eine geringere Priorität bedeuten.
Hier ist die vollständige Tabelle der Log-Ebenen-Hierarchie:

Pino gibt nur Logs aus, deren Ebene größer oder gleich der aktuell konfigurierten level-Ebene ist. Wenn die Log-Ebene beispielsweise info ist, werden debug- und trace-Logs ignoriert.

#Best Practices in der Plugin-Entwicklung

1. Verwenden Sie den Kontext-Logger
   Nutzen Sie ctx.logger in Plugin-, Modell- oder Anwendungskontexten, um automatisch Quellinformationen mitzuführen.

2. Unterscheiden Sie Log-Ebenen

   • Verwenden Sie error, um Geschäftsfehler zu protokollieren.
   • Verwenden Sie info, um Statusänderungen zu erfassen.
   • Verwenden Sie debug, um Debugging-Informationen für die Entwicklung aufzuzeichnen.

3. Vermeiden Sie übermäßige Protokollierung
   Insbesondere auf den debug- und trace-Ebenen wird empfohlen, diese nur in Entwicklungsumgebungen zu aktivieren.

4. Verwenden Sie strukturierte Daten
   Übergeben Sie Objektparameter anstelle von verketteten Zeichenfolgen. Dies erleichtert die Log-Analyse und -Filterung.

Durch die Befolgung dieser Praktiken können Entwickler die Plugin-Ausführung effizienter verfolgen, Probleme beheben und die Struktur sowie Erweiterbarkeit des Logging-Systems gewährleisten.