Stumpless

Stumpless is a C logging library built for high performance and a rich feature set.

Basic Usage

The simplest way to get started is to use the stumplog function as a direct replacement for the standard library's syslog function:

// if you're used to doing this:
syslog( LOG_INFO | LOG_USER, "My message #%d", count );
 
// then you can start by changing to this:
stumplog( LOG_INFO | LOG_USER, "My message #%d", count );

If you haven't opened a target, this will log messages to the default target for the platform: on Linux this is /dev/log, on a Mac system this will be /var/run/syslog, and on a Windows machine it is the Windows Event Log. If you open a target or even a few before calling stumplog, then logs will be sent to the most recently opened target.

If you want an even shorter function call, you can use the stump() function to send a message to the current target. You can also use format specifiers just as you would with printf.

stump( "Login attempt failure #%d for user %s", count, username );

If you don't need format specifiers, use one of the _str variants such as stump_str(): it's both faster and safer!

stump_str( "Login failure! See structured data for info." );

If you want to open a specific target rather than using the default, then just open the one you need and start sending messages. For example, to log to a file named example.log

target = stumpless_open_file_target( "example.log" );
 
// uses the last opened target by default
stump( "Login attempt failure #%d for user %s", count, username );

Sending messages over the network to something like Splunk or rsyslog is just as easy:

target = stumpless_open_udp4_target( "send-to-splunk-example",
                                     "mylogserver.com" ); // or use an IP
stump( "Login attempt failure #%d for user %s", count, username );

If you have multiple targets, you can send messages to a chosen target like this:

stumpless_add_message( target,
                       "Login attempt failure #%d for user %s",
                       count,
                       username );

Severity Shorthand

It's common to specify severity levels directly in logging calls, so stumpless provides some macro functions to make this less verbose and more efficient. For example, to log messages with a severity of INFO, you can do this:

stump_i( "this gets logged as an info message" );

And if you want to also see source file, line number, and function name info in each message you can use stump_t() (the 't' is for trace):

stump_t( "this includes source info" );

Using these functions has the added benefit that they can be removed at compile time by simply defining the proper STUMPLESS_ENABLE_UPTO or STUMPLESS_DISABLE_DOWNTO symbols. This makes it easy to change logging levels between builds, for example to have prod and debug versions without differences in their source code.

// be sure to define this before stumpless.h gets included
#define STUMPLESS_ENABLE_UPTO_INFO
 
// ...
 
// this log will go through just fine
stump_i( "I'm doing that thing you asked" );
 
// this debugging message is completely removed: no runtime impact whatsoever
stump_d( "DEBUG info: %d, %d, %s", thing_1, thing_2, stringy_thingy );

Check out the headers in the stumpless/level include directory named after a severity level such as alert.h to see the full list of severity shorthand functions, or severity_level_example.c to see a complete program in action.