[boost] Boost Logging v2

From: John Torjo (john.groups_at_[hidden])
Date: 2007-10-03 04:02:39

Boost Loogging v2

Hi all,

It's been a while - I admit, and I apologize for it. Well, finally, I'm 
working on version 2 of Boost Logging, taking into account your 
suggestions when the first version was rejected.

The extra short version: It's in alpha stage. Get it from here: 
http://torjo.com/log2/

Without further ado, I'll present you Boost Logging Library v2, with
- a much nicer separation of concepts and
- a much more flexible interface.
- you don't pay for what you don't use.
- fits a lot of scenarios:
  from very simple (dumping all to one log)
  to very complex (multiple logs, some enabled/some not, levels, etc).
- you can now define your own LOG_ macros

Here are 2 small examples to show you a bit of v2's power:

----------------- Example 1:
struct write_to_cout_and_file { ... };

// defining the logs
logger<write_to_cout_and_file, manage_enabled_no_ts> 
g_single_log("out.txt");
#define L_(x) if ( g_single_log) g_single_log.process_msg()(x)

// code
L_("reading word " + word);

----------------- Example 2:
struct write_to_file { ... };
struct write_to_cout { ... };
struct write_to_dbg { ... };

// defining the logs
typedef process_msg< ostream_like_return_str<>, write_to_cout> 
processor_cout;
typedef process_msg< ostream_like_return_str<>, write_to_file> 
processor_file;
typedef process_msg< ostream_like_return_str<>, write_to_dbg> processor_dbg;

logger<processor_cout, manage_enabled_no_ts> g_log_app;
logger<processor_file, manage_enabled_no_ts> g_log_err("err.txt");
logger<processor_dbg,  manage_enabled_no_ts> g_log_dbg;

#define LAPP_ if ( !g_log_app) ; else g_log_app->read_msg().gather().out()
#define LERR_ if ( !g_log_err) ; else g_log_err->read_msg().gather().out()
#define LDBG_ if ( !g_log_dbg) ; else g_log_dbg->read_msg().gather().out()

// code
LAPP_ << idx << " : reading word " << word;
LERR_ << "error at " << idx << ", while reading " << word;
LDBG_ << "debug info: " << idx << ", reading " << word;

-----------------

The above was the short version. You can also look at the test_*.cpp 
files, to see some more examples of how you can use the library.
Download it here : http://torjo.com/log2/

Long version follows:

First, a bit about the workflow:
Step 1: Filtering the message
Step 2: Gathering the message
Step 3: Writing the message

Step 1: Filtering the message
In order to be efficient, before anything happens to the message,
we see if the log it's written to, is enabled.
If so, we process the message.
If not, we ignore all of the message.

This is rather easy, with constructs like this:
#define L_(x) if ( g_single_log) g_single_log.process_msg()(x)
#define L_ if ( !g_log_app) ; else g_log_app->read_msg().gather().out()

Step 2: Gathering the message
Now, that we know the log is enabled, all the message is gathered.
This depends on how you write the message. For instance, you can gather 
it in one step, if you want to offer a syntax like this:
L_("this is my message");

Or, you can offer syntactic sugar:
i = 100;
L_ << "this is " << i << " times better that the average bear... ";

In this case, you'll gather all info in a stream of some kind.

Or, you can have more data besides the message string, like: module 
name, severity of message, category, etc:
L_(fatal,"chart","Can't find the ChartX control");

Step 3: Writing the message
Now all info about the message is gathered. You can write it to its 
destination(s).
What you wanna do with a message, is completely up to you. The library 
will offer you possibilities.

You can go for the extremely easy way, and just have a functor which 
dumps the message somewhere, like this:

struct write_to_cout {
    void operator()(const std::string & msg) const {
        std::cout << msg << std::endl ;
    }
};

Or:

struct write_to_file {
    typedef boost::shared_ptr<std::ofstream> ptr;
    write_to_file(const std::string & filename) : m_out(new 
std::ofstream(filename.c_str())) {}
    void operator()(const std::string & msg) const {
        (*m_out) << msg << std::endl ;
    }
    mutable ptr m_out;
};

Or, you can choose to Format and/or write your message to Destinations 
(these will be explained later)

Download it here : http://torjo.com/log2/
------------------------------------------------------
Logger objects

For each log you want, you'll have a logger object. Note that "log" is a 
concept - several logs can write to the same file and/or one log can 
write to multiple destinations. I use the term "log" to identify a type 
of log message you want to write -- for example, you can have a "debug 
log" for writing debug messages; an "info" log, for writing 
informations, and so on. The fact that they might end up writing to the 
same destinations, is completely transparent to the user, as it should.

