# Sinks

Andrey Semashev

14.07.2009

The header contains implementation of asynchronous sink frontend. `unbounded_fifo_queue` basic_sink_frontend Asynchronous logging sink frontend.

The frontend starts a separate thread on construction. All logging records are passed to the backend in this dedicated thread only.

A scope guard that resets a flag on destructor. `frontend_mutex_type &``condition_variable_any &``boost::atomic< bool > &` `scoped_flag const &` scoped_flag &`scoped_flag const &` A scope guard that implements thread ID management. `frontend_mutex_type &``condition_variable_any &``thread::id &``boost::atomic< bool > &`Initializing constructor. `unique_lock< frontend_mutex_type > &``condition_variable_any &``thread::id &``boost::atomic< bool > &`Initializing constructor. Destructor. `scoped_thread_id const &` scoped_thread_id &`scoped_thread_id const &` Sink implementation type. SinkBackendT

A pointer type that locks the backend until it's destroyed

implementation_defined locked_backend_ptr

Locking accessor to the attached backend

void `record_view const &`

Enqueues the log record to the backend

bool `record_view const &`

The method attempts to pass logging record to the backend

void

The method starts record feeding loop and effectively blocks until either of this happens:

- the thread is interrupted due to either standard thread interruption or a call to `stop`

- an exception is thrown while processing a log record in the backend, and the exception is not terminated by the exception handler, if one is installed

The sink frontend must be constructed without spawning a dedicated thread

void

The method softly interrupts record feeding loop. This method must be called when the `run` method execution has to be interrupted. Unlike regular thread interruption, calling `stop` will not interrupt the record processing in the middle. Instead, the sink frontend will attempt to finish its business with the record in progress and return afterwards. This method can be called either if the sink was created with a dedicated thread, or if the feeding loop was initiated by user.

Returning from this method does not guarantee that there are no records left buffered in the sink frontend. It is possible that log records keep coming during and after this method is called. At some point of execution of this method log records stop being processed, and all records that come after this point are put into the queue. These records will be processed upon further calls to `run` or `feed_records`.

void

The method feeds log records that may have been buffered to the backend and returns

The sink frontend must be constructed without spawning a dedicated thread

void

The method feeds all log records that may have been buffered to the backend and returns. Unlike `feed_records`, in case of ordering queueing the method also feeds records that were enqueued during the ordering window, attempting to empty the queue completely.

`booltrue

If `true`, the frontend creates a thread to feed log records to the backend. Otherwise no thread is started and it is assumed that the user will call either `run` or `feed_records` himself.

`

Default constructor. Constructs the sink backend instance. Requires the backend to be default-constructible.

`shared_ptr< sink_backend_type > const &

Pointer to the backend instance.

``booltrue

If `true`, the frontend creates a thread to feed log records to the backend. Otherwise no thread is started and it is assumed that the user will call either `run` or `feed_records` himself.

`

Constructor attaches user-constructed backend instance

backend is not `NULL`.

Destructor. Implicitly stops the dedicated feeding thread, if one is running.

Andrey Semashev

07.11.2008

The header contains facilities that are used in different sinks to map attribute values used throughout the application to values used with the specific native logging API. These tools are mostly needed to map application severity levels on native levels, required by OS-specific sink backends. Base class for attribute mapping function objects. Mapped value type. MappedT Result type. mapped_type int boost::log::sinks::basic_mapping< MappedT >Straightforward mapping.

This type of mapping assumes that attribute with a particular name always provides values that map directly onto the native values. The mapping simply returns the extracted attribute value converted to the native value.

Attribute contained value type. AttributeValueT Mapped value type. base_type::mapped_type mapped_type `record_view const &

A log record to extract value from

`

Extraction operator

An extracted attribute value

`attribute_name const &

Attribute name

``mapped_type const &

The default native value that is returned if the attribute value is not found

`

Constructor

int boost::log::sinks::basic_mapping< MappedT >Customizable mapping.

The class allows to setup a custom mapping between an attribute and native values. The mapping should be initialized similarly to the standard `map` container, by using indexing operator and assignment.

Unlike many other components of the library, exact type of the attribute value must be specified in the template parameter `AttributeValueT`. Type sequences are not supported.

Attribute contained value type. AttributeValueT Mapped value type. base_type::mapped_type mapped_type `record_view const &

A log record to extract value from

`

Extraction operator. Extracts the attribute value and attempts to map it onto the native value.

A mapped value, if mapping was successful, or the default value if mapping did not succeed.

implementation_defined `attribute_value_type const &

Attribute value to be mapped

`

Insertion operator

An object of unspecified type that allows to insert a new mapping through assignment. The key argument becomes the key attribute value, and the assigned value becomes the mapped native value.

`attribute_name const &

Attribute name

``mapped_type const &

The default native value that is returned if the conversion cannot be performed

`

Constructor

Andrey Semashev

04.11.2007

The header contains implementation of base classes for sink backends. Base class for a logging sink backend.

The ``basic_sink_backend`` class template defines a number of types that all sink backends are required to define. All sink backends have to derive from the class.

Frontend requirements tag. FrontendRequirementsT ``basic_sink_backend` const &` `basic_sink_backend` &``basic_sink_backend` const &` `synchronized_feeding` basic_sink_backend< combine_requirements< FrontendRequirementsT, formatted_records >::type >A base class for a logging sink backend with message formatting support.

The ``basic_formatted_sink_backend`` class template indicates to the frontend that the backend requires logging record formatting.

The class allows to request encoding conversion in case if the sink backend requires the formatted string in some particular encoding (e.g. if underlying API supports only narrow or wide characters). In order to perform conversion one should specify the desired final character type in the `TargetCharT` template parameter.

Character type. CharT Formatted string type. std::basic_string< char_type > Frontend requirements. base_type::frontend_requirements

