#include <boost/log/sources/threading_models.hpp>
#include <boost/log/sources/basic_logger.hpp>

You can extend the library by developing your own sources and, for that matter, ways of collecting log data. Basically, you have two choices of how to start: you can either develop a new logger feature or design a whole new type of source. The first approach is good if all you need is to tweak the functionality of the existing loggers. The second approach is reasonable if the whole mechanism of collecting logs by the provided loggers is unsuitable for your needs.

Creating a new logger feature

Every logger provided by the library consists of a number of features that can be combined with each other. Each feature is responsible for a single and independent aspect of the logger functionality. For example, loggers that provide the ability to assign severity levels to logging records include the severity feature. You can implement your own feature and use it along with the ones provided by the library.

A logger feature should follow these basic requirements:

These requirements allow composition of a logger from a number of features derived from each other. The root class of the features hierarchy will be the basic_logger class template instance. This class implements most of the basic functionality of loggers, like storing logger-specific attributes and providing the interface for log message formatting. The hierarchy composition is done by the basic_composite_logger class template, which is instantiated on a sequence of features (don't worry, this will be shown in an example in a few moments). The constructor with a templated argument allows initializing features with named parameters, using the Boost.Parameter library.

A logging feature may also contain internal data. In that case, to maintain thread safety for the logger, the feature should follow these additional guidelines:

In order to illustrate all these lengthy recommendations, let's implement a simple logger feature. Suppose we want our logger to be able to tag individual log records. In other words, the logger has to temporarily add an attribute to its set of attributes, emit the logging record, and then automatically remove the attribute. Somewhat similar functionality can be achieved with scoped attributes, although the syntax may complicate wrapping it into a neat macro:

// We want something equivalent to this
{
    BOOST_LOG_SCOPED_LOGGER_TAG(logger, "Tag", std::string, "[GUI]");
    BOOST_LOG(logger) << "The user has confirmed his choice";
}

Let's declare our logger feature:

template< typename BaseT >
class record_tagger_feature :
    public BaseT // the feature should derive from other features or the basic_logger class
{
public:
    // Let's import some types that we will need. These imports should be public,
    // in order to allow other features that may derive from record_tagger to do the same.
    typedef typename BaseT::string_type string_type;
    typedef typename BaseT::attribute_set_type attribute_set_type;
    typedef typename BaseT::threading_model threading_model;
    typedef typename BaseT::record_type record_type;

public:
    // Default constructor. Initializes m_Tag to an invalid value.
    record_tagger_feature();
    // Copy constructor. Initializes m_Tag to a value, equivalent to that.m_Tag.
    record_tagger_feature(record_tagger_feature const& that);
    // Forwarding constructor with named parameters
    template< typename ArgsT >
    record_tagger_feature(ArgsT const& args);

    // The method will require locking, so we have to define locking requirements for it.
    // We use the strictest_lock trait in order to choose the most restricting lock type.
    typedef typename src::strictest_lock<
        boost::lock_guard< threading_model >,
        typename BaseT::open_record_lock,
        typename BaseT::add_attribute_lock,
        typename BaseT::remove_attribute_lock
    >::type open_record_lock;

protected:
    // Lock-less implementation of operations
    template< typename ArgsT >
    record_type open_record_unlocked(ArgsT const& args);
};

// A convenience metafunction to specify the feature
// in the list of features of the final logger later
struct record_tagger :
    public boost::mpl::quote1< record_tagger_feature >
{
};

You can see that we use the strictest_lock template in order to define lock types that would fulfill the base class thread safety requirements for methods that are to be called from the corresponding methods of record_tagger_feature. The open_record_lock definition shows that the open_record_unlocked implementation for the record_tagger_feature feature requires exclusive lock (which lock_guard is) for the logger, but it also takes into account locking requirements of the open_record_unlocked, add_attribute_unlocked and remove_attribute_unlocked methods of the base class, because it will have to call them. The generated open_record method of the final logger class will make use of this typedef in order to automatically acquire the corresponding lock type before forwarding to the open_record_unlocked methods.

Frankly speaking, in this particular example, there was no need to use the strictest_lock trait, because all our methods require exclusive locking, which is already the strictest one. However, this template may come in handy if you use shared locking.

The implementation of the public interface becomes quite trivial:

template< typename BaseT >
record_tagger_feature< BaseT >::record_tagger_feature()
{
}

template< typename BaseT >
record_tagger_feature< BaseT >::record_tagger_feature(record_tagger_feature const& that) :
    BaseT(static_cast< BaseT const& >(that))
{
}

template< typename BaseT >
template< typename ArgsT >
record_tagger_feature< BaseT >::record_tagger_feature(ArgsT const& args) : BaseT(args)
{
}

Now, since all locking is extracted into the public interface, we have the most of our feature logic to be implemented in the protected part of the interface. In order to set up tag value in the logger, we will have to introduce a new Boost.Parameter keyword. Following recommendations from that library documentation, it's better to introduce the keyword in a special namespace:

namespace my_keywords {

    BOOST_PARAMETER_KEYWORD(tag_ns, tag)

}

Opening a new record can now look something like this:

template< typename BaseT >
template< typename ArgsT >
record_type record_tagger_feature< BaseT >::open_record_unlocked(ArgsT const& args)
{
    // Extract the named argument from the parameters pack
    string_type tag_value = args[my_keywords::tag | string_type()];

    attribute_set_type& attrs = BaseT::attributes();
    typename attribute_set_type::iterator tag = attrs.end();
    if (!tag_value.empty())
    {
        // Add the tag as a new attribute
        boost::shared_ptr< logging::attribute > attr(
            new logging::constant< string_type >(tag_value));
        std::pair<
            typename attribute_set_type::iterator,
            bool
        > res = BaseT::add_attribute_unlocked("Tag", attr);
        if (res.second)
            tag = res.first;
    }

    // In any case, after opening a record remove the tag from the attributes
    BOOST_SCOPE_EXIT((&tag)(&attrs))
    {
        if (tag != attrs.end())
            attrs.erase(tag);
    }
    BOOST_SCOPE_EXIT_END

    // Forward the call to the base feature
    return BaseT::open_record_unlocked(args);
}

Here we add a new attribute with the tag value, if one is specified in call to open_record. When a log record is opened, all attribute values are acquired and locked after the record, so we remove the tag from the attribute set with the Boost.ScopeExit block.

Ok, we got our feature, and it's time to inject it into a logger. Assume we want to combine it with the standard severity level logging. No problems:

template< typename LevelT = int >
class my_logger :
    public src::basic_composite_logger<
        char,                       // character type for the logger
        my_logger,                  // final logger type
        src::single_thread_model,   // the logger does not perform thread synchronization
                                    // use multi_thread_model to declare a thread-safe logger
        src::features<              // the list of features we want to combine
            src::severity< LevelT >,
            record_tagger
        >
    >
{
    // The following line will automatically generate forwarding constructors that
    // will call to the corresponding constructors of the base class
    BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_TEMPLATE(my_logger)
};

As you can see, creating a logger is a quite simple procedure. The BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_TEMPLATE macro you see here is for mere convenience purpose: it unfolds into a default constructor, copy constructor and a number of constructors to support named arguments. For non-template loggers there is a similar BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS macro.

To use this logger we can now write the following:

enum severity_level
{
    normal,
    warning,
    error
};

my_logger< severity_level > logger;

logging::record rec = logger.open_record((keywords::severity = normal, my_keywords::tag = "[GUI]"));
if (rec)
{
    rec.message() = "The user has confirmed his choice";
    logger.push_record(rec);
}

However, I would prefer defining a special macro to reduce verbosity:

#define LOG_WITH_TAG(lg, sev, tg) \
    BOOST_LOG_WITH_PARAMS((lg), (keywords::severity = (sev))(my_keywords::tag = (tg)))

LOG_WITH_TAG(logger, normal, "[GUI]") << "The user has confirmed his choice";

Guidelines for the complete logging source designers

In general, you can implement new logging sources the way you like, the library does not mandate any design requirements on log sources. However, there are some notes regarding the way log sources should interact with logging core.