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

Key Features | Download and Build | Basic Usage | Contributing

Key Features

Stumpless offers a robust set of features to make logging in C faster and easier:

• cross-platform builds on Linux, Windows, Mac, Cygwin, and more
• easy logging to network targets like Splunk or rsyslog servers
• can be adjusted or removed during compilation for zero runtime impact
• interoperability with standard syslog daemons and library functions
• an extensive unit testing suite and continuous integration
• localized for multiple languages 🇩🇪 🇫🇷 🇸🇪 🇸🇰 (add yours!)
• easy-access documentation, examples, and support.

Quick Build and Install

Stumpless only requires cmake and a cmake-supported build toolchain (like GCC or Visual Studio) to build. For a system using the standard GNU make toolchain, you can simply do:

# cloning the latest version of the source tree
git clone git@github.com:goatshriek/stumpless.git

# creating a new build directory
mkdir build
cd build

# configuring the new build
cmake ../stumpless

# building stumpless (with 4 threads - adjust as desired)
make -j 4 all

# install the library (you probably need sudo to do this)
sudo make install

Check out the Installation Instructions for more detail on building and installing stumpless.

Basic Usage

The following code snippets show the most common ways to use stumpless.

Basic Logging Functions

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" );

// then you can start doing this:
stumplog( LOG_INFO | LOG_USER, "My message" );

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

stump( "My message" );

And of course, you can use format specifiers in both functions just as you would with printf:

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

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

target = stumpless_open_file_target( "example.log",
                                     STUMPLESS_OPTION_NONE,
                                     STUMPLESS_FACILITY_USER );
// 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
                                     STUMPLESS_OPTION_NONE,
                                     STUMPLESS_FACILITY_USER );
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" );

Using these functions has the added benefit that they can be removed at compile time by simply defining the 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 stumpless/level to see the full list of severity shorthand functions, or the severity level example to see a complete program in action.

Even more examples

For more detailed examples of the above scenarios, usage of specific target types, how to handle more complicated message structures, and more check out the examples. These include annoted example code files to compile, run, and modify to get you started.

Contributing

Notice a problem or have a feature request? Just create an issue using one of the templates, and we will respond as quickly as we can. You can also look at the project's Contribution Guidelines for more details on the different ways you can give back to the open source community!

If you want to actually write some code or make an update yourself, take a look at the development guide to get a detailed orientation. There are a few options based on your level of experience and familiarity with making contributions.

The first option is to browse the list of issues that are marked with the label good first issue. These issues are selected to be a small but meaningful amount of work, and include details on the general approach that you can take to complete them. They are a great place to start if you are just looking to test the waters of this project or open source contribution in general.

More experienced developers may prefer to look at the full list of issues on the project, as well as the roadmap. If an item catches your interest, drop a comment in the existing issue or open a new one if it doesn't exist yet and state your intent to work on it so that others will have a way to know it is underway.

Or perhaps you are just looking for a way to say thanks! If that's the case, or if you have something that you would prefer to drop me a private message about, please feel free to do so in an email! I'd love to hear your thoughts on the project or anything related to it.

Further Documentation

If you're curious about how something in stumpless works that isn't explained here, you can check the appropriate section of the documentation, stored in the docs folder of the repository. Folders in the repository contain their own README files that detail what they contain and any other relevant information. If you still can't find an answer, submit an issue or head over to gitter and ask for some help.