$darkmode
Elektra 0.11.0
How-To: Logging

Quickstart

Enable logging by compiling with the CMake option ENABLE_LOGGER=ON (e.g. cmake -DENABLE_LOGGER=ON).

By default errors and warnings are logged to stderr and syslog, while notice and info message are only logged to syslog. Debug level message are not logged by default, but will be logged to syslog, if ENABLE_DEBUG=ON is set in CMake.

The file sink behaves like syslog, if it has been enabled (see below).

Step by Step Guide

Preparation

  1. Import the logging library in your code:
#include <kdblogger.h>
Logger Interface.
  1. Insert logging statements:
ELEKTRA_LOG("Hello, %s!", "🌎");

Log Everything

If Elektra should display all log messages, then please follow the steps below.

  1. Uncomment the line:
// #define NO_FILTER

in the file src/libs/elektra/log.c. (Alternatively you may define this macro via CMake.)

  1. Optional: The logging levels are set in src/include/kdblogger.h. For example, if you want to see everything (including debug messages) on stderr, then change the line
static const int ELEKTRA_LOG_LEVEL_STDERR = ELEKTRA_LOG_LEVEL_WARNING;
@ ELEKTRA_LOG_LEVEL_WARNING
something happened an end user would be interested in
Definition: kdblogger.h:35

to

static const int ELEKTRA_LOG_LEVEL_STDERR = ELEKTRA_LOG_LEVEL_DEBUG;
@ ELEKTRA_LOG_LEVEL_DEBUG
The debug log level.
Definition: kdblogger.h:65

File Specific Logging

If you want to only log messages below a specific directory prefix, then please follow the steps below.

  1. Search for the code:
#ifndef NO_FILTER
// XXX Filter level …
#endif

in the file src/libs/elektra/log.c.

  1. Replace the code with something like:
#ifndef NO_FILTER
if (strncmp (file, "src/postfix/", sizeof ("src/postfix"))) return -1;
#endif

, where src/postfix contains all source files with logging statements that Elektra should log. For example, if you want to log everything from the yamlcpp plugin, then use the following code.

#ifndef NO_FILTER
if (strncmp (file, "src/plugins/yamlcpp/", sizeof ("src/plugins/yamlcpp"))) return -1;
#endif

. To log messages from multiple source you can use the operator && to chain multiple calls to strncmp. For example, to log messages from the directoryvalue and yamlcpp plugin use the code:

#ifndef NO_FILTER
if (strncmp (file, "src/plugins/directoryvalue/", sizeof ("src/plugins/directoryvalue")) &&
strncmp (file, "src/plugins/yamlcpp/", sizeof ("src/plugins/yamlcpp")))
return -1;
#endif

Enabling and Disabling Sinks

The logging framework has 3 sinks: stderr, syslog and file.

The first to are enabled by default, while file is disabled. To enable it uncomment the line

// #define USE_FILE_SINK

in src/libs/elektra/log.c. The file that log messages are written to is defined in this line

elektraLoggerFileHandle = fopen ("elektra.log", "a");

Compilation

  1. Enable the logger: e.g. run cmake with the switch -DENABLE_LOGGER=ON
  2. Build Elektra

Log Levels

There are four log levels (ERROR is reserved for aborts within ELEKTRA_ASSERT):