#include <boost/log/utility/manipulators/to_log.hpp>

Функция<to_log>создает манипулятор потока, который просто выводит принятое значение в поток. По умолчанию его поведение эквивалентно простому размещению значения в потоке. Однако пользователь может перегрузить<operator<<>для принятого значения, чтобы переопределить поведение форматирования, когда значения отформатированы для целей регистрации. Это обычно желательно, когда обычный<operator<<>используется для других задач (таких как сериализация), и его поведение не подходит для регистрации и не может быть легко изменено. Например:

std::ostream& operator<<
(
    std::ostream& strm,
    logging::to_log_manip< int > const& manip
)
{
    strm << std::setw(4) << std::setfill('0') << std::hex << manip.get() << std::dec;
    return strm;
}
void test_manip()
{
    std::cout << "Regular output: " << 1010 << std::endl;
    std::cout << "Log output: " << logging::to_log(1010) << std::endl;
}

Второе заявление о потоковой передаче в функции<test_manip>будет ссылаться на нашего оператора ввода потока, который определяет специальные правила форматирования.

Также можно определить различные правила форматирования для разных контекстов значений. Библиотека использует эту функцию, чтобы разрешить различное форматирование для разных значений атрибутов, даже если тип сохраненного значения одинаков. Для этого необходимо указать явный аргумент шаблона<to_log>, тип тега, который будет встроен в тип манипулятора и, таким образом, позволит определить различные операторы вставки:

struct tag_A;
struct tag_B;
std::ostream& operator<<
(
    std::ostream& strm,
    logging::to_log_manip< int, tag_A > const& manip
)
{
    strm << "A[" << manip.get() << "]";
    return strm;
}
std::ostream& operator<<
(
    std::ostream& strm,
    logging::to_log_manip< int, tag_B > const& manip
)
{
    strm << "B[" << manip.get() << "]";
    return strm;
}
void test_manip_with_tag()
{
    std::cout << "Regular output: " << 1010 << std::endl;
    std::cout << "Log output A: " << logging::to_log< tag_A >(1010) << std::endl;
    std::cout << "Log output B: " << logging::to_log< tag_B >(1010) << std::endl;
}

См. полный код.

	Note
	Библиотека использует<basic_formatting_ostream>тип потока для форматирования записей, поэтому при настройке правил форматирования значений атрибутов<operator<<>необходимо использовать<basic_formatting_ostream>вместо<std::ostream>.

#include <boost/log/utility/manipulators/add_value.hpp>

Функция<add_value>создает манипулятор, который прикрепляет значение атрибута к записи журнала. Этот манипулятор может использоваться только в потоковых выражениях с типом потока<basic_record_ostream>(что имеет место при форматировании сообщения записи журнала). Поскольку текст сообщения отформатирован только после фильтрации, значения атрибутов, прилагаемые к этому манипулятору, не влияют на фильтрацию и могут использоваться только в форматировщиках и поглотителях.

В дополнение к самому значению, манипулятор также требует, чтобы имя атрибута было предоставлено. Например:

// Creates a log record with attribute value "MyAttr" of type int attached
BOOST_LOG(lg) << logging::add_value("MyAttr", 10) << "Hello world!";

#include <boost/log/utility/manipulators/dump.hpp>

Функция<dump>создает манипулятор, который выводит двоичное содержимое смежных областей памяти. Это может быть полезно для регистрации некоторых двоичных данных низкого уровня, таких как закодированные сетевые пакеты или записи двоичного файла. Использование довольно простое:

void on_receive(std::vector< unsigned char > const& packet)
{
    // Outputs something like "Packet received: 00 01 02 0a 0b 0c"
    BOOST_LOG(lg) << "Packet received: " << logging::dump(packet.data(), packet.size());
}

Манипулятор также позволяет ограничить объем выводимых данных, если входные данные могут быть слишком большими. Просто укажите максимальное количество байтов ввода для демпинга в качестве последнего аргумента:

void on_receive(std::vector< unsigned char > const& packet)
{
    // Outputs something like "Packet received: 00 01 02 03 04 05 06 07 and 67 bytes more"
    BOOST_LOG(lg) << "Packet received: " << logging::dump(packet.data(), packet.size(), 8);
}

Существует еще один манипулятор под названием<dump_elements>для печати двоичного представления небайтовых элементов массива. Специальный манипулятор для этого случая необходим, потому что единицы аргумента размера<dump>могут сбивать с толку (в байтах или в элементах?). Поэтому<dump>не будет компилироваться при использовании для небайтовых входных данных.<dump_elements>принимает одни и те же аргументы, а аргументы, связанные с размером, всегда определяют количество элементов для обработки.

