bonedaddy/ulog

ulog (uber log) is a lightweight and threadsafe logger in C that provides color coded output, as well as the ability to send logs to a file.

ulog

ulog (uber log) is a lightweight and threadsafe logging library written in C, with support for C++. It features color coded output, with the ability to send logs to stdout and a file. File and line information indicating what fired the log is also included. It has INFO, WARN, ERROR, and DEBUG log levels, and is thoroughly tested with cmocka and valgrind.

If not using debug logging then any DEBUG level log calls are silently skipped. The logger is threadsafe in that multiple threads can't log at the same time. In practice there is very little lock contention and in all honesty you will probably never have to worry about it.

In terms of memory usage, the only memory allocations conducted by this library are when initializing the logger. During actual logging there is no memory allocations whatsoever, as we use stack allocated variables. In practice logger initialization consumes arounds 7.4 KiB of memory, while regular logger usage general consumes no more than 3 -> 3.4 KiB of memory at any one time.

Please be aware that after calling clear_thread_logger or clear_file_logger using the logger results in undefined behavior, likely a panic causing the program to exit. Having one or more threads initiate a log invocation while concurrently calling clear_thread_logger or clear_file_logger results in undefined behavior. When clearing the logger you must be certain no other threads will attempt to use the logger.

features

• C/C++ support
• lightweight (3 -> 3.4 KiB memory consumption)
• threadsafe
• color coded logs
• stdout and file descriptor logging
• file and line number that emitted the log included

why another logging library?

I wanted a simple logging library that didnt leak memory, was well tested, and capable of color coded output. All logging libraries I found were complex code bases, leaked memory, and relied on global variables. Because of that, and as a way to better learn C development ulog was born.

Interested in reading more about how ulog was born? I published a blog post detailing the creation.

versioning

The library follows the semver versioning scheme. Additionally a version.h header file has the current release version listed as a macro.

installation

manual (broke)

Copy and paste the logger.h, colors.h, version.h, logger.c, and colors.c files into whatever project you are working on. You will need to make sure that you have pthreads available to link with as the logger library has a pthreads dependency.

clib (woke)

If you use the clib package manager then you can install ulog into your project with a single command:

$> clib install bonedaddy/ulog

testing

Before testing you'll need to compile the code, for which you have two options

Release mode

$> make

Debug mode

$> make build-debug

Running either of the following two commands will build a test executable logger-test within the build folder. You can either invoke this manually or use ctest.

Regular unit testing:

$> ctest

Valgrind dynamic analysis and unit testing:

$> ctest -T memcheck

usage

The primary method of interacting with ulog is by using macros. The macros allow you to emit logs at various levels, minimizing the amount of typing required to do so. There are a total of four macros that can be used, the base macros are denoted in the form of LOG_<LEVEL> and LOGF_<LEVEL> which provide the capabilities to emit logs to standard out. The LOG_ macros can be used to emit a log message as is, that is to say you provide a single message to emit, while the LOGF_ macros can be used to emit a log message formatted according to the printf formatting rules leveraging variadic arguments.

There are two additional macros that mimic LOG_<LEVEL> and LOGF_<LEVEL> however they will also log to a given file, while also logging to stdout. They are fLOG_<LEVEL> and fLOG_<LEVEL>. The main difference between these, other than the fact that file logging capabilities are provided, is that the LOG_<LEVEL> and LOGF_<LEVEL> macros take in an instance of thread_logger while the fLOG_<LEVEL> and fLOGF_<LEVEL> macros take in an instance of file_logger.

Below you'll find examples that showcase how to generate the logs that were captured in the screenshot displayed at the beginning of this readme.

stdout only

#include <stdbool.H>
#include "logger.h"

thread_logger *thl = new_thread_logger(true);

LOG_INFO(thl, "this is an info log");
LOG_WARN(thl, "this is a warn log");
LOG_ERROR(thl, "this is an error log");
LOG_DEBUG(thl, "this is a debug log");

// the LOGF_ prefixed functions can be used for printf styled output
LOGF_INFO(thl, "this is a %s style info log", "printf");
LOGF_WARN(thl, "this is a %s style warn log", "printf");
LOGF_ERROR(thl, "this is a %s style error log", "printf");
LOGF_DEBUG(thl, "this is a %s style debug log", "printf");

// free up memory when you no longer need the logger
// note: after this returns thl is no logner safe to use
clear_thread_logger(thl);

file and stdout

#include <stdbool.h>
#include "logger.h"


file_logger *fhl = new_file_logger("testfile.log", true);

fLOG_INFO(fhl, "this is an info log");
fLOG_WARN(fhl, "this is a warn log");
fLOG_ERROR(fhl, "this is an error log");
fLOG_DEBUG(fhl, "this is a debug log");

fLOGF_INFO(fhl, "this is a %s style info log", "printf");
fLOGF_WARN(fhl, "this is a %s style warn log", "printf");
fLOGF_ERROR(fhl, "this is a %s style error log", "printf");
fLOGF_DEBUG(fhl, "this is a %s style debug log", "printf");

// if you dont want to log to a file you will want to use the LOG_ and LOGF_ macros
LOG_INFO(fhl->thl, "this will only log to stdout");
LOGF_INFO(fhl->thl, "this will only log to %s", "stdout");

clear_file_logger(fhl);

license

AGPLv3 licensed, although if you want commercial license under MIT that can be aranged for a small fee.

ulog's Issues

Releases Fail Due To "Missing Token"

For some reason despite not actually uploading anything to github, releases are failing due to a "missing token", see https://travis-ci.com/github/bonedaddy/ulog/builds/209236979#L1703

Consider Alligned Memory Attributes

I'm wondering if we should set allignment requirements for the struct and all other possible locations.

https://gcc.gnu.org/onlinedocs/gcc-3.1/gcc/Type-Attributes.html
https://embeddedartistry.com/blog/2017/02/22/generating-aligned-memory/

Enable Switching To/From Debug Mode During Program Execution

A function can be added that lets you toggle debug mode during program execution, whereas currently it requires setting it at logger startup.

Publish As A Clibs Package

https://github.com/clibs/clib

TODO

• update README with installation instructions using clib
• publish PR to clib wiki listing this logger

Reduce Memory Usage

Currently we can avoid basically all memory allocations if we adjust functions which allocate memory to take an input buffer of memory. This input buffer can be assigned on the stack as opposed to being allocated on the stack. If I'm correct in my thinking, the only memory allocations needed would be during logger instantiation.

Update Usage Example Explaining How To Disable Debug Mode

Right now the usage example doesn't show how you can use either a debug log or non debug log.

Simplify File Logging

Right now the file logging system requires a bit of additional typing to complete, notice in the following the additional referencing of struct pointer member fields:

LOG_DEBUG(fhl->thl, fhl->fd, "this is a debug log");

Whereas with traditional stdout logging:

LOG_DEBUG(thl, 0, "this is a debug log");

The best solution I can think of would be to simply have a macro like FLOG_INFO, FLOGF_INFO and inside those macros deal with the struct pointer member referencing to avoid having to type it out when writing the actual log statement.

Update Readme With Goals And Non Goals

Goals (Long Term)

...

Non Goals

• log file rotation
• Complex log sending
  • We send to stdout, or a file descriptor that's it