Skip to content

Log Message System#

The log message system of the Framegrabber SDK supports you in case of problems. It contains about 1.000 log messages.

You can direct the log messages to appear

Receiving Log Messages in Software#

The log library siso_log allows you to receive the log messages directly in software. You will have to register a call back. After registering the call back, you will receive all log messages of the levels Error, Warning, and Fatal directly in your software.

To Use the Functions of the Library#

  1. Initiate the library: (void) SisoLog_InitLibrary();
  2. Define the log mode. You have the following options: SISOLOG_MODE_OFF or SISOLOG_MODE_DEFAULT

If you don't change the settings, the log mode is set to OFF (default).

SISOLOG_MODE_OFF: When the log mode is off, you can't receive log messages in your software. The messages are only written to file.

SISOLOG_MODE_DEFAULT: When the log mode is set to default, you can receive log messages of the following levels: Warning, Error, and Fatal.

To Receive the Log Messages in your Software#

  1. Set the log mode to SISOLOG_MODE_DEFAULT as follows: (void) SisoLog_SetMode(SISOLOG_MODE_DEFAULT);

Info

To get information which mode is set at the moment, you can use function SisoLog_GetMode.

To enable receiving the messages#

To enable receiving the messages, you also need to establish a log message call back:

  1. Define a log message call back as follows:
void 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)
{
... your implementation ...
}

At calling the function, you are handed over the following parameters:

  • pid: process id of the log event source process
  • tid: thread id of the log event source thread
  • logger: name of the log event source logger
  • level: logging level of the log event
  • msg: logging message of the log event
  • tagcount: number of attached logging tags of the log event
  • tags: logging tags array
  • userdata: user data pointer from the matching call to SisoLog_RegisterLogMsgCallback

Info

Defining the functionality of this function is up to you and part of your individual implementation.

  1. Register your log message call back as follows: (void) SisoLog_RegisterLogMsgCallback(&logMsgCallback, 0);

The last argument is at your disposal. You can use it as a pointer. It is handed over to the call back as the last argument (that is, as parameter userdata).

Now, this function will be called each time a log message is generated.

Info

Only one log message call back function can be active. When you define a new log message call back, the new function will be used. To unregister, use 0 as first argument.

To release the library#

  1. Use the following function: (void) SisoLog_FreeLibrary();.

Receiving Log Messages in Shell or Log Files#

To receive log messages in other channels than your application (for example, in log files or in the shell), you have to alter the XML logging configuration file: common-logging-log4cxx.xmla.

Info

Log4cxx is a C++ adaptation of Log4j and part of the Apache Logging Services project of the Apache Software Foundation. common-logging-log4cxx.xml adheres to the specifications of log4cxx. Make sure that in the logging system configuration file common-logging-log4cxx.xml, you first define the appenders, and only below the loggers.

You find this file in the bin folder of your Framegrabber SDK installation (%BASLER_FG_SDK_DIR%).

To configure the log output, you have three components available in the file:

  • Logger (for defining the source of logging and which severity levels are included)
  • Appender (for defining output channel and layout of logging output)
  • Layout of appender (child of appender)

You can define multiple appenders and multiple loggers. Each logger refers to at least one appender. One appender can be referred to by multiple loggers.

Example:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Target" value="System.out"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss,SSS}] %-5p %c: %m%n"/>
</layout>
</appender>
<logger name="basler">
<priority value="info"/>
<appender-ref ref="console"/>
</logger>
<root>
<priority value="off"/>
</root>
</log4j:configuration>

The Logger#

Within a logger tag, you define

  • from where you want to get logging messages (e.g., from a specific library)
  • which logging level you want to get
  • a reference to an appender

Code example for a logger:

<logger name="basler">
<priority value="info"/>
<appender-ref ref="console"/>
</logger>