void process(std::vector< double > const& matrix)
{
    // Note that dump_elements accepts the number of elements in the matrix, not its size in bytes
    BOOST_LOG(lg) << "Matrix dump: " << logging::dump_elements(matrix.data(), matrix.size());
}

	Tip
	Оба этих манипулятора также могут использоваться с регулярными выходными потоками, не обязательно лесозаготовителями.

#include <boost/log/utility/ipc/object_name.hpp>

В современных операционных системах ресурсы системы, разделенные процессами, обычно идентифицируются с именами. К сожалению, разные системы имеют разные требования к синтаксису имени и разрешенному набору символов. Кроме того, некоторые системы предлагают поддержку пространств имен, чтобы избежать столкновений имен. Класс<object_name>призван скрывать эти различия.

Имя объекта может быть построено из идентификатора строки UTF-8 и области. Портативный идентификатор может содержать следующие символы:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 . _ -

	Note
	Набор символов соответствуетPOSIX Portable Filename Character Set.

Использование других символов может привести к непортативному системному поведению.

Сфера охвата определяется перечислением<object_name::scope>:

Сферы не пересекаются. Например, если объект создан в глобальном масштабе, объект не может быть открыт с тем же именем, но в объеме пользователя. Некоторые области могут потребовать повышенных привилегий для создания или открытия объектов.

	Warning
	Определение названия объекта не должно рассматриваться как мера безопасности. Объекты по-прежнему могут быть доступны процессам за пределами их области имен. Основная цель сфер применения состоит в том, чтобы избежать столкновений имен между различными процессами с использованием<object_name>. Используйте разрешения доступа для контроля безопасности.

#include <boost/log/utility/ipc/reliable_message_queue.hpp>

Класс 263 реализует надежный односторонний канал передачи сообщений от одного или нескольких авторов к одному читателю. Формат сообщений определяется пользователем и должен соответствовать всем авторам и читателю. Очередь не обеспечивает какой-либо конкретный формат сообщений, кроме того, что они должны быть предоставлены в виде смежного массива байтов. Очередь внутри использует совместно используемое хранилище, идентифицированное именем объекта(имя очереди).

Очередь хранения организована как фиксированное количество блоков фиксированного размера. Размер блока должен быть целочисленной мощностью 2 и выражается в байтах. Каждое письменное сообщение вместе с некоторыми метаданными, добавленными в очередь, потребляет целое число блоков. Каждое прочитанное сообщение, полученное читателем, высвобождает блоки, выделенные для этого сообщения. Таким образом, максимальный размер сообщения немного меньше, чем пропускная способность очереди. Для эффективности рекомендуется выбрать размер блока, достаточно большой, чтобы разместить большинство сообщений, которые будут переданы через очередь. Очередь считается пустой, когда нет сообщений (все блоки свободны). Очередь считается полной в точке очереди сообщения, когда не хватает свободных блоков для размещения сообщения.

Очередь надежна тем, что она не упадет успешно отправленными сообщениями, которые не получены читателем, кроме случая, когда непустая очередь уничтожается последним пользователем. Если сообщение не может быть поставлено в очередь автором, потому что очередь заполнена, очередь будет действовать в зависимости от политики переполнения, указанной при создании очереди:

Политика носит объектно-локальный характер, т.е. разные авторы и читатели могут иметь разную политику переполнения. Вот пример записи в очередь сообщений:

int main()
{
    typedef logging::ipc::reliable_message_queue queue_t;
    // Create a message_queue_type object that is associated with the interprocess
    // message queue named "ipc_message_queue".
    queue_t queue
    (
        keywords::name = logging::ipc::object_name(logging::ipc::object_name::user, "ipc_message_queue"),
        keywords::open_mode = logging::open_mode::open_or_create,  
        keywords::capacity = 256,                                  
        keywords::block_size = 1024,                               
        keywords::overflow_policy = queue_t::fail_on_overflow      
    );
    // Send a message through the queue
    std::string message = "Hello, Viewer!";
    queue_t::operation_result result = queue.send(message.data(), message.size());
    // See if the message was sent
    switch (result)
    {
    case queue_t::operation_result::succeeded:
        std::cout << "Message sent successfully" << std::endl;
        break;
    case queue_t::operation_result::no_space:
        std::cout << "Message could not be sent because the queue is full" << std::endl;
        break;
    case queue_t::operation_result::aborted:
        // This can happen is overflow_policy is block_on_overflow
        std::cout << "Message sending operation has been interrupted" << std::endl;
        break;
    }
    return 0;
}