A logger object contains 2 things:
- a filter: an is_enabled() function - to find out if it's enabled.
- a process_msg() object - this contains the logic of what to do with 
the message, if the log is enabled.

The 2 concepts are orthogonal - Andrei would call them "policies" ;)

The process_msg() is the object that will process the message if the log 
is enabled - it executes steps 2 and 3.
How this happens, is completely up to you - when you define your macros 
(more on this later).
------------------------------------------------------
Filtering and Log Levels

I have implented several filters: see filter.hpp file:
- manage_enabled_no_ts - filter (not thread-safe)
- always_enabled - enable logs at compile time
- always_disabled - disable logs at compile time
- debug_enabled, release_enabled
- manage_enabled_ts - thread-safe filter
- etc.

Using v2, you don't really have to use Log Levels, if you don't wish 
(see examples above)

A logged message can have an associated Log Level. By default we have 
these levels:

        info (smallest level),
        warning ,
        debug ,
        error ,
        fatal (highest level)

Depending on which level is enabled for your application, some messages 
will reach the log: those messages having at least that level. For 
instance, if info level is enabled, all logged messages will reach the log.
If warning level is enabled, all messages are logged, but the warnings. 
If debug level is enabled, messages that have levels debug, error, fatal 
will be logged.

Note that there's an example of using Log Levels provided with the code.

------------------------------------------------------
Usage syntax / Macros

Once you've set up what each of your logs does (writes to), it's a must 
to have an easy and straightforward way to write to your logs - logging 
can be fun.

While you can write directly to your logs, like this:
if ( !g_log_app) ; else g_log_app->read_msg().gather().out() << 
"coolio!" << std::endl;

Usually you'll prefer to have some macros to help you write less and 
especially avoid being error-prone.

In the previous version, you've asked to be able to write your own 
macros - well, you are.
And it's waaaay easier than before:
If you have a logger object, to test if it's enabled, call its operator 
bool(). To see if it's not enabled, call its operator!

I will provide some helpers in the future - they're not there yet.

------------------------------------------------------
Logger objects and macros

So, to define a log macro, you'll say something like this:

logger<some_processor, some_filter_class> g_log;
#define L_ if ( !g_log) ; else g_log->...

Note that "g_log->" is equivalent to "g_log.process_msg()->" (syntactic 
sugar)

What follows after "..." is all up to you. For example, you can just get 
the message, and call a functor:

struct write_to_cout {
    void operator()(const std::string & msg) const {
        std::cout << msg << std::endl ;
    }
};
logger<write_to_cout, manage_enabled_no_ts> g_single_log;
#define L_(x) if ( g_single_log) g_single_log.process_msg()(x)

And in code you'll say things like
L_("some great message");

Or, you can use something a bit more complex, which will gather a 
message written using "<<", and then call a functor. I've already 
implemented this class:

typedef process_msg< ostream_like_return_str<>, write_to_cout> 
processor_cout;
logger<processor_cout, manage_enabled_no_ts> g_log;
#define L_ if ( !g_log) ; else g_log->read_msg().gather().out()

And in code you'll say things like:
L_ << "this" << " is " << "cool";

Or you can implement your own process message class.
------------------------------------------------------
Using process_msg()

Your process_msg class can hold context. And you can also manipulate 
logs in code:
logger<...> g_log;

g_log->my_great_log_manipulator();

Thus, you can create your own process message handler classes.
------------------------------------------------------
Formatters and/or destinations

In my previous version, they were called modifiers and appenders.

So, after the message has been gathered (step 2), we do the writing 
(step 3).

In step 3, if you use the "format_write" class, you can choose to add 
formatters and/or destinations.

A formatter is a functor that formats the message - for instance, it can 
prepend the current time, it can prepend the index, or thread ID, or 
append an Enter.

A destination is a location where a message can be written, like: 
console, a file, a socket, etc.

Dealing with formatters/destinations is easy: once you have a 
format_write object, just use:
void add_formatter(formatter fmt)
void del_formatter(formatter fmt)
void add_destination(destination dest)
void del_destination(destination dest)

In the previous version, the formatters were called first, and 
destinations last. Now you have more control.
However, this is not thoroughly tested - need to work more on this.

------------------------------------------------------
Examples. I've provided a few examples - you'll find them in the "tests" 
directory.

The code compiles and was tested on VC8.

Am still working on formatters and destinations. I'm planning to host it 
on sf.net.

Feedback and comments are welcome. Again, you'll find the library here:
http://torjo.com/log2/

-- 
http://John.Torjo.com -- C++ expert
... call me only if you want things done right