Logger name: With the logger name, you define from which library of the Framegrabber API you want to get logging messages.

  • name="basler" forwards logging messages from all libraries.
  • name="basler.fglib" forwards logging messages from the frame grabber library (fglib).
  • name="basler.clsersis" forwards logging messages from the Camera Link serial interface library (clsersis) of the Framegrabber API.
  • name="basler.genicam" forwards logging messages from the GenICam library (siso_genicam) of the Framegrabber API.
  • name="basler.iolibrt" forwards logging messages from the Camera Link serial interface library (clsersis) of the Framegrabber API.
  • name="basler.display" forwards logging messages from the Display library (for displaying raw image data) of the Framegrabber API.
  • name="basler.shal" forwards logging messages from the hardware abstraction layer library (hal) of the Framegrabber API.

Priority value: With the priority value, you define from which log level you want to receive your log messages. There are 6 log levels available in the following hierarchy:

  • fatal
  • error
  • warn
  • info
  • debug
  • trace

The messages of the level you select as well as all more severe log messages are forwarded. For example, if you select < priority value ="error"/ >, you will get all messages of levels error and fatal.

Appender reference: With the appender reference (appender-ref ref) you direct the output of the logger to a specific output channel. (The output channel itself and the layout of the message you define in the referenced appender). You can reference multiple appenders in one logger. For each reference, use a separate appender-ref tag.

<appender-ref ref="console" />
<appender-ref ref="file" />

The Appender#

In the appender, you define where log messages of a specific log source (logger) are output (output channel) and in which form (layout) they are output.

Within a appender tag, you define

  • the name of the appender (you can define any name)
  • the appender class (as defined by the log4j project) that tells the log message system where you want to get the log messages, for example ConsoleAppender (output to shell) or FileAppender (output to file); The most common appender classes are:
    • org.apache.log4j.ConsoleAppender: ConsoleAppender appends log events to System.out or System.err using a layout specified by the user.
    • org.apache.log4j.FileAppender: FileAppender appends log events to a file.
    • org.apache.log4j.RollingFileAppender: Extends FileAppender to backup the log files when they reach a certain size.

For information on further appender classes, refer to the log4j.Appender documentation.

  • the layout of the log message (you define the layout in the child tag < layout >). You specify the layout class and a specific pattern for the layout. What is required for the pattern is layout class specific, so check log4j.Layout documentation for the layout class you choose to use (PatternLayout is used most commonly).

For most purposes in the context of the Basler Framegrabber SDK it is enough if you

  1. Give a name to the appender you are defining.
  2. Select an appender class (ConsoleApplender, FileAppender, or RollingFileAppender).
  3. In case of RollingFileAppender, define the maximum size of a log file (chunk).

Code example for a console appender:

<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Target" value="System.out"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss,SSS}] %-5p %c: %m%n"/>
</layout>
</appender>
Code example for a file appender:

<appender name="file" class="org.apache.log4j.FileAppender">
<param name="file" value="/log/mylogfile.log" />
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n" />
</layout>
</appender>
Code example for a rolling file appender:

<appender name="file" class="org.apache.log4j.RollingFileAppender">
<param name="append" value="false" />
<param name="maxFileSize" value="10KB" />
<param name="maxBackupIndex" value="5" />
<param name="file" value="/log/mylogfile.log" />
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n" />
</layout>
</appender>

When you use the rolling file appender class, the log files will have an index number directly after the file extension:

  • mylogfile.log.
  • mylogfile.log.1
  • mylogfile.log.2
  • etc.

Info

Note that if you select log level info or lower, the program's performance slows down.

Info

Note that the log levels are case sensitive, so only use lower case characters.

Info

On Windows operating systems: Make sure the logging configuration file common-logging-log4cxx.xml is stored in the same directory as the executable of your application.

On Linux operating systems: Make sure the logging configuration file common-logging-log4cxx.xml is stored in the same directory as the file libcommon-logging-log4cxx.so, which is located in the lib64 folder of your Framegrabber SDK installation.

  1. Log4cxx is a C++ adaptation of Log4j and part of the Apache Logging Services project of the Apache Software Foundation. ↩↩↩↩