Lade...
 

Logging

Logging

Technische Dokumentation

Beim Logging protokolliert ClassiX® verschiedene Zustände, Fehlermeldung, Tätigkeiten usw. mit und schreibt diese in einem bestimmten Format in ein bestimmtes Medium, z.B. in eine Datei.

Eine extlnk.giflog4j-kompatible Logging-Bibliothek übernimmt hier den technischen Part.

Die Konfigurationsdatei befindet sich im System-Verzeichnis des ClassiX®-Systems (siehe CX_SYSTEM) und heißt logging.ini. Der Dateiname kann über die Kommandozeile oder per Umgebungsvariable verändert werden:

  • Kommandozeilenparameter -l: cx_osr.exe -l mylog.ini
  • Umgebungsvariable: SET CX_LOGGING_INI=mylog.ini

Die Umgebungsvariable hat die höchste Priorität.

Die Konfigurationsdatei besteht aus zwei Teilen: Den Loggern und den Ausgabemedien. Im folgenden Beispiel sind zwei Logger beschrieben, die in ein Ausgabemedium (eine Datei) schreiben:

Aufbau der Logging.ini
#this specifies the default Level: INFO
log4cplus.rootLogger=INFO, FILE_LOGGER

log4cplus.OrganizeLogsByDate=true

log4cplus.appender.FILE_LOGGER=log4cplus::RollingFileAppender
log4cplus.appender.FILE_LOGGER.File=${CX_LOGFILENAME}.log
log4cplus.appender.FILE_LOGGER.ImmediateFlush=true
log4cplus.appender.FILE_LOGGER.Append=true
log4cplus.appender.FILE_LOGGER.MaxFileSize=5MB
log4cplus.appender.FILE_LOGGER.MaxBackupIndex=10
log4cplus.appender.FILE_LOGGER.layout=log4cplus::PatternLayout
log4cplus.appender.FILE_LOGGER.layout.ConversionPattern=%D{%Y-%m-%d %H:%M:%S,%q} %5x %5p %c - %m%n

#this specifies, which loggers should be appended at which level
log4cplus.logger.cx.main=ALL
log4cplus.logger.cx.pool=WARN

Option: log4cplus.OrganizeLogsByDate

198837

Ist diese Option gesetzt, dann ergänzt ClassiX die Umgebungsvariablen CX_LOGFILENAME und CX_CHANGELOGFILENAME um einen Datumspräfix (/YYYY/MM/DD/Logfilename), damit das SystemOut-Verzeichnis nicht mit Dateien überläuft und man recht einfach alte Logs löschen kann.

ACHTUNG: Es kann vorkommen, dass Logs vom WebService vom Vortag oder noch früher stammen. Es ist dann sehr schwer diese Logs zu finden, wenn man diese Option gesetzt hat.

 

Logger

Ein Logger ist ein Objekt, das alle Meldungen einer bestimmten Kategorie (und deren Unterkategorien) sammelt und in ein oder mehrere Medien schreibt. Die Meldungen kommen vom ClassiX®-System selbst, über SystemObject::Log können aber auch selbst solche Meldungen erzeugt werden.

Im Beispiel wird der Ur-Logger "rootLogger" mit dem Level INFO und dem Medium FILE_LOGGER konfiguriert. Alle anderen Logger sind von "rootLogger" abgeleitet, erben also dessen Eigenschaften. ClassiX®-Logger beginnen üblicherweise mit "cx.".

Die Meldungen "Programmstart" und "Programmende" z.B. werden dem Logger "cx.main" zugestellt. Damit diese immer im Logbuch erscheinen, wird der Logging-Level auf ALL hoch gestuft.

Logger Bedeutung Hinweis
cx.access 193468,
cx.change 198900

