Boost.Log

In Boost.Log, a sink is the destination for log records. It is composed of two parts:

1. Frontend: Manages general sink behavior, such as threading models (e.g., synchronous_sink) and filtering. It handles thread synchronization so that the backend does not have to.
2. Backend: Implements the actual logic for formatting and storing log records (e.g., text_ostream_backend).

To use a sink, you typically instantiate a frontend with a specific backend, configure the backend (like adding output streams), and then register the sink with the logging core.

// Create a synchronous sink frontend with a text stream backend
typedef sinks::synchronous_sink< sinks::text_ostream_backend > text_sink;
shared_ptr< text_sink > pSink(new text_sink);

// Access the backend safely using a locked pointer
text_sink::locked_backend_ptr pBackend = pSink->locked_backend();

// Add a stream to the backend
shared_ptr< std::ostream > pStream(&std::clog, boost::null_deleter());
pBackend->add_stream(pStream);

// Register the sink with the core
logging::core::get()->add_sink(pSink);

You can initialize logging using utility functions like logging::add_file_log. This allows you to specify a filename and a format for the log records. The format can be constructed using boost::log::expressions (e.g., expr::stream, expr::format_date_time, expr::message).

To support specific character encodings (like UTF-8) for wide character logging, you can retrieve the sink object and call imbue() with a std::locale (for example, using boost::locale::generator).

Common attributes like timestamps and record counters can be added globally using logging::add_common_attributes().

// Declare attribute keywords for use in formatting
BOOST_LOG_ATTRIBUTE_KEYWORD(severity, "Severity", severity_level)
BOOST_LOG_ATTRIBUTE_KEYWORD(timestamp, "TimeStamp", boost::posix_time::ptime)

void init_logging()
{
    // Create a file sink with a specific format
    boost::shared_ptr< sinks::synchronous_sink< sinks::text_file_backend > > sink = logging::add_file_log
    (
        "sample.log",
        keywords::format = expr::stream
            << expr::format_date_time(timestamp, "%Y-%m-%d, %H:%M:%S.%f")
            << " <" << severity.or_default(normal)
            << "> " << expr::message
    );

    // Set locale for character code conversion (e.g., UTF-8)
    std::locale loc = boost::locale::generator()("en_US.UTF-8");
    sink->imbue(loc);

    // Add common attributes like timestamp
    logging::add_common_attributes();
}

You can configure Boost.Log dynamically using a settings file (via logging::init_from_stream) by registering custom factories for filters and formatters. This allows the settings file to reference custom attribute types or complex formatting logic by name.

To use custom factories:

1. Implement a formatter_factory: Create a class inheriting from logging::formatter_factory<T> and implement create_formatter to return your custom formatter.
2. Register the factory: Use logging::register_formatter_factory(name, factory_ptr) to map a string name (used in the settings file) to your factory.
3. Register simple factories: For types that support operator<< and operator>>, use logging::register_simple_filter_factory<T>(name) and logging::register_simple_formatter_factory<T, CharType>(name).
4. Load settings: Call logging::init_from_stream(stream) to parse the configuration.

// 1. Define a custom factory
class my_scopes_formatter_factory : public logging::formatter_factory<char> {
public:
    formatter_type create_formatter(logging::attribute_name const& attr_name, args_map const& args) {
        return formatter_type(scope_list_formatter(attr_name));
    }
};

// 2. Register and initialize
void init_logging() {
    // Register custom formatter factory
    logging::register_formatter_factory("MyScopes", boost::make_shared<my_scopes_formatter_factory>());

    // Register simple factories for custom enums (requires operator<< and operator>>)
    logging::register_simple_filter_factory<severity_level>("Severity");
    logging::register_simple_formatter_factory<severity_level, char>("Severity");

    // Load from file
    std::ifstream settings("settings.txt");
    logging::init_from_stream(settings);

    logging::add_common_attributes();
}

You can use boost::log::sinks::text_multifile_backend wrapped in a synchronous_sink to direct log records to different files simultaneously based on attribute values.

To implement this:

1. Define a text_multifile_backend inside a synchronous_sink.
2. Use set_file_name_composer with sinks::file::as_file_name_composer to define a naming pattern that includes an attribute (e.g., a thread ID).
3. Use BOOST_LOG_SCOPED_THREAD_TAG or similar mechanisms to attach the relevant attribute to the log records in different threads.
4. Register the sink with boost::log::core::get()->add_sink(sink).

This allows the sink to automatically separate log records into different files (e.g., logs/thread_id.log) depending on the value of the specified attribute.

