Skip to content

Log Message System#

The log message system of the Basler runtime software supports you in case of problems. It contains about 1.000 log messages.

You can direct the log messages to appear

This topic provides information on how to:

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.

You find an example for using the log library in your runtime installation folder: Runtime5.9/SDKExamplesNew/siso_genicam/AcquisitionWithLogging

Example Log Library in Runtime Installation Folder

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
  • 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. As soon as 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.xmld.

You find this file in the bin folder of your Basler runtime installation (%sisodir5%).

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="siso">
<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(s) you want to get
  • a reference to an appender

Code example for a logger:

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

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

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

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 runtime 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

To receive error messages from the GigE Vision library (gbelib) of the Basler SDK, you need to adapt the separate XML logging configuration file common-logging-log4cxx.gs.xml, see Receiving Log Messages from Generic Service and gbelib.

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

Make sure the logging configuration file common-logging-log4cxx.xml (and common-logging-log4cxx.gs.xml) is stored in the same directory as the executable of your application.

Info

Make sure that in the logging system configuration file common-logging-log4cxx.xmlf, you first define the appenders, and only below the loggers.

Receiving Log Messages from GS and gbelib#

The Basler generic service is a local service. It is required, amongst other things, for camera discovery. You can receive error messages from the generic service. These messages also contain all messages sent by the SDK library gbelib.

To receive log messages from the generic service and the SDK library gbelib, you have to adapt the XML logging configuration file common-logging-log4cxx.gs.xmlg.

You find this file in the bin folder of your Basler runtime installation (%sisodir5%).

To receive error messages:

  1. Adapt the separate XML logging configuration file common-logging-log4cxx.gs.xml to your needs. Use the instructions for configuring log files you find in Receiving Log Messages in Shell or Log Files. You may use any appender configuration described in the log4j documentation except logging to shell (console).

Info

As the generic service is a local service and no application, it is not possible to receive its error messages in the console (shell). Therefore, the default appender configuration in common-logging-log4cxx.gs.xml is logging to file.

Info

Basler recommends you to use logger name "siso" to receive all error messages sent by the generic service. As only the generic service and SDK library gbelib use log configuration file common-logging-log4cxx.gs.xml, but all other SDK libraries use log configuration file common-logging-log4cxx.xml, there will be no interference of the outputs from both files.


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

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

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

  4. This file adheres to the specifications of log4cxx. Log4cxx is a C++ adaptation of Log4j and part of the Apache Logging Services project of the Apache Software Foundation. 

  5. To receive error messages from library gbelib of the Basler SDK, you need to adapt the seperate XML logging configuration file "common-logging-log4cxx.gs.xml" which you find in the bin folder of your Basler runtime installation (%sisodir5%), see section "Receiving Log Messages" from Generic Service and gbelib. 

  6. This file adheres to the specifications of log4cxx. Log4cxx is a C++ adaptation of Log4j and part of the Apache Logging Services project of the Apache Software Foundation. 

  7. This file adheres to the specifications of log4cxx. Log4cxx is a C++ adaptation of Log4j and part of the Apache Logging Services project of the Apache Software Foundation. 

Back to top