...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Sometimes trivial logging doesn't provide enough flexibility. For example, one may want a more sophisticated logic of log processing, rather than simply printing it on the console. In order to customize this, you have to construct logging sinks and register them with the logging core. This should normally be done only once somewhere in the startup code of your application.
Note | |
---|---|
It must be mentioned that in the previous sections we did not initialize any sinks, and trivial logging worked somehow anyway. This is because the library contains a default sink that is used as a fallback when the user did not set up any sinks. This sink always prints log records to the console in a fixed format which we saw in our previous examples. The default sink is mostly provided to allow trivial logging to be used right away, without any library initialization whatsoever. Once you add any sinks to the logging core, the default sink will no longer be used. You will still be able to use trivial logging macros though. |
As a starting point, here is how you would initialize logging to a file:
void init() { logging::add_file_log("sample.log"); logging::core::get()->set_filter ( logging::trivial::severity >= logging::trivial::info ); }
The added piece is the call to the add_file_log
function. As the name
implies, the function initializes a logging sink that stores log records
into a text file. The function also accepts a number of customization options,
such as the file rotation interval and size limits. For instance:
void init() { logging::add_file_log ( keywords::file_name = "sample_%N.log", keywords::rotation_size = 10 * 1024 * 1024, keywords::time_based_rotation = sinks::file::rotation_at_time_point(0, 0, 0), keywords::format = "[%TimeStamp%]: %Message%" ); logging::core::get()->set_filter ( logging::trivial::severity >= logging::trivial::info ); }
You can see that the options are passed to the function in the named form. This approach is also taken in many other places of the library. You'll get used to it. The meaning of the parameters is mostly self-explaining and is documented in this manual (see here for what regards the text file sink). This and other convenience initialization functions are described in this section.
Note | |
---|---|
You can register more than one sink. Each sink will receive and process log records as you emit them independently from others. |
If you don't want to go into details, you can skip this section and continue reading from the next one. Otherwise, if you need more comprehensive control over sink configuration or want to use more sinks than those available through helper functions, you can register sinks manually.
In the simplest form, the call to the add_file_log
function in the section above is nearly equivalent to this:
void init() { // Construct the sink typedef sinks::synchronous_sink< sinks::text_ostream_backend > text_sink; boost::shared_ptr< text_sink > sink = boost::make_shared< text_sink >(); // Add a stream to write log to sink->locked_backend()->add_stream( boost::make_shared< std::ofstream >("sample.log")); // Register the sink in the logging core logging::core::get()->add_sink(sink); }
Ok, the first thing you may have noticed about sinks is that they are composed
of two classes: the frontend and the backend. The frontend (which is the
synchronous_sink
class template in the snippet above) is responsible for various common tasks
for all sinks, such as thread synchronization model, filtering and, for text-based
sinks, formatting. The backend (the text_ostream_backend
class above)
implements everything specific to the sink, such as writing to a file in
this case. The library provides a number of frontends and backends that can
be used with each other out of the box.
The synchronous_sink
class template above indicates that the sink is synchronous, that is, it
allows for several threads to log simultaneously and will block in case of
contention. This means that the backend text_ostream_backend
doesn't have
to worry about multithreading at all. There are other sink frontends available,
you can read more about them here.
The text_ostream_backend
class writes
formatted log records into STL-compatible streams. We have used a file stream
above but we could have used any type of stream. For example, adding output
to console could look as follows:
#include <boost/core/null_deleter.hpp> // We have to provide an empty deleter to avoid destroying the global stream object boost::shared_ptr< std::ostream > stream(&std::clog, boost::null_deleter()); sink->locked_backend()->add_stream(stream);
The text_ostream_backend
supports adding
several streams. In that case its output will be duplicated to all added
streams. It can be useful to duplicate the output to console and file since
all the filtering, formatting and other overhead of the library happen only
once per record for the sink.
Note | |
---|---|
Please note the difference between registering several distinct sinks and registering one sink with several target streams. While the former allows for independently customizing output to each sink, the latter would work considerably faster if such customization is not needed. This feature is specific to this particular backend. |
The library provides a number of backends that provide different log processing logic. For instance, by specifying the syslog backend you can send log records over the network to the syslog server, or by setting up the Windows NT event log backend you can monitor your application run time with the standard Windows tools.
The last thing worth noting here is the locked_backend
member function call to access the sink backend. It is used to get thread-safe
access to the backend and is provided by all sink frontends. This function
returns a smart-pointer to the backend and as long as it exists the backend
is locked (which means even if another thread tries to log and the log record
is passed to the sink, it will not be logged until you release the backend).
The only exception is the unlocked_sink
frontend which does
not synchronize at all and simply returns an unlocked pointer to the backend.