Lightweight logging API for C programs
 
 
 
Go to file
nirenjan 3be94a24ba Update logging library to include module and string buffer
This commit adds the following changes to pinelog:

- Optional buffer to write the message to prior to writing to the output
  stream. This reduces the likelihood of log messages from multiple
  threads interleaving due to multiple calls to fputs/fprintf, etc. The
  default is to still write directly to the output stream, but the
  integrator can add a define of PINELOG_BUFFER_SZ to the CFLAGS, and
  this will allow the application to log messages that are shorter than
  the above size, including the timestamp, level and backtrace if any.

- Optional module level logging. This allows more fine-grained
  debugging, where the application can control the log levels of the
  individual modules. By default, when modules are configured, they
  default to the global log level, but this can be overridden by the
  application.
2021-11-08 16:18:30 -08:00
m4 Add autotools build framework 2021-07-13 11:33:10 -07:00
.gitignore Ignore test and benchmark programs 2021-08-25 09:35:20 -07:00
LICENSE Initial commit 2021-07-13 10:57:22 -07:00
Makefile.am Update logging library to include module and string buffer 2021-11-08 16:18:30 -08:00
README.md Remove the use of config.h 2021-08-25 12:07:40 -07:00
autogen.sh Add autotools build framework 2021-07-13 11:33:10 -07:00
bench_pinelog.c Fix pinelog builds on MacOS 2021-07-19 11:15:42 -07:00
configure.ac Remove the use of config.h 2021-08-25 12:07:40 -07:00
pinelog.c Update logging library to include module and string buffer 2021-11-08 16:18:30 -08:00
pinelog.h Update logging library to include module and string buffer 2021-11-08 16:18:30 -08:00
test_pinelog.c Update logging library to include module and string buffer 2021-11-08 16:18:30 -08:00

README.md

Pinelog - a lightweight logging API

Pinelog is a lightweight logging API for C programs that's designed to be included in your program source code. Parameters for Pinelog are configured at build time by means of preprocessor flags.

Usage

Logging macros

Pinelog uses printf style formatting, using the following list of macros. The macro indicates the level at which the message is logged.

  • PINELOG_FATAL
  • PINELOG_ERROR
  • PINELOG_WARN
  • PINELOG_INFO
  • PINELOG_DEBUG
  • PINELOG_TRACE

Note: PINELOG_FATAL is used when the program encounters a fatal condition and needs to abort. This will log the fatal message and terminate the program with an exit code of 1.

Example

PINELOG_INFO("configuration file %s not found, using defaults", config_file);

Logging levels

The default logging level is ERROR, and this can be controlled by the preprocessor flag PINELOG_DEFAULT_LEVEL.

The program can control the level at which messages can be logged at runtime, by using the pinelog_set_level function. This function takes in the level definition, which is one of the following, in increasing order of priority.

  • PINELOG_LVL_TRACE
  • PINELOG_LVL_DEBUG
  • PINELOG_LVL_INFO
  • PINELOG_LVL_WARNING
  • PINELOG_LVL_ERROR
  • PINELOG_LVL_FATAL
  • PINELOG_LVL_NONE

Setting the level to a given priority suppresses all log messages of lower priority, i.e., if the level is set to PINELOG_LVL_ERROR, messages at WARNING level and below will be suppressed, but ERROR and FATAL messages will be logged.

Note: PINELOG_LVL_NONE suppresses all log messages, but PINELOG_FATAL will still terminate the program, even though nothing is logged.

Example

pinelog_set_level(PINELOG_LVL_WARNING);
-DPINELOG_DEFAULT_LEVEL=PINELOG_LVL_WARNING

Output redirection

Pinelog defaults to writing the log messages to standard output, and this can be controlled by the preprocessor flag PINELOG_DEFAULT_STREAM.

However, the application can redirect log messages at runtime to a different FILE * stream, or to a file by using one of the following two methods:

FILE *out = fopen("/run/app.fifo", "w");
pinelog_set_output_stream(out);
pinelog_set_output_file("/var/log/app.log");
-DPINELOG_DEFAULT_STREAM=stderr

Logging format

Pinelog uses an opinionated logging format that is fixed as follows. Fields within [] are optional and controlled by build time flags.

[2021-07-14 11:08:04 ][ERROR: ][./test_pinelog.c:108 ]formatted message.

The program can be controlled by the following preprocessor flags, all of which default to 0 (disabled). Set the flag to 1 to enable it.

  • PINELOG_SHOW_DATE - Display the ISO 8601 date and time when the message is logged.
  • PINELOG_SHOW_LEVEL - Display the level at which the message is logged.
  • PINELOG_SHOW_BACKTRACE - Display the file and line where the message is logged.

Set these flags by using the -D compiler argument, .e.g. -DPINELOG_SHOW_LEVEL=1 -DPINELOG_SHOW_DATE=1

Level strings

The application can control the level strings displayed by means of preprocessor flags, if the application wishes to display the log messages in a language other than English. This can be achieved by means of the following preprocessor definitions.

  • PINELOG_FATAL_STR
  • PINELOG_ERROR_STR
  • PINELOG_WARNING_STR
  • PINELOG_INFO_STR
  • PINELOG_DEBUG_STR
  • PINELOG_TRACE_STR

Example

-DPINELOG_ERROR_STR=\"E\" -DPINELOG_FATAL_STR=\"F\"

Integrating Pinelog

Pinelog is intended to be integrated into your application source tree, either by means of including the sources directly, or by including the repository as a Git submodule or subtree.