Log Message System#

The log message system of the Framegrabber SDK provides additional information which can be useful in tracking down problems observed in a user application. Around 1000 individual messages provide information about the system configuration, warnings when conditions aren't as expected, and more detailed error descriptions.

At the core of the log message system is a dispatcher which forwards messages to log4cpp^a and the siso_log library. The logging library log4cpp is used by GenICam and the pylon SDK to provide logging to the console, log files, syslog, the pylon Event Logger Application, and other destinations. Using the siso_log library, the user application can register a callback handler to receive warnings and error messages.

log4cpp is a C++ adaptation of Log4j and you find it on SourceForge. log4cpp was first used in the Framegrabber SDK version 5.11.3. Older versions of the Framegrabber SDK used log4cxx, an alternative to log4cpp. ↩

Configuring Log4cpp for Logging#

The log4cpp library can be configured using a configuration file. You find the default configuration for the Framegrabber SDK in the installation directory in the file bin/BaslerFgSdkLogging.properties. To change the configuration, you can edit this file, or you can provide your own configuration file and set the environment variable BASLER_FGSDK_LOGGING_CONFIG to point to the location of the file.

The configuration file for log4cpp is a text file. Each line of the file can contain one configuration option, which is given in the form <key>=<value>, and an optional comment starting with a # character. Empty lines and lines only containing a comment are also allowed.

<key> is a hierarchical element, the levels of hierarchy are separated by a . character. The top level of the hierarchy is always log4cpp, alternatively you can use log4j. The second level of the hierarchy is either category (including rootCategory), or appender.

A category designates where the log messages come from, and an appender designates a destination for the log messages.

Configuring Log4cpp Categories#

The options for a category are <min-severity>[, <appender>[...]]. The value for <min-severity> can be:

FATAL,
ALERT,
CRIT,
ERROR,
WARN,
NOTICE,
INFO, or
DEBUG

<min-severity> specifies the severity threshold of the log messages to be reported for the category and all its sub-categories. The optional list of <appender> specifies to which appender the log messages should be forwarded for the category and all its sub-categories.

Category options are inherited by all sub-categories, but can be overwritten by providing a separate option for a sub-category. Again, all sub-sub-categories inherit the configuration of the sub-category.

Most configuration files start with setting up reasonable defaults for all categories, using the special designation rootCategory. For example:

log4j.rootCategory=NOTICE, stdout

This configuration option sends all messages of the severity FATAL, ALERT, CRIT, ERROR, WARN, and NOTICE to the appender stdout. You must define the appender in the configuration file, as described at Configuring Log4cpp Appenders.

Mapping of Log Levels#

The Framegrabber SDK internally uses a different set of names for the severity of log messages, which follow the naming of the library log4cxx used in previous versions of the Framegrabber SDK. You might come across these internal log levels, for example, when using the siso_log library or the Debug dialog in microDisplayX.

Severity	siso_log	log4cpp
lower	TRACE	DEBUG
	DEBUG	INFO
	INFO	NOTICE
	WARN	WARN
	ERROR	ERROR
higher	FATAL	CRIT, FATAL, ALERT

Configuring Log4cpp Appenders#

To direct log messages to a destination, you must define and configure appenders in the configuration file. The appender must be included in a category configuration in the configuration file.

There are different types of appenders provided by the log4cpp library, which is installed with the Framegrabber SDK. Each type of appender has a set of configurable parameters that define, for example, how a log file should be named, where it should be saved, and if it should be limited in size.

To define an appender, the name is given as a key in the log4cpp.appender hierarchy and the type is specified as value. For example, the following line defines an appender named stdout which writes log messages to the console:

log4cpp.appender.stdout=ConsoleAppender

You can further configure the appender by setting options in the hierarchy below the named appender. For example, the following lines change the format of the log messages:

log4cpp.appender.stdout.layout=PatternLayout
log4cpp.appender.stdout.layout.ConversionPattern=[%d:%t:%c] %p: %m%n

Formatting Log Messages#

All appenders share some common options for formatting log messages by setting and configuring the layout. There are two simple, fixed layouts which can't be further configured: SimpleLayout and BasicLayout. PatternLayout can be configured by setting the ConversionPattern.

The option ConversionPattern is a format string and can contain the following format specifiers plus text that should appear in all log messages:

Specifier	Meaning
%%	The character `%`
%c	Category
%d	Date (see below)
%m	Log message
%n	Line separator
%p	Priority (severity)
%r	Milliseconds since creating the layout
%R	Seconds since Jan 1, 1970
%t	Thread ID
%u	Clock ticks since start of process