См. полный код.

Как правило, очередь используется для отправки записей журнала в другой процесс. Таким образом, вместо того, чтобы использовать очередь для написания непосредственно, можно использовать специальный фон раковины для этого. См.<text_ipc_message_queue_backend>документацию.

Получение сообщений из очереди аналогично. Вот пример лог-просмотрщика, который получает сообщения из очереди и выводит их на консоль.

int main()
{
    try
    {
        typedef logging::ipc::reliable_message_queue queue_t;
        // Create a message_queue_type object that is associated with the interprocess
        // message queue named "ipc_message_queue".
        queue_t queue
        (
            keywords::name = logging::ipc::object_name(logging::ipc::object_name::user, "ipc_message_queue"),
            keywords::open_mode = logging::open_mode::open_or_create,
            keywords::capacity = 256,
            keywords::block_size = 1024,
            keywords::overflow_policy = queue_t::block_on_overflow
        );
        std::cout << "Viewer process running..." << std::endl;
        // Keep reading log messages from the associated message queue and print them on the console.
        // queue.receive() will block if the queue is empty.
        std::string message;
        while (queue.receive(message) == queue_t::succeeded)
        {
            std::cout << message << std::endl;
            // Clear the buffer for the next message
            message.clear();
        }
    }
    catch (std::exception& e)
    {
        std::cout << "Failure: " << e.what() << std::endl;
    }
    return 0;
}

См. полный код.

	Note
	Очередь не гарантирует какого-либо конкретного порядка получаемых сообщений от разных авторов. Сообщения, отправленные конкретным автором, будут получены в порядке отправки.

Заблокированный читатель или автор может быть разблокирован по телефону<stop_local>. После того, как этот метод называется, все нити, заблокированные на этом конкретном объекте, высвобождаются и возвращаются<operation_result::aborted>. Другие случаи очереди (в текущих или других процессах) не затрагиваются. Чтобы восстановить нормальное функционирование экземпляра очереди после вызова<stop_local>, пользователь должен вызвать<reset_local>.

#include <boost/log/utility/setup/console.hpp>
#include <boost/log/utility/setup/file.hpp>
#include <boost/log/utility/setup/common_attributes.hpp>

Библиотека предоставляет ряд функций, которые упрощают некоторые общие процедуры инициализации, такие как регистрация атрибутов. Это не так много функциональности. Тем не менее, это экономит пару минут обучения библиотеке для новичка.

Регистрация на консоли приложения - это самый простой способ увидеть библиотеку журналов в действии. Для этого можно инициализировать библиотеку одним вызовом функции, например:

int main(int, char*[])
{
    // Initialize logging to std::clog
    logging::add_console_log();
    // Here we go, we can write logs right away
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";
    return 0;
}

Довольно просто, не так ли? Существует также функция<wadd_console_log>для широкохарактерной консоли. Если вы хотите поместить журналы в какой-то другой стандартный поток, вы можете передать поток функции<add_console_log>в качестве аргумента. Например, возможность регистрации в<std::cout>вместо<std::clog>будет выглядеть следующим образом:

logging::add_console_log(std::cout);

Важно то, что вы можете дополнительно управлять раковиной консоли, если сохраните<shared_ptr>до раковины, которую эта функция возвращает. Это позволяет настроить такие вещи, как фильтр, формататор и автоматический флаг.

int main(int, char*[])
{
    // Initialize logging to std::clog
    boost::shared_ptr<
        sinks::synchronous_sink< sinks::text_ostream_backend >
    > sink = logging::add_console_log();
    sink->set_filter(expr::attr< int >("Severity") >= 3);
    sink->locked_backend()->auto_flush(true);
    // Here we go, we can write logs right away
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";
    return 0;
}

Аналогично консоли, можно использовать один вызов функции, чтобы включить вход в файл. Все, что вам нужно сделать, это указать имя файла:

int main(int, char*[])
{
    // Initialize logging to the "test.log" file
    logging::add_file_log("test.log");
    // Here we go, we can write logs right away
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";
    return 0;
}

Функции<add_console_log>и<add_file_log>не конфликтуют и могут свободно комбинироваться, поэтому можно настроить вход в консоль и пару файлов, включая фильтрацию и форматирование, примерно в 10 строках кода.