// Create a text file sink using a multifile backend
typedef sinks::synchronous_sink< sinks::text_multifile_backend > file_sink;
shared_ptr< file_sink > sink(new file_sink);

// Set up how the file names will be generated using an attribute (e.g., "ThreadID")
sink->locked_backend()->set_file_name_composer(
    sinks::file::as_file_name_composer(
        expr::stream << "logs/" << expr::attr< std::thread::id >("ThreadID") << ".log"
    )
);

// Set the log record formatter
sink->set_formatter(
    expr::format("%1%: [%2%] - %3%")
        % expr::attr< unsigned int >("RecordID")
        % expr::attr< boost::posix_time::ptime >("TimeStamp")
        % expr::smessage
);

// Add it to the core
logging::core::get()->add_sink(sink);

// Add global attributes to the core
logging::core::get()->add_global_attribute("TimeStamp", attrs::local_clock());
logging::core::get()->add_global_attribute("RecordID", attrs::counter< unsigned int >());

// In a thread, tag the scope with the attribute used for file naming
void thread_foo()
{
    BOOST_LOG_SCOPED_THREAD_TAG("ThreadID", std::this_thread::get_id());
    BOOST_LOG(my_logger::get()) << "Log record";
}

To implement asynchronous logging that limits memory usage and ensures log records are written in a specific order (even when produced by multiple threads), use sinks::asynchronous_sink combined with a sinks::bounded_ordering_queue.

Key components:

• sinks::asynchronous_sink<Backend, Queue>: Wraps a backend to process logs in a separate thread.
• sinks::bounded_ordering_queue<Ordering, Capacity, OverflowStrategy>:
  • Ordering: Defines how records are sorted (e.g., logging::attribute_value_ordering).
  • Capacity: The maximum number of records allowed in the queue.
  • OverflowStrategy: Defines behavior when the queue is full (e.g., sinks::block_on_overflow to wait for space).
• logging::make_attr_ordering<T>(AttributeName, Comparator): Used during sink construction to tell the queue which attribute to use for sorting records.

To ensure all logs are written before the application exits, call sink->stop() and sink->flush().

// Define the backend (e.g., text file stream)
typedef sinks::text_ostream_backend backend_t;

// Define the asynchronous sink with a bounded, ordering queue
typedef sinks::asynchronous_sink<
    backend_t,
    sinks::bounded_ordering_queue<
        logging::attribute_value_ordering< unsigned int, std::less< unsigned int > ability, 
        128,                        // Max 128 records in queue
        sinks::block_on_overflow    // Block the producer if queue is full
    >
> sink_t;

// Initialize the sink with ordering based on a "RecordID" attribute
shared_ptr< sink_t > sink(new sink_t(
    boost::make_shared< backend_t >(),
    keywords::order = logging::make_attr_ordering< unsigned int >("RecordID", std::less< unsigned int >())
));

// Add to core and set attributes for ordering
logging::core::get()->add_sink(sink);
logging::core::get()->add_global_attribute("RecordID", attrs::counter< unsigned int >());

// ... logging operations ...

// Cleanup
sink->stop();
sink->flush();

To log messages to a native syslog server (like syslogd), use the boost::log::sinks::syslog_backend within a synchronous sink. You must define the implementation type and the syslog facility using keywords during sink construction.

Key steps:

1. Define a sink using sinks::synchronous_sink<sinks::syslog_backend>.
2. Use keywords::use_impl = sinks::syslog::native to specify the native API.
3. Specify the syslog facility (e.g., sinks::syslog::local7) using keywords::facility.
4. Map application-specific severity levels to syslog levels using sinks::syslog::custom_severity_mapping and register it with the backend via set_severity_mapper.
5. Register the sink with the logging core using logging::core::get()->add_sink(sink).

// Create a syslog sink using the native implementation
shared_ptr< sinks::synchronous_sink< sinks::syslog_backend > > sink(
    new sinks::synchronous_sink< sinks::syslog_backend>(
        keywords::use_impl = sinks::syslog::native,
        keywords::facility = sinks::syslog::local7
    )
);

// Map custom application severity levels to syslog levels
sinks::syslog::custom_severity_mapping< severity_levels > mapping("Severity");
mapping[normal] = sinks::syslog::info;
mapping[warning] = sinks::syslog::warning;
mapping[error] = sinks::syslog::critical;

// Apply the mapping to the backend
sink->locked_backend()->set_severity_mapper(mapping);

// Register the sink with the core
logging::core::get()->add_sink(sink);