Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
Next

Chapter 1. Boost.Log v2

Andrey Semashev

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt).

Table of Contents

Introduction
Motivation
How to read the documentation
Definitions
Installation and compatibility
Supported compilers and platforms
Configuring and building the library
Design overview
Tutorial
Trivial logging
Trivial logging with filters
Setting up sinks
Creating loggers and writing logs
Adding more information to log: Attributes
Log record formatting
Filtering revisited
Wide character logging
Detailed features description
Core facilities
Logging sources
Sink frontends
Sink backends
Lambda expressions
Attributes
Utilities
Extending the library
Writing your own sinks
Writing your own sources
Writing your own attributes
Extending library settings support
Rationale and FAQ
Why string literals as scope names?
Why scoped attributes don't override existing attributes?
Why log records are weakly ordered in a multithreaded application?
Why attributes set with stream manipulators do not participate in filtering?
Why not using lazy streaming?
Why not using hierarchy of loggers, like in log4j? Why not Boost.Log4j? Etc.
Does Boost.Log support process forking?
Does Boost.Log support logging at process initialization and termination?
Why my application crashes on process termination when file sinks are used?
Why my application fails to link with Boost.Log? What's the fuss about library namespaces?
Why MSVC 2010 fails to link the library with error LNK1123: failure during conversion to COFF: file invalid or corrupt?
How to use Boost.Log in libraries?
Reference
Top level headers
Core components
Attributes
Expressions
Logging sources
Sinks
Utilities
Other libraries support layer
Changelog
TODO in future releases
Acknowledgments

Today applications grow rapidly, becoming complicated and difficult to test and debug. Most of the time applications run on a remote site, leaving the developer little chance to monitor their execution and figure out the reasons for their failure, once it should happen. Moreover, even the local debugging may become problematic if the application behavior depends heavily on asynchronous side events, such as a device feedback or another process activity.

This is where logging can help. The application stores all essential information about its execution to a log, and when something goes wrong this information can be used to analyze the program behavior and make the necessary corrections. There are other very useful applications of logging, such as gathering statistical information and highlighting events (i.e. indicating that some situation has occurred or that the application is experiencing some problems). These tasks have proved to be vital for many real-world industrial applications.

This library aims to make logging significantly easier for the application developer. It provides a wide range of out-of-the-box tools along with public interfaces for extending the library. The main goals of the library are:

  • Simplicity. A small example code snippet should be enough to get the feel of the library and be ready to use its basic features.
  • Extensibility. A user should be able to extend functionality of the library for collecting and storing information into logs.
  • Performance. The library should have as little performance impact on the user's application as possible.

The documentation is oriented to both new and experienced library users. However, users are expected to be familiar with commonly used Boost components, such as shared_ptr, make_shared (see Boost.SmartPtr), and function (Boost.Function). Some parts of the documentation will refer to other Boost libraries, as needed.

If this is your first experience with the library, it is recommended to read the Design overview section for a first glance at the library's capabilities and architecture. The Installation and Tutorial sections will help to get started experimenting with the library. The tutorial gives an overview of the library features with sample code snippets. Some tutorial steps are presented in two forms: simple and advanced. The simple form typically describes the most common and easy way to do the task and it is being recommended to be read by new users. The advanced form usually gives an expanded way to do the same thing but with an in-depth explanation and the ability to do some extra customization. This form may come in handy for more experienced users and should generally be read if the easy way does not satisfy your needs.

Besides the tutorial there is a Detailed features description chapter. This part describes other tools provided by the library that were not covered by the tutorial. This chapter is best read on a case by case basis.

Last, but not least, there is a Reference section which gives the formal description of library component interfaces.

To keep the code snippets in this documentation simple, the following namespace aliases are assumed to be defined:

namespace logging = boost::log;
namespace sinks = boost::log::sinks;
namespace src = boost::log::sources;
namespace expr = boost::log::expressions;
namespace attrs = boost::log::attributes;
namespace keywords = boost::log::keywords;

Note that most of the examples are followed by a link to a complete compilable code sample, with all the necessary includes and auxiliary code, if any, that was stripped from the documentation for brevity. Relevant includes are also listed at the beginning of sections.

Here are definitions of some terms that will be used widely throughout the documentation:

Log record

A single bundle of information, collected from the user's application, that is a candidate to be put into the log. In a simple case the log record will be represented as a line of text in the log file after being processed by the logging library.

Attribute

An "attribute" is a piece of meta-information that can be used to specialize a log record. In Boost.Log, attributes are represented by function objects with a specific interface, which return the actual attribute value when invoked. Some example of attributes are a function returning current clock time, a function returning a monotonously increading log record counter, etc.

Attribute value

Attribute values are the actual data acquired from attributes. This data is attached to the specific log record and processed by the library. Values can have different types (integers, strings and more complex, including user defined types). Some examples of attribute values: current time stamp value, file name, line number, current scope name, etc. Attribute values are enveloped in a type erasing wrapper, so the actual type of the attribute is not visible in the interface. The actual (erased) type of the value is sometimes called the stored type.

(Attribute) value visitation

A way of processing the attribute value. This approach involves a function object (a visitor) which is applied to the attribute value. The visitor should know the stored type of the attribute value in order to process it.

(Attribute) value extraction

A way of processing the attribute value when the caller attempts to obtain a reference to the stored value. The caller should know the stored type of the attribute value in order to be able to extract it.

Log source

An entry point for the user's application to put log records to. In a simple case it is an object (logger) which maintains a set of attributes that will be used to form a log record upon the user's request. However, one can surely create a source that would emit log records on some side events (for example, by intercepting and parsing console output of another application).

Log sink

A target, to which all log records are fed after being collected from the user's application. The sink defines where and how the log records are going to be stored or processed.

Log filter

A predicate that takes a log record and tells whether this record should be passed through for further processing or discarded. The predicate typically forms its decision based on the attribute values attached to the record.

Log formatter

A function object that generates the final textual output from a log record. Some sinks, e.g. a binary logging sink, may not need it, although almost any text-based sink would use a formatter to compose its output.

Logging core

A global entity that maintains a list of sinks and applies filters to records generated by log sources. In the user's application, it is mainly used when the logging library is configured. There is only one instance of the logging core in an application.

i18n

Internationalization. The ability to manipulate wide characters.

TLS

Thread-local storage. The concept of having a variable that has independent values for each thread that attempts to access it.

RTTI

Run-time type information. This is the C++ language support data structures required for dynamic_cast and typeid operators to function properly.


Next