Наконец, есть функция<add_common_attributes>, которая регистрирует два часто используемых атрибута: «LineID» и «TimeStamp». Первый считает запись журнала сделанной и имеет значение атрибута<unsignedint>. Последнее, как следует из его названия, предоставляет текущее время для каждой записи журнала в виде<boost::posix_time::ptime>(см.Boost.DateTime). Эти два атрибута зарегистрированы во всем мире, поэтому они будут доступны во всех потоках и регистраторах. Это делает окончательную версию нашего образца кода примерно такой:

int main(int, char*[])
{
    // Initialize sinks
    logging::add_console_log()->set_filter(expr::attr< int >("Severity") >= 4);
    logging::formatter formatter =
        expr::stream
            << expr::attr< unsigned int >("LineID") << ": "
            << expr::format_date_time< boost::posix_time::ptime >("TimeStamp", "%Y-%m-%d %H:%M:%S") << " *"
            << expr::attr< int >("Severity") << "* "
            << expr::message;
    logging::add_file_log("complete.log")->set_formatter(formatter);
    boost::shared_ptr<
        sinks::synchronous_sink< sinks::text_ostream_backend >
    > sink = logging::add_file_log("essential.log");
    sink->set_formatter(formatter);
    sink->set_filter(expr::attr< int >("Severity") >= 1);
    // Register common attributes
    logging::add_common_attributes();
    // Here we go, we can write logs
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";
    return 0;
}

#include <boost/log/utility/setup/filter_parser.hpp>
#include <boost/log/utility/setup/formatter_parser.hpp>

Парсеры фильтров и форматеров позволяют создавать фильтры и формататоры из описательной строки. Функция<parse_filter>отвечает за распознавание фильтров и<parse_formatter>— за распознавание формататоров.

В случае фильтров струна образуется из последовательности выражений состояний, связанных с булевыми операциями. Поддерживаются две операции: соединение (обозначенное как «&» или «и») и разъединение (« |» или «или»). Каждое условие само по себе может быть либо одним условием, либо подфильтром, взятым в круглые скобки. Каждое условие можно свести на нет с помощью ключевого слова «!» или «нет». Условие, если оно не является подфильтром, обычно состоит из имени атрибута, заключенного в символах % («%»), ключевом слове отношения и операнде. Отношение и операнд могут быть опущены, и в этом случае условие считается требованием присутствия атрибута (с любым типом).

filter:
    condition { op condition }
op:
    &
    and
    |
    or
condition:
    !condition
    not condition
    (filter)
    %attribute_name%
    %attribute_name% relation operand
relation:
    >
    <
    =
    !=
    >=
    <=
    begins_with
    ends_with
    contains
    matches

Ниже приведены некоторые примеры фильтров:

Синтаксис строки форматера еще проще и в значительной степени напоминаетBoost. Форматсинтаксис строк. Струна интерпретируется как шаблон, который может содержать имена атрибутов, прилагаемые знаками % («%»). Соответствующие значения атрибутов заменят эти заполнители при применении форматтера. Заполнитель «%Message%» будет заменен текстом записи журнала. Например, следующая строка форматтера:

[%TimeStamp%] *%Severity%* %Message%

Записи журналов будут выглядеть так:

[2008-07-05 13:44:23] *0* Hello world

	Note
	Предыдущие выпуски библиотеки также поддерживали заполнитель «%_%» для текста сообщения. Этот заполнитель теперь обесценен, хотя он все еще работает для обратной совместимости. Его поддержка будет удалена в будущих выпусках.

Следует отметить, что по умолчанию библиотека поддерживает только те типы значений атрибутов, которые известныво время построения библиотеки. Определенные пользователем типы не будут работать должным образом в разрезанных фильтрах и форматировщиках, пока не будут зарегистрированы в библиотеке. Также возможно переопределение правил форматирования известных типов, включая поддержку дополнительных параметров форматирования в шаблоне строк. Подробнее об этом можно прочитать вРасширение библиотеки.

Note

Парсированные формататоры и фильтры, как правило, менее оптимальны, чем эквивалентные, написанные в коде с выражениями шаблонов. Это связано с двумя причинами: (*) программист обычно знает больше о типах значений атрибутов, которые могут быть задействованы в форматировании или фильтрации, и (*) компилятор имеет больше шансов оптимизировать формататор или фильтр, если он известен во время компиляции. Поэтому, когда производительность имеет значение, рекомендуется избегать разрозненных фильтров и форматировщиков.

#include <boost/log/utility/setup/settings.hpp>
#include <boost/log/utility/setup/from_settings.hpp>