The date format specifier adds the date and time according to the short date format specified by the system. To customize the date format, the date format specifier can be followed by a strftime format specifier enclosed in curly braces (%d{...}). Refer to the strftime documentation for further details. The only change to the strftime format specifiers is, that the specifier %l prints milliseconds padded with zeroes to make three digits. For example, to print the date and time in an extended ISO 8601 format including milliseconds, use either %d{%FT%T.%l%z}, or %d{%Y-%m-%dT%H:%M:%S.%l%z}.

Logging to Files#

There are two appenders store log messages in files: FileAppender and RollingFileAppender.

The FileAppender has one required option, fileName, to set the file name. For example, to log messages to a file named fglib.log in addition to the console, the configuration file could look like this:

log4cpp.rootCategory=NOTICE, stdout, logfile

log4cpp.appender.stdout=ConsoleAppender
log4cpp.appender.stdout.layout=SimpleLayout

log4cpp.appender.logfile=FileAppender
log4cpp.appender.logfile.fileName=fglib.log
log4cpp.appender.logfile.layout=BasicLayout

The RollingFileAppender only writes to the log file up to a specified file size, then creates a backup of the file and clears the file to start anew. As with FileAppender, fileName is used to specify the name for the log file. In addition, maxFileSize can be set to change the maximum file size before rolling over. The default for maxFileSize is 10 MB. To set the number of backup files allowed, you can set maxBackupIndex. The default for maxBackupIndex is 1.

Using the Pylon Event Logger#

Alternatively to the log4cpp library, you can use the pylon Event Logger Application to display, filter and highlight log messages.

If you start the user application from the pylon Event Logger application, a configuration file is automatically generated and used, which makes sure that the pylon Event Logger application receives log messages from the user application.

If you start the user application in a different way, then the log4cpp configuration must include the EltAppender. The EltAppender works by sending log messages via the network interface and you must specify the port used with portNumber. The port must match the setup of the pylon Event Logger application. The default configuration for this scenario looks like this:

log4j.rootCategory=NOTICE, pylonEventLogger, stdout

log4j.appender.stdout=ConsoleAppender
log4j.appender.stdout.layout=PatternLayout
log4j.appender.stdout.layout.ConversionPattern=[%d:%t:%c] %p: %m%n

log4j.appender.pylonEventLogger=org.apache.log4j.EltAppender
log4j.appender.pylonEventLogger.layout=org.apache.log4j.PatternLayout
log4j.appender.pylonEventLogger.layout.ConversionPattern=[%d:%t:%c] %p: %m%n
log4j.appender.pylonEventLogger.portNumber=12320

Using the siso_log Library to Receive Log Message in an Application#

int SisoLog_InitLibrary();

typedef void FuncType_LogMsgCallback(
    tProcessId pid,
    tThreadId tid,
    const char * const logger,
    unsigned int level,
    const char * const msg,
    unsigned int tagcount,
    const tSisoLogTag * const tags,
    void * userdata
);

int SisoLog_RegisterLogMsgCallback(
    FuncType_LogMsgCallback * callback,
    void * userdata);

int SisoLog_SetMode(
    unsigned int mode);

int SisoLog_GetMode(
    unsigned int * mode);

To receive log messages from the log message system of the Framegrabber SDK, add the library siso_log to your application project and include siso_log.h in your source code. Refer to the chapter Prerequisites of the Framegrabber API Manual for further details.

To start using the siso_log library, first call SisoLog_InitLibrary() to perform initialization.

With SisoLog_RegisterLogMsgCallback() you can register a function of the type FuncType_LogMsgCallback, which is then called whenever a log message of the severity WARN, ERROR, or FATAL is reported from the log message system. You can register only one function in a process.

Parameters of the SisoLog_RegisterLogMsgCallback() callback function:

The first two parameters to the callback functions are the process and thread IDs.
The third parameter is the name of the logger (category).
The fourth parameter is the severity, also called "log level" or "priority".
The fifth parameter is the log message.
The sixth and seventh parameters are the number of tags and a pointer to the array of tags. Tags are used to add additional metadata to log messages, such as the device relations.
The last parameter to the callback function is a pointer which was supplied with the call to SisoLog_RegisterLogMsgCallback() and which can be used as a pointer to a context structure or class, for example this pointer of a class instance which represents the user application.

After a callback function has been registered, the application must call SisoLog_SetMode() and pass SISOLOG_MODE_DEFAULT to eanble forwarding log messages.

Stop Receiving Log Messages#

int SisoLog_RegisterLogMsgCallback(
    FuncType_LogMsgCallback * callback,
    void * userdata);

int SisoLog_SetMode(
    unsigned int mode);

int SisoLog_FreeLibrary();

To stop receiving log messages from the log message system of the Framegrabber SDK:

To disable forwarding log messages, call SisoLog_SetMode() and pass SISOLOG_MODE_OFF.
Unregister the callback function by calling SisoLog_RegisterLogMsgCallback() and pass nullptr for both the callback function and the user context pointer.
Before terminating the application, call SisoLog_FreeLibrary().