Andrey Semashev

14.07.2009

The header contains implementation of a base class for sink frontends. sink A base class for a logging sink frontend. An exception handler type. base_type::exception_handler_type void `FunT const &`

The method sets sink-specific filter functional object

void

The method resets the filter

void `FunT const &`

The method sets an exception handler function

void

The method resets the exception handler function

bool `attribute_value_set const &

A set of attribute values of a logging record

`

The method returns `true` if no filter is set or the attribute values pass the filter

`bool

The flag indicates whether the sink passes log records between different threads

`Initializing constructor.

mutex_type &Returns reference to the frontend mutex. exception_handler_type &Returns reference to the exception handler. exception_handler_type const &Returns reference to the exception handler. void `record_view const &``BackendMutexT &``BackendT &`Feeds log record to the backend. bool `record_view const &``BackendMutexT &``BackendT &`Attempts to feeds log record to the backend, does not block if backend_mutex is locked. void `BackendMutexT &``BackendT &`Flushes record buffers in the backend, if one supports it. void `BackendMutexT &``BackendT &``mpl::true_`Flushes record buffers in the backend (the actual implementation) void `BackendMutexT &``BackendT &``mpl::false_`Flushes record buffers in the backend (stub for backends that don't support flushing) basic_sink_frontend A base class for a logging sink frontend with formatting support. const unsigned int Object version. string_type Formatted log record storage. stream_type Formatting stream. formatter_type Formatter functor. `unsigned int` `std::locale const &``formatter_type const &` Character type. CharT Formatted string type. std::basic_string< char_type > Formatter function object type. basic_formatter< char_type > Output stream type. formatter_type::stream_type void `FunT const &`

The method sets sink-specific formatter function object

void

The method resets the formatter

std::locale

The method returns the current locale used for formatting

void `std::locale const &`

The method sets the locale used for formatting

`bool

The flag indicates whether the sink passes log records between different threads

`Initializing constructor.

formatter_type &Returns reference to the formatter. void `record_view const &``BackendMutexT &``BackendT &`Feeds log record to the backend. bool `record_view const &``BackendMutexT &``BackendT &`Attempts to feeds log record to the backend, does not block if backend_mutex is locked.

Andrey Semashev

04.01.2012

The header contains implementation of `block_on_overflow` strategy for handling queue overflows in bounded queues for the asynchronous sink frontend. Blocking strategy for handling log record queue overflows.

This strategy will cause enqueueing threads to block when the log record queue overflows. The blocked threads will be woken as soon as there appears free space in the queue, in the same order they attempted to enqueue records.

Andrey Semashev

04.01.2012

The header contains implementation of bounded FIFO queueing strategy for the asynchronous sink frontend. std::size_t Bounded FIFO log record queueing strategy.

The ``bounded_fifo_queue`` class is intended to be used with the ``asynchronous_sink`` frontend as a log record queueing strategy.

This strategy describes log record queueing logic. The queue has a limited capacity, upon reaching which the enqueue operation will invoke the overflow handling strategy specified in the `OverflowStrategyT` template parameter to handle the situation. The library provides overflow handling strategies for most common cases: ``drop_on_overflow`` will silently discard the log record, and ``block_on_overflow`` will put the enqueueing thread to wait until there is space in the queue.

The log record queue imposes no ordering over the queued elements aside from the order in which they are enqueued.

void `record_view const &`Enqueues log record to the queue. bool `record_view const &`Attempts to enqueue log record to the queue. bool `record_view &`Attempts to dequeue a log record ready for processing from the queue, does not block if the queue is empty. bool `record_view &`Attempts to dequeue log record from the queue, does not block if the queue is empty. bool `record_view &`Dequeues log record from the queue, blocks if the queue is empty. void Wakes a thread possibly blocked in the `dequeue` method. Default constructor. `ArgsT const &`Initializing constructor.

Andrey Semashev

06.01.2012

The header contains implementation of bounded ordering queueing strategy for the asynchronous sink frontend. std::size_t Bounded ordering log record queueing strategy.

The ``bounded_ordering_queue`` class is intended to be used with the ``asynchronous_sink`` frontend as a log record queueing strategy.

This strategy provides the following properties to the record queueing mechanism:

- The queue has limited capacity specified by the `MaxQueueSizeV` template parameter.

- Upon reaching the size limit, the queue invokes the overflow handling strategy specified in the `OverflowStrategyT` template parameter to handle the situation. The library provides overflow handling strategies for most common cases: ``drop_on_overflow`` will silently discard the log record, and ``block_on_overflow`` will put the enqueueing thread to wait until there is space in the queue.

- The queue has a fixed latency window. This means that each log record put into the queue will normally not be dequeued for a certain period of time.

- The queue performs stable record ordering within the latency window. The ordering predicate can be specified in the `OrderT` template parameter.

posix_time::time_duration

Returns ordering window size specified during initialization

posix_time::time_duration

Returns default ordering window size. The default window size is specific to the operating system thread scheduling mechanism.

void `record_view const &`Enqueues log record to the queue. bool `record_view const &`Attempts to enqueue log record to the queue. bool `record_view &`Attempts to dequeue a log record ready for processing from the queue, does not block if the queue is empty. bool `record_view &`Attempts to dequeue log record from the queue, does not block if the queue is empty. bool `record_view &`Dequeues log record from the queue, blocks if the queue is empty. void Wakes a thread possibly blocked in the `dequeue` method. `ArgsT const &`Initializing constructor.

Andrey Semashev

07.11.2008

The header contains a logging sink backend that outputs log records to the debugger. basic_formatted_sink_backend< CharT, concurrent_feeding >An implementation of a logging sink backend that outputs to the debugger.

The sink uses Windows API in order to write log records as debug messages, if the application process is run under debugger. The sink backend also provides a specific filter that allows to check whether the debugger is available and thus elide unnecessary formatting.

Character type. base_type::char_type String type to be used as a message text holder. base_type::string_type void `record_view const &``string_type const &`

The method passes the formatted message to debugger

Constructor. Initializes the sink backend.

Destructor

Convenience typedef for narrow-character logging. `basic_debug_output_backend`< char > Convenience typedef for wide-character logging. `basic_debug_output_backend`< wchar_t >

Andrey Semashev

04.01.2012

The header contains implementation of `drop_on_overflow` strategy for handling queue overflows in bounded queues for the asynchronous sink frontend. Log record dropping strategy.

This strategy will cause log records to be discarded in case of queue overflow in bounded asynchronous sinks. It should not be used if losing log records is not acceptable.

Andrey Semashev

07.11.2008

The header contains a logging sink backend that uses Windows NT event log API for signaling application events. basic_formatted_sink_backend< CharT, concurrent_feeding >An implementation of a simple logging sink backend that emits events into Windows NT event log.

The sink uses Windows NT 5 (Windows 2000) and later event log API to emit events to an event log. The sink acts as an event source in terms of the API, it implements all needed resources and source registration in the Windows registry that is needed for the event delivery.

The backend performs message text formatting. The composed text is then passed as the first and only string parameter of the event. The resource embedded into the backend describes the event so that the parameter is inserted into the event description text, thus making it visible in the event log.

The backend allows to customize mapping of application severity levels to the native Windows event types. This allows to write portable code even if OS-specific sinks, such as this one, are used.

Since the backend registers itself into Windows registry as the resource file that contains event description, it is important to keep the library binary in a stable place of the filesystem. Otherwise Windows might not be able to load event resources from the library and display events correctly.

It is known that Windows is not able to find event resources in the application executable, which is linked against the static build of the library. Users are advised to use dynamic builds of the library to solve this problem.

Character type. base_type::char_type String type to be used as a message text holder. base_type::string_type Mapper type for the event type. unspecified void `event_type_mapper_type const &`

The method installs the function object that maps application severity levels to WinAPI event types

void `record_view const &``string_type const &`

The method puts the formatted message to the event log

Default constructor. Registers event source with name based on the application executable file name in the Application log. If such a registration is already present, it is not overridden.

typename... `ArgsT...const &

A set of named parameters.

`

Constructor. Registers event log source with the specified parameters. The following named parameters are supported:

- `target` - Specifies an UNC path to the remote server which log records should be sent to. The local machine will be used to process log records, if not specified.

- `log_name` - Specifies the log in which the source should be registered. The result of `get_default_log_name` is used, if the parameter is not specified.

- `log_source` - Specifies the source name. The result of `get_default_source_name` is used, if the parameter is not specified.

- `registration` - Specifies the event source registration mode in the Windows registry. Can have values of the `registration_mode` enum. Default value: `on_demand`.

Destructor. Unregisters event source. The log source description is not removed from the Windows registry.

string_type

Default log name: Application

string_type

Default log source name that is based on the application executable file name and the sink name

basic_sink_backend< synchronized_feeding >An implementation of a logging sink backend that emits events into Windows NT event log.

The sink uses Windows NT 5 (Windows 2000) and later event log API to emit events to an event log. The sink acts as an event source. Unlike ``basic_simple_event_log_backend``, this sink backend allows users to specify the custom event message file and supports mapping attribute values onto several insertion strings. Although it requires considerably more scaffolding than the simple backend, this allows to support localizable event descriptions.

Besides the file name of the module with event resources, the backend provides the following customizations:

- Remote server UNC address, log name and source name. These parameters have similar meaning to ``basic_simple_event_log_backend``.

- Event type and category mappings. These are function object that allow to map attribute values to the according event parameters. One can use mappings in the `event_log` namespace.

- Event composer. This function object extracts event identifier and formats string insertions, that will be used by the API to compose the final event message text.

Character type. CharT String type. std::basic_string< char_type > Type of the composed insertions list. std::vector< string_type > Mapper type for the event type. unspecified Mapper type for the event category. unspecified Event composer type. unspecified void `record_view const &

Log record to consume

`

The method creates an event in the event log

void `event_type_mapper_type const &`

The method installs the function object that maps application severity levels to WinAPI event types

void `event_category_mapper_type const &`

The method installs the function object that extracts event category from attribute values

void `event_composer_type const &`

The method installs the function object that extracts event identifier from the attributes and creates insertion strings that will replace placeholders in the event message.

`std::basic_string< T > const &`

Constructor. Registers event source with name based on the application executable file name in the Application log. If such a registration is already present, it is not overridden.

`filesystem::path const &`

Constructor. Registers event source with name based on the application executable file name in the Application log. If such a registration is already present, it is not overridden.

typename... `ArgsT...const &

A set of named parameters.

`

Constructor. Registers event log source with the specified parameters. The following named parameters are supported:

- `message_file` - Specifies the file name that contains resources that describe events and categories. This parameter is mandatory unless `registration` is `never`.

- `target` - Specifies an UNC path to the remote server to which log records should be sent to. The local machine will be used to process log records, if not specified.

- `log_name` - Specifies the log in which the source should be registered. The result of `get_default_log_name` is used, if the parameter is not specified.

- `log_source` - Specifies the source name. The result of `get_default_source_name` is used, if the parameter is not specified.

- `registration` - Specifies the event source registration mode in the Windows registry. Can have values of the `registration_mode` enum. Default value: `on_demand`.

Destructor. Unregisters event source. The log source description is not removed from the Windows registry.

string_type

Default log name: Application

string_type

Default log source name that is based on the application executable file name and the sink name

int basic_direct_mapping< event_type, AttributeValueT >Straightforward event type mapping.

This type of mapping assumes that attribute with a particular name always provides values that map directly onto the native event types. The mapping simply returns the extracted attribute value converted to the native event type.

`attribute_name const &

Attribute name

`

Constructor

int basic_custom_mapping< event_type, AttributeValueT >Customizable event type mapping.

The class allows to setup a custom mapping between an attribute and native event types. The mapping should be initialized similarly to the standard `map` container, by using indexing operator and assignment.

`attribute_name const &

Attribute name

`

Constructor

int basic_direct_mapping< event_id, AttributeValueT >Straightforward event ID mapping.

This type of mapping assumes that attribute with a particular name always provides values that map directly onto the event identifiers. The mapping simply returns the extracted attribute value converted to the event ID.

`attribute_name const &

Attribute name

`

Constructor

int basic_custom_mapping< event_id, AttributeValueT >Customizable event ID mapping.

The class allows to setup a custom mapping between an attribute and event identifiers. The mapping should be initialized similarly to the standard `map` container, by using indexing operator and assignment.

`attribute_name const &

Attribute name

`

Constructor

int basic_direct_mapping< event_category, AttributeValueT >Straightforward event category mapping.

This type of mapping assumes that attribute with a particular name always provides values that map directly onto the event categories. The mapping simply returns the extracted attribute value converted to the event category.

`attribute_name const &

Attribute name

`

Constructor

int basic_custom_mapping< event_category, AttributeValueT >Customizable event category mapping.

The class allows to setup a custom mapping between an attribute and event categories. The mapping should be initialized similarly to the standard `map` container, by using indexing operator and assignment.

`attribute_name const &

Attribute name

`

Constructor

An event composer.

This class is a function object that extracts event identifier from the attribute values set and formats insertion strings for the particular event. Each insertion string is formatted with a distinct formatter, which can be created just like regular sinks formatters.

Before using, the composer must be initialized with the following information:

- Event identifier extraction logic. One can use `basic_direct_event_id_mapping` or `basic_custom_event_id_mapping` classes in order to create such extractor and pass it to the composer constructor.

- Event identifiers and insertion string formatters. The composer provides the following syntax to provide this information:

         event_composer comp;
         comp[MY_EVENT_ID1] % formatter1 % ... % formatterN;
         comp[MY_EVENT_ID2] % formatter1 % ... % formatterN;
         ...

The event identifiers in square brackets are provided by the message compiler generated header (the actual names are specified in the .mc file). The formatters represent the insertion strings that will be used to replace placeholders in event messages, thus the number and the order of the formatters must correspond to the message definition.

Character type. CharT String type to be used as a message text holder. std::basic_string< char_type > Event identifier mapper type. unspecified Type of an insertion composer (a formatter) basic_formatter< char_type > Type of the composed insertions list. std::vector< string_type > void``basic_event_composer` &`

Swaps `*this` and `that` objects.

event_map_reference `event_id

Event identifier.

`

Initiates creation of a new event description. The result of the operator can be used to add formatters for insertion strings construction. The returned reference type is implementation detail.

event_map_reference `int

Event identifier.

`

Initiates creation of a new event description. The result of the operator can be used to add formatters for insertion strings construction. The returned reference type is implementation detail.

event_id `record_view const &

Log record view

``insertion_list &

A sequence of formatted insertion strings

`

Event composition operator. Extracts an event identifier from the attribute values by calling event ID mapper. Then runs all formatters that were registered for the event with the extracted ID. The results of formatting are returned in the insertions parameter.

An event identifier that was extracted from `attributes`

`event_id_mapper_type const &

An event identifier mapping function that will be used to extract event ID from attribute values

`

Default constructor. Creates an empty map of events.

``basic_event_composer` const &`

Copy constructor. Performs a deep copy of the object.

Destructor

`basic_event_composer` &``basic_event_composer``

Assignment. Provides strong exception guarantee.

Never register event source, even if it's not registered. Register if the source is not registered yet. Register always, event if the source is already registered. Event log source registration modes. Convenience typedef for narrow-character logging. `basic_event_composer`< char > Convenience typedef for wide-character logging. `basic_event_composer`< wchar_t > Convenience typedef for narrow-character logging. `basic_simple_event_log_backend`< char > Convenience typedef for narrow-character logging. `basic_event_log_backend`< char > Convenience typedef for wide-character logging. `basic_simple_event_log_backend`< wchar_t > Convenience typedef for wide-character logging. `basic_event_log_backend`< wchar_t >

Andrey Semashev

07.11.2008

The header contains definition of constants related to Windows NT Event Log API. The constants can be used in other places without the event log backend. 0 Equivalent to EVENTLOG_SUCCESS. 4 Equivalent to EVENTLOG_INFORMATION_TYPE. 2 Equivalent to EVENTLOG_WARNING_TYPE. 1 Equivalent to EVENTLOG_ERROR_TYPE. Windows event types. A tagged integral type that represents event identifier for the Windows API. unspecified A tagged integral type that represents event category for the Windows API. unspecified `event_id`unsigned int`

The function constructs event identifier from an integer

` `event_category`unsigned short`

The function constructs event category from an integer

` `event_type`unsigned short`

The function constructs log record level from an integer

`

Andrey Semashev

22.04.2007

The header contains definition of requirement tags that sink backend may declare with regard to frontends. These requirements ensure that a backend will not be used with an incompatible frontend.

The sink backend expects pre-synchronized calls, all needed synchronization is implemented in the frontend (IOW, only one thread is feeding records to the backend concurrently, but it is possible for several threads to write sequentially). Note that if a frontend supports synchronized record feeding, it will also report capable of concurrent record feeding.

synchronized_feeding

The sink backend ensures all needed synchronization, it is capable to handle multithreaded calls

The sink backend requires the frontend to perform log record formatting before feeding

The sink backend supports flushing

A helper metafunction to check if a requirement is satisfied. The `TestedT` template argument should be the type combining one or several requirements and `RequiredT` is the requirement to test against. The metafunction will yield a positive result if `TestedT` supports `RequiredT`.

The macro specifies the maximum number of requirements that can be combined with the `combine_requirements` metafunction.

Andrey Semashev

22.04.2007

The header contains an interface declaration for all sinks. This interface is used by the logging core to feed log records to sinks. A base class for a logging sink frontend. An exception handler type. unspecified bool `attribute_value_set const &

A set of attribute values of a logging record

`

The method returns `true` if no filter is set or the attribute values pass the filter

void `record_view const &

Logging record to consume

`

The method puts logging record to the sink

bool `record_view const &

Logging record to consume

`

The method attempts to put logging record to the sink. The method may be used by the core in order to determine the most efficient order of sinks to feed records to in case of heavy contention. Sink implementations may implement try/backoff logic in order to improve overall logging throughput.

`true`, if the record was consumed, `false`, if not.

void

The method performs flushing of any internal buffers that may hold log records. The method may take considerable time to complete and may block both the calling thread and threads attempting to put new records into the sink while this call is in progress.

bool

The method indicates that the sink passes log records between different threads. This information is needed by the logging core to detach log records from all thread-specific resources before passing it to the sink.

`bool`

Default constructor

Virtual destructor

``sink` const &` `sink` &``sink` const &`

Andrey Semashev

14.07.2009

The header contains implementation of synchronous sink frontend. basic_sink_frontend Synchronous logging sink frontend.

The sink frontend serializes threads before passing logging records to the backend

Sink implementation type. SinkBackendT

A pointer type that locks the backend until it's destroyed

implementation_defined locked_backend_ptr

Locking accessor to the attached backend

void `record_view const &`

Passes the log record to the backend

bool `record_view const &`

The method attempts to pass logging record to the backend

void

The method performs flushing of any internal buffers that may hold log records. The method may take considerable time to complete and may block both the calling thread and threads attempting to put new records into the sink while this call is in progress.

Default constructor. Constructs the sink backend instance. Requires the backend to be default-constructible.

`shared_ptr< sink_backend_type > const &

Pointer to the backend instance

`

Constructor attaches user-constructed backend instance

backend is not `NULL`.

Andrey Semashev

08.01.2008

The header contains implementation of a Syslog sink backend along with its setup facilities. basic_formatted_sink_backend< char >An implementation of a syslog sink backend.

The backend provides support for the syslog protocol, defined in RFC3164. The backend sends log records to a remote host via UDP. The host name can be specified by calling the `set_target_address` method. By default log records will be sent to localhost:514. The local address can be specified as well, by calling the `set_local_address` method. By default syslog packets will be sent from any local address available.

It is safe to create several sink backends with the same local addresses - the backends within the process will share the same socket. The same applies to different processes that use the syslog backends to send records from the same socket. However, it is not guaranteed to work if some third party facility is using the socket.

On systems with native syslog implementation it may be preferable to utilize the POSIX syslog API instead of direct socket management in order to bypass possible security limitations that may be in action. To do so one has to pass the `use_impl = native` to the backend constructor. Note, however, that in that case you will only have one chance to specify syslog facility and process identification string - on the first native syslog backend construction. Other native syslog backends will ignore these parameters. Obviously, the `set_local_address` and `set_target_address` methods have no effect for native backends. Using `use_impl = native` on platforms with no native support for POSIX syslog API will have no effect.

Character type. base_type::char_type String type that is used to pass message test. base_type::string_type Syslog severity level mapper type. unspecified void `severity_mapper_type const &`

The method installs the function object that maps application severity levels to syslog levels

void `std::string const &

The local address

``unsigned short514

The local port number

`

The method sets the local host name which log records will be sent from. The host name is resolved to obtain the final IP address.

Does not have effect if the backend was constructed to use native syslog API

void `boost::asio::ip::address const &

The local address

``unsigned short514

The local port number

`

The method sets the local address which log records will be sent from.

Does not have effect if the backend was constructed to use native syslog API

void `std::string const &

The remote host address

``unsigned short514

The port number on the remote host

`

The method sets the remote host name where log records will be sent to. The host name is resolved to obtain the final IP address.

Does not have effect if the backend was constructed to use native syslog API

void `boost::asio::ip::address const &

The remote host address

``unsigned short514

The port number on the remote host

`

The method sets the address of the remote host where log records will be sent to.

Does not have effect if the backend was constructed to use native syslog API

void `record_view const &``string_type const &`

The method passes the formatted message to the syslog API or sends to a syslog server

Constructor. Creates a UDP socket-based backend with `syslog::user` facility code. IPv4 protocol will be used.

typename... `ArgsT...const &`

Constructor. Creates a sink backend with the specified named parameters. The following named parameters are supported:

- `facility` - Specifies the facility code. If not specified, `syslog::user` will be used.

- `use_impl` - Specifies the backend implementation. Can be one of:

- `native` - Use the native syslog API, if available. If no native API is available, it is equivalent to `udp_socket_based`.

- `udp_socket_based` - Use the UDP socket-based implementation, conforming to RFC3164 protocol specification. This is the default.

- `ip_version` - Specifies IP protocol version to use, in case if socket-based implementation is used. Can be either `v4` (the default one) or `v6`.

- `ident` - Process identification string. This parameter is only supported by native syslog implementation.

Destructor

int basic_direct_mapping< level, AttributeValueT >Straightforward severity level mapping.

This type of mapping assumes that attribute with a particular name always provides values that map directly onto the Syslog levels. The mapping simply returns the extracted attribute value converted to the Syslog severity level.

`attribute_name const &

Attribute name

`

Constructor

int basic_custom_mapping< level, AttributeValueT >Customizable severity level mapping.

The class allows to setup a custom mapping between an attribute and Syslog severity levels. The mapping should be initialized similarly to the standard `map` container, by using indexing operator and assignment.

`attribute_name const &

Attribute name

`

Constructor

0 Use native syslog API. 1 Use UDP sockets, according to RFC3164. The enumeration defined the possible implementation types for the syslog backend. Supported IP protocol versions.

Andrey Semashev

08.01.2008

The header contains definition of constants related to Syslog API. The constants can be used in other places without the Syslog backend. 0 Equivalent to LOG_EMERG in syslog API. 1 Equivalent to LOG_ALERT in syslog API. 2 Equivalent to LOG_CRIT in syslog API. 3 Equivalent to LOG_ERROR in syslog API. 4 Equivalent to LOG_WARNING in syslog API. 5 Equivalent to LOG_NOTICE in syslog API. 6 Equivalent to LOG_INFO in syslog API. 7 Equivalent to LOG_DEBUG in syslog API. Syslog record levels. 0 * 8 Kernel messages. 1 * 8 User-level messages. Equivalent to LOG_USER in syslog API. 2 * 8 Mail system messages. Equivalent to LOG_MAIL in syslog API. 3 * 8 System daemons. Equivalent to LOG_DAEMON in syslog API. 4 * 8 Security/authorization messages. 5 * 8 Messages from the syslogd daemon. Equivalent to LOG_SYSLOG in syslog API. 6 * 8 Line printer subsystem. Equivalent to LOG_LPR in syslog API. 7 * 8 Network news subsystem. Equivalent to LOG_NEWS in syslog API. 8 * 8 Messages from UUCP subsystem. Equivalent to LOG_UUCP in syslog API. 9 * 8 Messages from the clock daemon. 10 * 8 Security/authorization messages. 11 * 8 Messages from FTP daemon. 12 * 8 Messages from NTP daemon. 13 * 8 Security/authorization messages. 14 * 8 Security/authorization messages. 15 * 8 Messages from the clock daemon. 16 * 8 For local use. Equivalent to LOG_LOCAL0 in syslog API. 17 * 8 For local use. Equivalent to LOG_LOCAL1 in syslog API. 18 * 8 For local use. Equivalent to LOG_LOCAL2 in syslog API. 19 * 8 For local use. Equivalent to LOG_LOCAL3 in syslog API. 20 * 8 For local use. Equivalent to LOG_LOCAL4 in syslog API. 21 * 8 For local use. Equivalent to LOG_LOCAL5 in syslog API. 22 * 8 For local use. Equivalent to LOG_LOCAL6 in syslog API. 23 * 8 For local use. Equivalent to LOG_LOCAL7 in syslog API. Syslog facility codes. `level`int`

The function constructs log record level from an integer

` `facility`int`

The function constructs log source facility from an integer

`

Andrey Semashev

09.06.2009

The header contains implementation of a text file sink backend. basic_formatted_sink_backend< char, combine_requirements< synchronized_feeding, flushing >::type >An implementation of a text file logging sink backend.

The sink backend puts formatted log records to a text file. The sink supports file rotation and advanced file control, such as size and file count restriction.

Character type. base_type::char_type String type to be used as a message text holder. base_type::string_type Stream type. std::basic_ostream< char_type > File open handler. unspecified File close handler. unspecified Predicate that defines the time-based condition for file rotation. unspecified void `PathT const &

The name pattern for the file being written.

`

The method sets file name wildcard for the files being written. The wildcard supports date and time injection into the file name.

void `std::ios_base::openmode

File open mode

`

The method sets the file open mode

void `shared_ptr< `file::collector` > const &

The file collector function object

`

The method sets the log file collector function. The function is called on file rotation and is being passed the written file name.

void `open_handler_type const &

The file open handler function object

`

The method sets file opening handler. The handler will be called every time the backend opens a new temporary file. The handler may write a header to the opened file in order to maintain file validity.

void `close_handler_type const &

The file close handler function object

`

The method sets file closing handler. The handler will be called every time the backend closes a temporary file. The handler may write a footer to the opened file in order to maintain file validity.

void `uintmax_t

The maximum file size, in characters.

`

The method sets maximum file size. When the size is reached, file rotation is performed.

The size does not count any possible character translations that may happen in the underlying API. This may result in greater actual sizes of the written files.

void `time_based_rotation_predicate const &

The predicate that defines the time-based condition for file rotation. If empty, no time-based rotation will take place.

`

The method sets the predicate that defines the time-based condition for file rotation.

The rotation always occurs on writing a log record, so the rotation is not strictly bound to the specified condition.

void `booltrue`

Sets the flag to automatically flush buffers of all attached streams after each log record

uintmax_t `file::scan_methodfile::scan_matching

File scanning method

``booltrue

If `true` and method is `scan_matching`, the method attempts to update the internal file counter according to the found files. The counter is unaffected otherwise.

`

Performs scanning of the target directory for log files that may have been left from previous runs of the application. The found files are considered by the file collector as if they were rotated.

The file scan can be performed in two ways: either all files in the target directory will be considered as log files, or only those files that satisfy the file name pattern. See documentation on `sinks::file::collector::scan_for_files` for more information.

The method essentially delegates to the same-named function of the file collector.

File collector and the proper file name pattern have already been set.

The number of files found.

void `record_view const &``string_type const &`

The method writes the message to the sink

void

The method flushes the currently open log file

void

The method rotates the file

Default constructor. The constructed sink backend uses default values of all the parameters.

typename... `ArgsT...const &`

Constructor. Creates a sink backend with the specified named parameters. The following named parameters are supported:

- `file_name` - Specifies the file name pattern where logs are actually written to. The pattern may contain directory and file name portions, but only the file name may contain placeholders. The backend supports Boost.DateTime placeholders for injecting current time and date into the file name. Also, an additional N placeholder is supported, it will be replaced with an integral increasing file counter. The placeholder may also contain width specification in the printf-compatible form (e.g. %5N). The printed file counter will always be zero-filled. If `file_name` is not specified, pattern "%5N.log" will be used.

- `open_mode` - File open mode. The mode should be presented in form of mask compatible to `std::ios_base::openmode`. If not specified, `trunc | out` will be used.

- `rotation_size` - Specifies the approximate size, in characters written, of the temporary file upon which the file is passed to the file collector. Note the size does not count any possible character conversions that may take place during writing to the file. If not specified, the file won't be rotated upon reaching any size.

- `time_based_rotation` - Specifies the predicate for time-based file rotation. No time-based file rotations will be performed, if not specified.

- `auto_flush` - Specifies a flag, whether or not to automatically flush the file after each written log record. By default, is `false`.

Read the caution note regarding file name pattern in the `sinks::file::collector::scan_for_files` documentation.

Destructor

Base class for file collectors.

All file collectors, supported by file sink backends, should inherit this class.

void `filesystem::path const &

The name of the file to be stored

`

The function stores the specified file in the storage. May lead to an older file deletion and a long file moving.

uintmax_t `scan_method

The method of scanning. If `no_scan` is specified, the call has no effect.

``filesystem::path const &filesystem::path()

The file name pattern if method is `scan_matching`. Otherwise the parameter is not used.

``unsigned int *0

If not `NULL` and method is `scan_matching`, the method suggests initial value of a file counter that may be used in the file name pattern. The parameter is not used otherwise.

`

Scans the target directory for the files that have already been stored. The found files are added to the collector in order to be tracked and erased, if needed.

The function may scan the directory in two ways: it will either consider every file in the directory a log file, or will only consider files with names that match the specified pattern. The pattern may contain the following placeholders:

- y, Y, m, d - date components, in Boost.DateTime meaning.

- H, M, S, f - time components, in Boost.DateTime meaning.

- N - numeric file counter. May also contain width specification in printf-compatible form (e.g. %5N). The resulting number will always be zero-filled.

- %% - a percent sign

All other placeholders are not supported.

In case if method is `scan_matching` the effect of this function is highly dependent on the pattern definition. It is recommended to choose patterns with easily distinguished placeholders (i.e. having delimiters between them). Otherwise either some files can be mistakenly found or not found, which in turn may lead to an incorrect file deletion.

The number of found files.

Default constructor

Virtual destructor

``collector` const &` `collector` &``collector` const &`

The class represents the time point of log file rotation. One can specify one of three types of time point based rotation:

- rotation takes place every day, at the specified time

- rotation takes place on the specified day of every week, at the specified time

- rotation takes place on the specified day of every month, at the specified time

The time points are considered to be local time. bool bool

Checks if it's time to rotate the file

`unsigned char

The rotation hour, should be within 0 and 23

``unsigned char

The rotation minute, should be within 0 and 59

``unsigned char

The rotation second, should be within 0 and 59

`

Creates a rotation time point of every day at the specified time

`date_time::weekdays

The weekday of the rotation

``unsigned char0

The rotation hour, should be within 0 and 23

``unsigned char0

The rotation minute, should be within 0 and 59

``unsigned char0

The rotation second, should be within 0 and 59

`

Creates a rotation time point of each specified weekday at the specified time

`gregorian::greg_day

The monthday of the rotation, should be within 1 and 31

``unsigned char0

The rotation hour, should be within 0 and 23

``unsigned char0

The rotation minute, should be within 0 and 59

``unsigned char0

The rotation second, should be within 0 and 59

`

Creates a rotation time point of each specified day of month at the specified time

The class represents the time interval of log file rotation. The log file will be rotated after the specified time interval has passed.

bool bool

Checks if it's time to rotate the file

`posix_time::time_duration const &

The interval of the rotation, should be no less than 1 second

`

Creates a rotation time interval of the specified duration

Don't scan for stored files. Scan for files with names matching the specified mask. Scan for all files in the directory. The enumeration of the stored files scan methods. `shared_ptr< `collector` > typename... `ArgsT...const &`

The function creates a file collector for the specified target directory. Each target directory is managed by a single file collector, so if this function is called several times for the same directory, it will return a reference to the same file collector. It is safe to use the same collector in different sinks, even in a multithreaded application.

One can specify certain restrictions for the stored files, such as maximum total size or minimum free space left in the target directory. If any of the specified restrictions is not met, the oldest stored file is deleted. If the same collector is requested more than once with different restrictions, the collector will act according to the most strict combination of all specified restrictions.

The following named parameters are supported:

- `target` - Specifies the target directory for the files being stored in. This parameter is mandatory.

- `max_size` - Specifies the maximum total size, in bytes, of stored files that the collector will try not to exceed. If the size exceeds this threshold the oldest file(s) is deleted to free space. Note that the threshold may be exceeded if the size of individual files exceed the `max_size` value. The threshold is not maintained, if not specified.

- `min_free_space` - Specifies the minimum free space, in bytes, in the target directory that the collector tries to maintain. If the threshold is exceeded, the oldest file(s) is deleted to free space. The threshold is not maintained, if not specified.

- `max_files` - Specifies the maximum number of log files stored. If the number of files exceeds this threshold, the oldest file(s) is deleted to free space. The threshhold is not maintained if not specified.

The file collector.

`

Andrey Semashev

09.06.2009

The header contains implementation of a text multi-file sink backend. basic_formatted_sink_backend< char >An implementation of a text multiple files logging sink backend.

The sink backend puts formatted log records to one of the text files. The particular file is chosen upon each record's attribute values, which allows to distribute records into individual files or to group records related to some entity or process in a separate file.

Character type. base_type::char_type String type to be used as a message text holder. base_type::string_type File name composer functor type. unspecified void `ComposerT const &

File name composer functor

`

The method sets file name composer functional object. Log record formatters are accepted, too.

void `record_view const &``string_type const &`

The method writes the message to the sink

Default constructor. The constructed sink backend has no file name composer and thus will not write any files.

Destructor

An adapter class that allows to use regular formatters as file name generators.

Functor result type. filesystem::path File name character type. result_type::string_type::value_type The adopted formatter type. FormatterT Formatting stream type. basic_formatting_ostream< native_char_type > result_type `record_view const &`

The operator generates a file name based on the log record

`formatter_type const &``std::locale const &std::locale()`

Initializing constructor

``file_name_composer_adapter` const &`

Copy constructor

`file_name_composer_adapter` &``file_name_composer_adapter` const &`

Assignment

``file_name_composer_adapter`< FormatterT > `FormatterT const &``std::locale const &std::locale()`

The function adopts a log record formatter into a file name generator

`

Andrey Semashev

22.04.2007

The header contains implementation of a text output stream sink backend. basic_formatted_sink_backend< CharT, combine_requirements< synchronized_feeding, flushing >::type >An implementation of a text output stream logging sink backend.

The sink backend puts formatted log records to one or more text streams.

Character type. base_type::char_type String type to be used as a message text holder. base_type::string_type Output stream type. std::basic_ostream< char_type > void `shared_ptr< stream_type > const &

Pointer to the stream. Must not be NULL.

`

The method adds a new stream to the sink.

void `shared_ptr< stream_type > const &

Pointer to the stream. Must not be NULL.

`

The method removes a stream from the sink. If the stream is not attached to the sink, the method has no effect.

void `booltrue`

Sets the flag to automatically flush buffers of all attached streams after each log record

void `record_view const &``string_type const &`

The method writes the message to the sink

void

The method flushes the associated streams

Constructor. No streams attached to the constructed backend, auto flush feature disabled.

Destructor

Convenience typedef for narrow-character logging. `basic_text_ostream_backend`< char > Convenience typedef for wide-character logging. `basic_text_ostream_backend`< wchar_t >

Andrey Semashev

24.07.2011

The header contains implementation of unbounded FIFO queueing strategy for the asynchronous sink frontend. Unbounded FIFO log record queueing strategy.

The ``unbounded_fifo_queue`` class is intended to be used with the ``asynchronous_sink`` frontend as a log record queueing strategy.

This strategy implements the simplest logic of log record buffering between threads: the queue has no limits and imposes no ordering over the queued elements aside from the order in which they are enqueued. Because of this the queue provides decent performance and scalability, however if sink backends can't consume log records fast enough the queue may grow uncontrollably. When this is an issue, it is recommended to use one of the bounded strategies.

void `record_view const &`Enqueues log record to the queue. bool `record_view const &`Attempts to enqueue log record to the queue. bool `record_view &`Attempts to dequeue a log record ready for processing from the queue, does not block if the queue is empty. bool `record_view &`Attempts to dequeue log record from the queue, does not block if the queue is empty. bool `record_view &`Dequeues log record from the queue, blocks if the queue is empty. void Wakes a thread possibly blocked in the `dequeue` method. Default constructor. `ArgsT const &`Initializing constructor.

Andrey Semashev

24.07.2011

The header contains implementation of unbounded ordering record queueing strategy for the asynchronous sink frontend. Unbounded ordering log record queueing strategy.

The ``unbounded_ordering_queue`` class is intended to be used with the ``asynchronous_sink`` frontend as a log record queueing strategy.

This strategy provides the following properties to the record queueing mechanism:

- The queue has no size limits.

- The queue has a fixed latency window. This means that each log record put into the queue will normally not be dequeued for a certain period of time.

- The queue performs stable record ordering within the latency window. The ordering predicate can be specified in the `OrderT` template parameter.

Since this queue has no size limits, it may grow uncontrollably if sink backends dequeue log records not fast enough. When this is an issue, it is recommended to use one of the bounded strategies. posix_time::time_duration

Returns ordering window size specified during initialization

posix_time::time_duration

Returns default ordering window size. The default window size is specific to the operating system thread scheduling mechanism.

void `record_view const &`Enqueues log record to the queue. bool `record_view const &`Attempts to enqueue log record to the queue. bool `record_view &`Attempts to dequeue a log record ready for processing from the queue, does not block if no log records are ready to be processed. bool `record_view &`Attempts to dequeue log record from the queue, does not block. bool `record_view &`Dequeues log record from the queue, blocks if no log records are ready to be processed. void Wakes a thread possibly blocked in the `dequeue` method. `ArgsT const &`Initializing constructor. void `record_view const &`Enqueues a log record.

Andrey Semashev

14.07.2009

The header contains declaration of an unlocked sink frontend. basic_sink_frontend Non-blocking logging sink frontend.

The sink frontend does not perform thread synchronization and simply passes logging records to the sink backend.

Sink implementation type. SinkBackendT

Type of pointer to the backend

shared_ptr< sink_backend_type > locked_backend_ptr

Locking accessor to the attached backend.

Does not do any actual locking, provided only for interface consistency with other frontends.

void `record_view const &`

Passes the log record to the backend

void

The method performs flushing of any internal buffers that may hold log records. The method may take considerable time to complete and may block both the calling thread and threads attempting to put new records into the sink while this call is in progress.

Default constructor. Constructs the sink backend instance. Requires the backend to be default-constructible.

`shared_ptr< sink_backend_type > const &

Pointer to the backend instance

`

Constructor attaches user-constructed backend instance

backend is not `NULL`.