Заголовки определяют компоненты для инициализации библиотеки из контейнера настроек. Контейнер настроек представляет собой набор именованных параметров, разделенных на разделы. Контейнер реализован с шаблоном класса<basic_settings>. Существует несколько ограничений на то, как параметры хранятся в контейнере:

Таким образом, контейнер настроек представляет собой многоуровневый ассоциативный контейнер со строковыми ключами и значениями. В некотором отношении он похож наBoost.PropertyTree, и фактически он поддерживает строительство из<boost::ptree>. Поддерживаемые параметры описаны ниже.

	Tip
	В таблицах ниже тип<CharT>обозначает тип символа, который используется с контейнером настроек.

Настройки поглотителей разделены на отдельные подразделы в рамках общего раздела верхнего уровня «Поглотители» - по одному подразделу для каждой раковины. Имена подраздела обозначают имя раковины, определенное пользователем. Например, «Мой файл».

Note

Предыдущие версии библиотеки также поддерживали разделы верхнего уровня, начиная с префикса «Sink:» для описания параметров раковины. Этот синтаксис теперь обесценен, хотя он все еще работает при разборе файла настроек для обратной совместимости. Парсер автоматически поместит эти разделы под секцией верхнего уровня «Sinks» в результирующий контейнер настроек. Поддержка этого синтаксиса будет удалена в будущих выпусках.

Помимо общих настроек, которые поддерживают все раковины, некоторые бэкэнды раковины также принимают ряд конкретных параметров. Эти параметры должны быть указаны в том же разделе.

	Warning
	Исправитель текстового файла используетBoost.Filesystemвнутренне, что может вызвать проблемы при прекращении процесса. См.здесьдля более подробной информации.

Вращение на основе времени может быть настроено с одним из двух параметров: RotationInterval или RotationTimePoint. Для данной раковины следует указывать не более одного из этих параметров. Если ничего не указано, ротация на основе времени не будет выполняться.

Параметр RotationTimePoint должен иметь один из следующих форматов, согласно обозначению форматаBoost.DateTime:

Пользователь может свободно заполнять контейнер настроек из любого источника настроек, который ему нужен. Пример использования приведен ниже:

void init_logging()
{
    logging::settings setts;
    setts["Core"]["Filter"] = "%Severity% >= warning";
    setts["Core"]["DisableLogging"] = false;
    // Subsections can be referred to with a single path
    setts["Sinks.Console"]["Destination"] = "Console";
    setts["Sinks.Console"]["Filter"] = "%Severity% >= fatal";
    setts["Sinks.Console"]["AutoFlush"] = true;
    // ...as well as the individual parameters
    setts["Sinks.File.Destination"] = "TextFile";
    setts["Sinks.File.FileName"] = "MyApp_%3N.log";
    setts["Sinks.File.AutoFlush"] = true;
    setts["Sinks.File.RotationSize"] = 10 * 1024 * 1024; // 10 MiB
    logging::init_from_settings(setts);
}

Считыватель настроек также позволяет расширяться для поддержки пользовательских типов раковины. СмотретьРасширение разделадля получения дополнительной информации.

#include <boost/log/utility/setup/from_stream.hpp>

Поддержка конфигурационных файлов является часто запрашиваемой функцией библиотеки. И несмотря на то, что в конечном итоге отсутствует удобный и гибкий формат настроек библиотеки, библиотека обеспечивает предварительную поддержку этой функции. Функция реализована с помощью простой функции<init_from_stream>, которая принимает поток ввода STL и считывает из него настройки библиотеки. Затем функция переходит на настройки чтения к функции<init_from_settings>, описаннойвыше. Следовательно, имена параметров и их значение одинаковы для функции<init_from_settings>.

Формат настроек довольно прост и широко используется. Ниже приведено описание синтаксиса и параметров.

# Comments are allowed. Comment line begins with the '#' character
# and spans until the end of the line.
# Logging core settings section. May be omitted if no parameters specified within it.
[Core]
DisableLogging=false
Filter="%Severity% > 3"
# Sink settings sections
[Sinks.MySink1]
# Sink destination type
Destination=Console
# Sink-specific filter. Optional, by default no filter is applied.
Filter="%Target% contains \"MySink1\""
# Formatter string. Optional, by default only log record message text is written.
Format="<%TimeStamp%> - %Message%"
# The flag shows whether the sink should be asynchronous
Asynchronous=false
# Enables automatic stream flush after each log record.
AutoFlush=true

Вот пример использования:

int main(int, char*[])
{
    // Read logging settings from a file
    std::ifstream file("settings.ini");
    logging::init_from_stream(file);
    return 0;
}