Spezieller Logger, der alle Objektänderungen während DrainWindow rausloggt sobald er auf TRACE gestellt wird. (Hinweise zur Einrichtung)
cx.access soll künftig durch cx.change abgelöst werden. Vorübergehend sollten beide gleich definiert werden.

 
cx.accesscontrol Meldungen zu CX_ACCESS_CONTROL Ab DLL-Version 177533
cx.app Allgemeine Meldungen der Applikation, z.B. Fehlermeldungen oder Meldungen via CX_SYSTEM_OBJECT::Log  
cx.app.crashdumps Unter INFO Statusmeldung, falls sich ClassiX mit einem neuen OOPS-Prozess verbunden hat.

Unter WARN Warnung, falls der Pfad der Crashdump-Datei gekürzt werden musste.
 
cx.arena Meldungen der Arena (Speicherverwaltung)  
cx.as Meldungen der Address-Space Verwaltung (Marker)  
cx.basic Meldungen der Basisklassen bzw. der Basis-Infrastruktur  
cx.basic.fcond    
cx.basic.formula    
cx.basic.numeric Logger für CX_NUMERIC. Loggt Fehler beim Export oder Format.  
cx.basic.string    
cx.basic.unit    
cx.birt Informationen zur Benutzung von Birt als Reporting-Tool  
cx.dbase

Logger für CX_DBASE_FILE Klasse.
Gibt unter INFO Meldungen über das Vorhandensein von MNEMO-Dateien aus.

Gibt Warnungen und Fehler bei ungültigem Format oder Fehlern aus.

 
cx.dbutil Fehlermeldungen bei Überprüfung der Datenbank  
cx.dict

Logger für das Parsen des Dictionary-Segments der .ini-Datei.
Gibt unter DEBUG aus, welche Slots durch welcher Überschrieben oder Versteckt werden.

Ab Dll-Version 205351
cx.file

Logger für CX_ASCII_FILE Klasse. Gibt Fehlermeldungen bei zu kleinem Puffer aus.

 
cx.formula Logger für CX_FORMULA Klasse. Gibt Warnungen bei ungültigen Formeln aus.  
cx.gc Garbage-Collection-Läufe (siehe auch CX_GARBAGE_LOGGING_THRESHOLD)  
cx.instantview.parser

Meldungen des InstantView®-Parsers 

Unter TRACE gibt dieser Logger die Zustandsübergänge des Zustandsautomaten aus, der die Sprache definiert.

Unter DEBUG gibt der Parser jede Datei aus, die geparst wird.

Unter WARN werden Warnungen beim Parsen des Codes ausgegeben, zum Beispiel bei mehrfach definierten Variablen oder bei mehrdeutiger Vererbung.

 
cx.ivservices Loggt ausführlichere Warnungen und Fehlermeldungen, bei Fehlern im Webserver oder Webclient.
Auf DEBUG werden alle eingehenden HTTP-Requests vollständig geloggt.
 
cx.ivservices.websocket

Gibt auf INFO Status und Verbindungsinformationen zur MorphIT-Verbindung aus, sowie eventuell auftretende Fehler.

Unter DEBUG werden nur die Nachrichtentypen der eingehenden Nachrichten geloggt.

Unter TRACE werden alle eingehenden und ausgehenden Websocket-Nachrichten vollständig rausgeloggt. (Sehr teuer)

 
cx.ivservices.morphit

Unter WARN werden Warnungen zu eingehenden MorphIT-Nachrichten mit ungültigem Format ausgegeben, sowie Problemen beim MorphIT-Export der Oberfläche.

Unter INFO werden Statusinformationen zur MorphIT-Verbindung ausgegeben.

 
cx.lic Meldungen des Lizenzmanagers  
cx.listview Meldungen der ListView  
cx.locale

Unter DEBUG wird beim Einlesen der Locales jeder geladene Locale-Eintrag ausgegeben.

