Logging
Technical documentation
During logging, ClassiX® logs various states, error messages, activities etc. and writes them in a certain format into a certain medium, e.g. into a file.
A 
log4j-compatible logging library takes over the technical part here.
The configuration file is located in the system directory of the ClassiX® system (see CX_SYSTEM) and is called logging.ini. The file name can be changed via the command line or via environment variable:
- Command line parameters -l: cx_osr.exe -l mylog.ini
- Environment variable: SET CX_LOGGING_INI=mylog.ini
The environment variable has the highest priority.
The configuration file consists of two parts: The loggers and the output media. The following example describes two loggers that write to an output medium (a file):
#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
198837If this option is set, ClassiX adds a date prefix (/YYYY/MM/DD/Logfilename) to the environment variables CX_LOGFILENAME and CX_CHANGELOGFILENAME, so that the SystemOut directory does not overflow with files and you can easily delete old logs.
ATTENTION: It can happen that logs from the WebService are from the previous day or even earlier. It is then very difficult to find these logs if this option is set.
Logger
A logger is an object that collects all the entries of a certain category (and its subcategories) and writes them to one or more media. The messages come from the ClassiX® system itself, but SystemObject::Log can also be used to create such messages.
In the example, the original logger "rootLogger" is configured with the level INFO and the medium FILE_LOGGER. All other loggers are derived from "rootLogger", so they inherit its properties. ClassiX® loggers usually start with "cx.
The messages "Programme start" and "Programme end", for example, are sent to the logger "cx.main". To ensure that these always appear in the logbook, the logging level is raised to ALL.
| Logger | Meaning | Note |
|---|---|---|
193468 | Replaced by cx.change. No longer supported as of Dll version 223726. | |
| cx.change 198900 | Special logger which logs all object changes during DrainWindow as soon as it is set to TRACE. (notes on setup) | |
| cx.access control | Messages for CX_ACCESS_CONTROL | From DLL version 177533 |
| cx.app | General application messages, e.g. error messages or messages via CX_SYSTEM_OBJECT::Log Under DEBUG, when loading source files (also .ini, .ext, ...), it is output in which directories were searched and where the files were found. | |
| cx.app.crash dumps | Under INFO Status message, if ClassiX has connected to a new OOPS process. Under WARN Warning, if the path of the crash dump file had to be shortened. | |
| cx.arena | Under DEBUG, the memory size used is logged in bytes when the arena is initialised. | |
| cx.as | Messages of the Address-Space Management (Marker) Since 64-bit, AS handling is no longer performed. | |
| cx.basic | Reporting of the basic classes or basic infrastructure | |
| cx.basic.numeric | Logger for CX_NUMERIC. Logs errors during export or format. | |
| cx.basic.string | Logs warnings during string export of CX_STRINGsthat are too long. | |
| cx.basic.unit | ||
| cx.birt | Information on using Birt as a reporting tool | |
| cx.dbase | Logger for CX_DBASE_FILE class. Outputs warnings and errors when the format or errors are invalid. | |
| cx.dbutile | Error messages when checking the database | |
| cx.dict | Logger for parsing the dictionary segment of the .ini file. | From Dll version 205351 |
| cx.file | Logger for CX_ASCII_FILE class. Outputs error messages if the buffer is too small. | |
| cx.formula | Logger for CX_FORMULA class. Outputs warnings for invalid formulas. Under DEBUG, before binding the variables, the plugspace is displayed and for each variable, to which value it was bound. | From Dll version 217199 |
| cx.gc | Garbage Collection Under DEBUG, for each run of the garbage collection, it is logged how many objects are protected and how many objects have been released. | see also CX_GARBAGE_LOGGING_THRESHOLD |
| cx.gc.time 229962 | Under DEBUG , each garbage collection run logs how much time it took and how much time was spent in each phase. | |
| cx.instantview.parser | InstantView® parser messages Under TRACE this logger outputs the state transitions of the state machine that defines the language. Under DEBUG the parser outputs every file that is parsed. Under WARN, warnings are issued when the code is parsed, for example in the case of variables defined several times or in the case of ambiguous inheritance. | |
cx.ivs Renamed as of Dll version 224641 | Logs more detailed warnings and error messages, in case of errors in the web server or web client. On DEBUG, all incoming HTTP requests are fully logged. | |
cx.ivs.websocket | Outputs status and connection information on the MorphIT connection and any errors that may occur on INFO. | |
cx.ivs.morphit | Under WARN, warnings about incoming MorphIT messages with invalid format are displayed, as well as problems with MorphIT export of the interface. Under INFO status information about the MorphIT connection is displayed. | |
| cx.ivs.morphit.paths | Logged under WARN if asset paths cannot be translated into URLs that are relative to the server. Under DEBUG it is logged to which relative URL each local asset path was translated. | |
| cx.lic | Messages of the licence manager | |
| cx.locale | Under DEBUG, every loaded locale entry is output when the locales are read in. Under INFO, the set locale is displayed during initialisation and each time the locale is changed. | |
| cx.login | Login messages (LoginSID) | As of Dll version 177535 |
| cx.main | Message about programme start and end, loading of DLLs DEBUG shows which DLL was loaded to which address. | |
| cx.model | Information on general model classes. Is further subdivided according to specific model classes. | |
| cx.model.dict | Dictionaries and Indexes log under this entry. The FixKeyOwnership method logs fixed problems under WARN and all key objects that are deleted (and recreated) under DEBUG. | |
| cx.model.txn | Gives information about the functions CX_TRANSACTION::Predecessor/Successsor... . | |
| cx.ole | Logging to the OLE, COM, ActiveX-relevant classes. Under TRACE the individual steps of the merging process are logged in detail. In addition, every COM method call is logged. Under INFO all COM calls are logged which have lasted longer than 50ms. OLE widgets log under cx.ui.ole | |
| cx.ole.xml | Outputs error messages and warnings for the classes CX_EXCEL_XML(xlsx) and CX_WORD_XML(docx). | |
| cx.ole.xml.search | Outputs some information about the scanned nodes of an XML document under DEBUG. | |
| cx.omgr | Messages of the object manager Under INFO, important information for the analysis of crash dumps is displayed at startup. | |
| cx.omgr.db | Under INFO, the individual steps are displayed when the database is opened. In addition, each time the database is opened, the mode in which it is opened is logged. | |
| cx.omgr.osversion | ObjectStore version and own ObjectStore ID | |
| cx.omgr.set.clustering 223726 | If the CX_CHECK_CLUSTERED_SET_INSERTS variable is set, then clustering-related performance problems are logged. Under WARN, the problematic sets and inserted objects, as well as the current command, are logged. Under DEBUG, all elements are always checked for larger sets in order to obtain an exact number of elements in the fullest bucket. Under TRACE, the complete call stack is logged in addition to the current command. | |
| cx.oops | Logs errors and warnings in OOPS when executing tasks. Under INFO , basic status information is output in ClassiX and in OOPS. Under DEBUG , detailed information on the connection and processing of the tasks is output. | The environment variable CX_OOPS_LOG must be set for the OOPS to write a log file. |
| cx.pool | Messages from Pool (memory management) Under DEBUG messages are issued when pools are relocated. | |
| cx.print | Messages from the printing environment (ASCII printing only) | |
| cx.process | Here information is logged when ClassiX starts another application (process). | |
| cx.query | Messages for activating/deactivating indexes | |
| cx.rate | Registering and deregistering rate tables (including overwrite) In addition, conversion errors are output via this logger. | |
| cx.remote | Messages from the remote interfaces (e.g. CORBA) | |
| cx.remote.corba | CORBA-related messages from the remote interface | |
| cx.remote.data | Messages concerning data sent and received via the remote interface | |
| cx.rqdsp | Request dispatcher messages (command execution) | |
| cx.rqdsp.asf | Address Space Full Error | |
| cx.rqdsp.deadlock | Subcategory for deadlock handling | |
| cx.rqdsp.deadlock.rcb | Output of the resume control blocks (see also CX_DEBUG_RCB_QUEUE) | |
| cx.rqdsp.deprecated | Output of obsolete language constructs/language features that will not be supported in the future. The output is at WARN level. The logger should be deactivated in productive operation at customer sites by setting it to OFF in logging.ini. Some warnings are only issued at DEBUG level if they are potentially frequent and can only be resolved slowly. | |
| cx.rqdsp.recursion 218706 | When the call stack reaches the limit of 1000, the last 50 entries of the call stack are logged under WARN. At the same time the limit is doubled. This warning serves to detect procedures that crash the ClassiX process by endless recursion. | |
| cx.rqdsp.resetModules 227185 | Logger for the ResetModules command. Under DEBUG, all modules are logged, which modules are protected from ResetModules and why. And at the end it is logged how many modules were reset. Under TRACE, the name of each module that is reset is logged. | |
| cx.rqdsp.stack | Warning when reallocating the IV stack. | From DLL version 179664 |
| cx.rqdsp.time | Runtimes of InstantView macros (see also CX_MACRO_LOGGING_THRESHOLD) | Only use (=DEBUG) if time measurements are actively made. Has a very performance-reducing effect |
| cx.tapi | Debugging information about the TAPI (Telephone API) interface | |
| cx.test | Test messages | |
| cx.threading | Information on the threading behaviour of ClassiX | |
| cx.threading.timetrigger | CX_TIMED_TRIGGER writes information about its events. DEBUG logs in detail when a trigger is created, activated, deactivated, deleted and when which message is triggered. | |
| cx.threading.critsec | Messages when CriticalSections are used | |
| cx.txn | Transaction Manager (monitor for database transactions) (see also CX_TXN_LOGGING_THRESHOLD) Under DEBUG all transaction steps are logged. | |
| cx.txn.retry 224453 | Under DEBUG, each intercepted deadlock/lock timeout is logged within RetryTXN. Under WARN, a warning is issued if an AbortTXN is used within RetryTXN and no cancel follows. | |
| cx.stringstorage | Writes a warning if the custom string file cannot be written. | |
| cx.ui | Messages concerning the surface. Is further subdivided according to widget types | |
| cx.ui.group | ERROR = error message if the group widget cannot be drawn. | |
| cx.ui.listview | DEBUG = Additional information during access path evaluation. ERROR = Error during event handling | |
| cx.ui.oboxedit | DEBUG = Logs the events OBOX_UP/OBOX_DOWN | |
| cx.ui.ole | DEBUG = Logs each MLOleBoxcreated. | |
| cx.ui.olecontrol | WARN = Different warnings in case of errors in the control. | |
| {{%%!1!%%}} | {{%%!2!%%}} | |
| cx.ui.tray | Messages of the tray | |
| cx.ui.treeview | ERROR = Error in the selection logic. |
Log level settings of a logger always apply to the subordinate logger (unless the level is redefined for this subordinate logger):
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
Media
Each logging line can be output to several media. Currently the following media are supported:
- Screen (ConsoleAppender)
- File (FileAppender, RollingFileAppender, DailyRollingFileAppender)
- System-Log (SyslogAppender, NTEventLogAppender)
- Network (SocketAppender)
ClassiX® automatically creates the environment variable CX_LOGFILENAME, which contains a standard file name including path. The path corresponds to the system directory of ClassiX®, the file name starts with CX_ followed by the computer name, user name and process ID, ending with .log .
If the environment variable CX_LOGFILENAME is already set, it is overwritten for the running ClassiX process.
In order to assign the log file name manually, the entry in logging.ini must be adjusted accordingly.
However, this is strongly discouraged, as all events are then written to only one file, which makes it difficult to assign them to a user. However, any environment variable can be accessed at this point, e.g. ${COMPUTERNAME} or ${USERNAME}.
Alternatively, the name of the log file can be changed using the environment variable CX_FORCED_LOGFILENAME. CX_LOGFILENAME is set by ClassiX to the value of CX_FORCED_LOGFILENAME if this variable is defined.
Layout
Logging lines can be designed individually (see log4cpp documentation for details):
| Character (to be indicated with percent) | Meaning |
|---|---|
| D, d | Time stamp (D = local time, d = UTC) |
| Y, y | Year (4 or 2 digits) |
| m | month |
| d | Day |
| H | hour |
| M | minute |
| S | Second |
| q | Millisecond |
| p | Level |
| c | Category |
| m | Text |
| n | Line break |
Level
There are six different levels:
| Level | Description |
|---|---|
| TRACE | Finest level, sometimes individual function calls are logged |
| DEBUG | Very detailed information that can be used for technical troubleshooting |
| INFO | General Information |
| WARN | Warnings |
| ERROR | Error |
| FATAL | Highest level: error that leads to program abort |
If a certain level is set in logging.ini, all messages that have this level or higher will be logged. ALL also means all messages, OFF means no messages.
In principle, the DEBUG, TRACE, ALL stages should be used with caution in productive systems, as their use can slow down the system considerably and they are primarily suitable for tracing problems.
If there are no special requirements, the following logger settings are recommended:
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
Change history logger
For the tracking of changes made by users to objects in the course of DrainWindow, there is the cx.change logger (until Dll version 198898 still cx.access), which has a special meaning. As soon as it is set to TRACE, a mechanism is logged that outputs every object change and every transaction as a JSON object (for easier parsing). Since a lot of data is logged here that should be separated from the regular log output, it is recommended to define a separate log appender for this.
For this purpose ClassiX defines its own environment variable CX_CHANGELOGFILENAME (based on CX_CHANGELOG_DIR), which can be used in logging.ini. If CX_CHANGELOG_DIR is not set, the system writes to System\Changelog.
To activate the change history logger, simply add the following block to the logging.ini at the end:
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
Short explanation:
The newly defined CHANGE_LOGGER appender writes in a log file with the suffix _change and formats the output similar to the regular logger. After the appender has been defined, the cx.change logger is set to the TRACE level and assigned to the CHANGE_LOGGER appender. The last line prevents an event that the cx.change-Logger does not log from being passed on to the cx-Logger.
Whitelist/Blacklist
199065
To further limit the amount of logged data, a whitelist or blacklist can be defined via SetLoggedClasses, SetNotLoggedClasses. The change logger only logs DrainWindow/Link/... commands that refer to objects that are derived from at least one class from the whitelist and are not derived from any class from the blacklist. The start object of the DrainWindow/Link/...-operation is always checked. The subobjects drained by the DrainWindow operation are not filtered by the whitelist/blacklist. Via Whitelist&Blacklist, logging can thus be limited to the classes of really relevant inventory data. This also further speeds up the system.
If nothing has been set, the change logger starts with a whitelist of CX_CLASS and an empty blacklist so that all changes to all classes are logged.
200176
The Changelogger now logs all commands that change the state of persistent objects or collections. To restrict the operations performed on collections, the type COLL can be added to the blacklist or removed from the whitelist (from now on part of the default whitelist). The performance of the logger can be slightly optimised by choosing a suitable buffer size (BufferSize in logging.ini) for the logger. The changelogger collects the log events (as long as the buffer is sufficient) in memory until a CommitTXN or AbortTXN comes.
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}