Introduction
It's simple to use implementation of cross-platform and thread-safe logging facility.
Background
Logging is a fundamental technique in programming. Sometimes it's the single available diagnostic tool. No surprise there're a lot of different logging libraries. They provide logging to different kind of targets most of them you never heard about, dozens of log categories (like "warning", "serious warning", "almost error", "critical error", "the end of the Earth"), comprehensive configurations and output formats, vertical takeoff (I'm sure I remember one such log-library), etc. And I'm sure there're projects that really need all those features. Who doesn't need them writes their own logging.
One day when I decided to throw out one of those comprehensive log-libraries (because it had a 4 pages feature list but was not thread-safe), I tried to write a simple logger and had the following requirements for it:
- Logging to log-file and to console (if present)
- Logging errors, ordinal log-messages and debug messages (with the ability to turn off not-important category)
- Simplicity: single header only
- Usability:
printf()-like formatting and ability to automatically put function name (or class_name::function_name) to beginning of log-message - Logging should be thread-safe
- Library should work fine under Windows and Linux (not tested under MacOS but don't see any reason why it shouldn't work there)
- Logging should be as efficient as possible and I need to be able to turn it off
It's already the second version of the library, with some improvements and additions. Further development is planned too, e.g. the next version will include log-message format configuration. If you see how this library can be improved or if you need a not-implemented feature - don't hesitate to write in the comments below.
Using the Code
You need to include "logger.h" to your sources (precompiled header is the most appropriate place for this), set filename of log output and log, log, log. :) This looks like:
#include "logger.h"
int main()
{
logging::set_output("filename.log");
logging::set_minimal_category(logging::cat_info);
log_error("to log w/o logging place info, uses %s format", "printf()");
LOG("to log with function name and with single %s", "argument");
log_debug("debug message shouldn't appear because of category filter");
return 0;
}
Output looks like:
08:30:20:609 3412 ERROR: to log w/o logging place info, uses printf() format
08:30:20:609 3412 info: main: to log with function name and with single argument
08:30:20:625 3412 info: main: this long log message should be truncated
because of too short buf
Format is:
HH:MM:SS:FFF thread_id log_category: optional_function_name: log-message
Macros LOG, LOG_ERROR and LOG_DEBUG put the function name where logging occurred.
To turn off logging, define LOGGING_DISABLED before including "logger.h".
BTW, these macros are very useful, e.g. if you have a function...
void DoSomething(ID item_id)
... you can log it like...
LOG("id = %d", item_id)
It's enough because the function name will be added automatically.
By default log-message formatting buffer is 4096 chars long that should be enough in most cases. But you can change this using logging::set_buffer_size(size_t new_size).
Points of Interest
To provide portability, I used Boost. If you still don't use Boost Libraries, it's good chance to start, they will "boost" your C++ programming performance.
Efficiency is provided by optimizing memory allocation for output formatting and by lock-free output buffer synchronization - keeping it in thread local storage. printf() formatting style instead of modern and much more robust boost::format was chosen also for better performance.
Acknowledgements
I would like to thank my friend Sviatoslav Danyliv (aka Dans.Lviv.Ua) and all guys who commented on this library, for their help.
History
- 28th April, 2009: Initial post
- 9th May, 2009: Version 2.0