Unter INFO wird das eingestellte Locale bei der Initialisierung und bei jedem Locale-Wechsel ausgegeben.

 
cx.login Meldungen zum Login (LoginSID) Ab DDL-Version 177535
cx.main Meldung über Programmstart und -ende, laden von DLLs
Unter DEBUG wird ausgegeben, welche DLL an welche Adresse geladen wurde.
 
cx.model Informationen zu allgemeinen Model-Klassen. Wird weiter unterteilt nach spezifischen Model-Klassen.  
cx.model.dict Dictionaries und Indexes loggen unter diesem Eintrag  
cx.model.monitor    
cx.model.txn Gibt Informationen zu den Funktionen CX_TRANSACTION::Predecessor/Successsor... aus.  
cx.ole

Logging zu den OLE-, COM-, ActiveX-relevanten Klassen.

Unter TRACE werden die einzelnen Schritte beim Mergen ausführlich geloggt. Zudem wird jeder COM-Methodenaufruf geloggt.

Unter INFO werden alle COM-Aufrufe geloggt, die länger als 50ms gedauert haben.

OLE-Widgets loggen unter cx.ui.ole

 
cx.ole.xml Gibt Fehlermeldungen und Warnungen zu den Klassen CX_EXCEL_XML(xlsx) und CX_WORD_XML(docx) aus.  
cx.ole.xml.search Gibt unter DEBUG einige Informationen aus über die durchsuchten Knoten eines XML-Dokuments.  
cx.omgr

Meldungen des Objekt-Managers

Unter INFO werden beim Start wichtige Informationen für die Analyse von Crashdumps ausgegeben.

 
cx.omgr.db

Unter INFO werden die einzelnen Schritte beim Öffnen der Datenbank ausgegeben. Außerdem wird bei jedem Öffnen der Datenbank geloggt, in welchem Modus sie geöffnet wird. 

 
cx.omgr.osversion ObjectStore-Version und eigene ObjectStore-ID  
cx.oops

Loggt im OOPS Fehler und Warnungen beim Ausführen von Tasks.

Unter INFO werden in ClassiX und im OOPS grundlegende Statusinformationen ausgegeben.

Unter DEBUG werden ausführliche Informationen zur Verbindung und Abarbeitung der Tasks ausgegeben.

Damit der OOPS ein eigenes Logfile schreibt, muss die Umgebungsvariable CX_OOPS_LOG gesetzt sein.
cx.perf Performance logging  
cx.perf.iv Performance informationen bezgl. Instantview-Statements.
Im DEBUG-Level wird zu jedem Statement ein Eintrag erzeugt, das Logfile wächst dann also sehr schnell.
Im INFO-Level werden die Zeiten gesammelt und je nach Einstellung von CX_PERF_LOGGING_THRESHOLD_PAGE und CX_PERF_LOGGING_THRESHOLD_TIME geloggt.
 
cx.perf.db Performance informationen bezgl. Datenbank (ggw. nicht verwendet)  
cx.pool Meldungen von Pool (Speicherverwaltung)
Unter DEBUG werden Meldungen bei Reallocation von Pools ausgegeben.
 
cx.print Meldungen von der Druckumgebung (ggw. lediglich ASCII-Druck)  
cx.process Hier werden Informationen geloggt wenn ClassiX eine andere Anwendung (einen anderen Prozess) startet.  
cx.query Query-relevante Meldungen  
cx.rate

An- und Abmelden von Rate-Tables (einschließlich Overwrite)
Unter DEBUG werden Inkonsistenzen in Tabellen und jede Anpassung der Tabellen geloggt.

Außerdem werden Umrechnungsfehler über diesen Logger ausgegeben.

 
cx.remote Meldungen der Remote-Schnittstellen (z.B. CORBA)  
cx.remote.corba CORBA bezogene Meldungen der Remote-Schnittstelle  
cx.remote.data Meldungen bezgl. über die Remote-Schnittstelle gesendeter und empfangener Daten  
cx.rqdsp Request-Dispatcher-Meldungen (Befehlsausführung)  
cx.rqdsp.asf Address-Space-Full-Fehler  
cx.rqdsp.deadlock Unterkategorie für das Deadlock-Handling  
cx.rqdsp.deadlock.rcb Ausgabe der Resume Control Blocks (siehe auch CX_DEBUG_RCB_QUEUE)  
cx.rqdsp.deprecated

Ausgabe von veralteten Sprachkonstrukten/Sprachfeatures, die in Zukunft nicht mehr unterstützt werden. Die Ausgabe erfolgt im WARN-Level.

Der Logger sollte im Produktivbetrieb bei Kunden deaktiviert werden, indem er in der logging.ini auf OFF gesetzt wird.

Einige Warnungen werden nur im DEBUG-Level ausgegeben, wenn sie potenziell häufig auftreten können und nur langsam behoben werden können.
Um alle deprecation-Warnungen zu sehen, sollte der Logger auf ALL gesetzt werden.

 
cx.rqdsp.stack Warnung bei Reallokation des IV-Stacks. Ab DLL-Version 179664
cx.rqdsp.time Laufzeiten der InstantView-Makros (siehe auch CX_MACRO_LOGGING_THRESHOLD) Nur einsetzen (=DEBUG), wenn aktiv Zeitmessungen vorgenommen werden. Wirkt sich sehr leistungsmindernd aus
cx.tapi Debugging Informationen zur TAPI (Telephone API) Schnittstelle  
cx.test Test-Meldungen  
cx.threading Informationen zum Threadingverhalten von ClassiX  
cx.threading.timetrigger CX_TIMED_TRIGGER schreibt Informationen zu seinen Events  
cx.threading.critsec Meldungen, wenn CriticalSections benutzt werden  
cx.txn

Transaction-Manager (Monitor für Datenbank-Transaktionen) (siehe auch CX_TXN_LOGGING_THRESHOLD)

Unter TRACE & DEBUG werden alle Transaktionsschritte geloggt und unter INFO  werden abgeschlossene Transaktionen ausgegeben.

 
cx.stringstorage Schreibt eine Warnung, falls die Kundenspezifische Strings-Datei nicht geschrieben werden kann.  
cx.ui Meldungen betreffs der Oberfläche. Wird weiter unterteilt nach Widgettypen  
cx.ui.group    
cx.ui.listview    
cx.ui.oboxedit    
cx.ui.ole    
cx.ui.olecontrol    
cx.ui.notebook    
cx.ui.tray Meldungen des Trays  
cx.ui.treeview    

Log-Level-Einstellungen eines Loggers gelten immer auch für den untergeordneten Logger (es sei denn, für diesen untergeordneten wird der Level wieder umdefiniert):

log4cplus.logger.cx=INFO                    # Für alle ClassiX®-Logger: INFO-Level
log4cplus.logger.cx.instantview=WARN        # InstantView®-Meldungen: Nur Warnungen und Fehler
log4cplus.logger.cx.rqdsp=ERROR             # Request-Dispatcher: Nur Fehler, ...
log4cplus.logger.cx.rqdsp.deadlock=WARN     # ... aber bei Deadlock-Meldungen auch Warnungen

Medien

Jede Logging-Zeile kann in mehrere Medien ausgegeben werden. Z.Zt. werden folgende Medien unterstützt:

  • Bildschirm (ConsoleAppender)
  • Datei (FileAppender, RollingFileAppender, DailyRollingFileAppender)
  • System-Log (SyslogAppender, NTEventLogAppender)
  • Netzwerk (SocketAppender)

ClassiX® legt von sich aus die Umgebungsvariable CX_LOGFILENAME an, die einen Standard-Dateinamen inkl. Pfad enthält. Der Pfad entspricht dem System-Verzeichnis von ClassiX®, der Dateiname beginnt mit CX_, gefolgt vom Rechnernamen, Benutzernamen und Prozess-ID, Endung ist .log.
Falls die Umgebungsvariable CX_LOGFILENAME bereits gesetzt ist, wird sie für den laufenden ClassiX-Prozess überschrieben.
Um den Dateinamen der Log Datei manuell zu vergeben muss in der logging.ini der Eintrag entsprechend angepasst werden.

log4cplus.appender.FILE_LOGGER.File=${MY_FILE_NAME}.log       

 

Davon ist allerdings dringend abzuraten, da dann alle Events in nur eine Datei geschrieben werden, was eine Zuordnung zu einem Benutzer erschwert. Allerdings kann an dieser Stelle auf jede beliebige Umgebungsvariable zugegriffen werden, z.B. ${COMPUTERNAME} oder ${USERNAME}.

Der Name der Log-Datei kann alternativ auch über die Umgebungsvariable CX_FORCED_LOGFILENAME geändert werden. CX_LOGFILENAME wird von ClassiX dann auf den Wert von CX_FORCED_LOGFILENAME gesetzt, wenn diese Variable definiert ist.

 

Layout

Logging-Zeilen können individuell gestaltet werden (s. extlnk.giflog4cpp-Dokumentation für Details):

Zeichen (mit Prozent anzugeben) Bedeutung
D, d Zeitstempel (D = lokale Zeit, d = UTC)
  Y, y Jahr (4- bzw. 2-stellig)
  m Monat
  d Tag
  H Stunde
  M Minute
  S Sekunde
  q Millisekunde
p Level
c Kategorie
m Text
n Zeilenumbruch

Level

Es gibt sechs verschiedene Level-Stufen:

Level Beschreibung
TRACE Feinste Stufe, z.T. werden einzelne Funktionsaufrufe geloggt
DEBUG Sehr detaillierte Informationen, die zur technischen Fehlersuche genutzt werden können
INFO Allgemeine Informationen
WARN Warnungen
ERROR Fehler
FATAL Höchste Stufe: Fehler, der zum Programmabbruch führt

Wird in der logging.ini ein bestimmter Level eingestellt, werden alle Meldungen protokolliert, die diesen Level oder einen höheren haben. ALL bedeutet außerdem alle Meldungen, OFF bedeutet keine Meldungen.

Grundsätzlich sollten die Stufen DEBUG, TRACE, ALL in Produktivsystemen mit Bedacht eingesetzt werden, da ihr Einsatz das System stark ausbremsen kann und sie primär zum Nachvollziehen von Problemen geeignet sind.

Sind keine besonderen Voraussetzungen zu beachten, so sind die folgenden Logger-Einstellungen empfehlenswert:

Standard-Logger

#this specifies the default Level: INFO
log4cplus.rootLogger=INFO, FILE_LOGGER

log4cplus.OrganizeLogsByDate=true

log4cplus.appender.FILE_LOGGER=log4cplus::RollingFileAppender
log4cplus.appender.FILE_LOGGER.File=${CX_LOGFILENAME}_change.log
log4cplus.appender.FILE_LOGGER.ImmediateFlush=true
log4cplus.appender.FILE_LOGGER.Append=true
log4cplus.appender.FILE_LOGGER.MaxFileSize=5MB
log4cplus.appender.FILE_LOGGER.MaxBackupIndex=10
log4cplus.appender.FILE_LOGGER.layout=log4cplus::PatternLayout
log4cplus.appender.FILE_LOGGER.layout.ConversionPattern=%D{%Y-%m-%d %H:%M:%S,%q} %5x %5p %c - %m%n

#this specifies, which loggers should be appended at which level
log4cplus.logger.cx.main=ALL
log4cplus.logger.cx.instantview.parser=ERROR
log4cplus.logger.cx.omgr.db=WARN
log4cplus.logger.cx.ole=WARN
log4cplus.logger.rqdsp.deprecated=OFF

 

 Änderungshistorie-Logger

Für die Nachverfolgung von Änderungen, die von Nutzern an Objekten im Zuge von DrainWindow durchgeführt werden, gibt es den cx.change-Logger (bis Dll-Version 198898 noch cx.access), der eine besondere Bedeutung hat. Sobald dieser auf TRACE gesetzt wird, wird ein Mechanismus angemeldet, der jede Objektänderung und jede Transaktion als JSON-Objekt (für einfacheres Parsen) ausgibt. Da hierbei sehr viele Daten geloggt werden, die von den regulären Log-Ausgaben getrennt werden sollten, empfiehlt es sich hierfür einen eigenen Log-Appender zu definieren.

ClassiX definiert hierfür eine eigene Umgebungsvariable CX_CHANGELOGFILENAME (auf Basis von CX_CHANGELOG_DIR), die in der logging.ini verwendet werden kann. Ist CX_CHANGELOG_DIR nicht gesetzt, dann wird nach System\Changelog geschrieben.

Um den Änderungshistorie-Logger zu aktivieren, muss nur folgender Block and die logging.ini hinten angefügt werden:

log4cplus.appender.CHANGE_LOGGER=log4cplus::FileAppender
log4cplus.appender.CHANGE_LOGGER.File=${CX_CHANGELOGFILENAME}_change.log
log4cplus.appender.CHANGE_LOGGER.ImmediateFlush=true
log4cplus.appender.CHANGE_LOGGER.BufferSize=100000
log4cplus.appender.CHANGE_LOGGER.Append=true
log4cplus.appender.CHANGE_LOGGER.layout=log4cplus::PatternLayout
log4cplus.appender.CHANGE_LOGGER.layout.ConversionPattern=%D{%Y-%m-%d %H:%M:%S,%q} %8x %5p %c - %m%n

log4cplus.logger.cx.change=TRACE, CHANGE_LOGGER
log4cplus.additivity.cx.change=false

Kurze Erklärung:

Der neu definierte CHANGE_LOGGER-Appender schreibt in einer log-Datei mit dem Suffix _change und formatiert die Ausgabe ähnlich, wie der reguläre Logger. Nachdem der Appender definiert wurde, wird der cx.change-Logger auf das TRACE-Level gesetzt und dem CHANGE_LOGGER-Appender zugewiesen. Die letzte Zeile verhindert, dass ein Event, dass der cx.change-Logger nicht loggt, an den cx-Logger weitergereicht wird.

Whitelist/Blacklist

199065
Um die geloggte Datenmenge weiter einzuschränken kann über SetLoggedClasses, SetNotLoggedClasses eine Whitelist bzw. Blacklist definiert werden. Der Change-Logger loggt nur DrainWindow-Befehle, die sich auf Objekte beziehen, die von mindestens einer Klasse aus der Whitelist abgeleitet sind und von keiner Klasse aus der Blacklist abgeleitet sind. Über Whitelist&Blacklist lässt sich so das Logging auf die Klassen von wirklich relevanten Bestandsdaten beschränken. Dadurch wird das System auch weiter beschleunigt.

Wenn nichts gesetzt wurde, dann startet der Change-Logger mit eine Whitelist von CX_CLASS und einer leeren Blacklist, damit alle Klassen geloggt werden.

200176
Der Changelogger loggt nun alle Befehle, die den Zustand von persistenten Objekten oder Collections verändern. Um die Operationen, die auf Collections durchgeführt werden einzuschränken, kann der Typ COLL in die Blacklist aufgenommen oder aus der Whitelist entfernt werden (ab jetzt Teil der Default-Whitelist). Die Performance des Loggers lässt sich durch die Wahl einer geeigneten Buffer-Größe (BufferSize in der logging.ini) für den Logger etwas optimieren. Der Changelogger sammelt die Log-Events (solange der Buffer ausreicht) im Speicher bis ein CommitTXN oder AbortTXN kommt. 

InstantView