logging

Logging

mqtt_cpp outputs log messages using Boost.Log.

Compile option

You need to add the following compile option to use logging functionality.

-DMQTT_USE_LOG -DBOOST_LOG_DYN_LINK -lboost_log -lboost_filesystem -lboost_thread

Setup

By default, mqtt_cpp use the default Boost.Log settings. Custom setup is usually convenient.

Typical setup

mqtt_cpp provides a typical logging setting.

First, include the following file:

#include <mqtt/setup_log.hpp>

Next, call setup_log().

int main() {
    ...

    mqtt::setup_log(
        {
            { "mqtt_api", mqtt::severity_level::trace },
            { "mqtt_cb", mqtt::severity_level::debug },
        }
    );

    ...

The setup takes std::map<mqtt::channel, mqtt::severity_level>. You can set the threshold severity_level by each channel.

You can also call setup_log() like as follows:

int main() {
    ...

    mqtt::setup_log(
        mqtt::severity_level::warning
    );

    ...

The threshold is applied for all channels.

channel

Channel describes what kind of message.

channel	description
mqtt_api	API is called
mqtt_cb	event is occurred

severity

High priority                Low priority
fatal, error, warning, info, debug, trace

Custom setup

Typical setup is convenient way if Boost.Log user is only mqtt_cpp. However, your code or other library might use Boost.Log too. In this case, you need to setup logging by yourself instead of the typical setup.

The function setup_log() in setup_log.hpp is a reference implementation. You can write your own formatter and filter. Logging is a kind of crosscutting concern. So you need to mixed setup for all Boost.Log users including mqtt_cpp at the beginning of the code. It is typically at int main().

Use custom logger instead of Boost.Log (for advanced user)

mqtt_cpp use the macro MQTT_LOG(chan, sev) << ... << ... for logging. See https://github.com/redboltz/mqtt_cpp/blob/be306b3d59e285368f7086d8ef04af3fc5c3d46f/include/mqtt/log.hpp#L116-L125

You can define your own MQTT_LOG before include mqtt_cpp headers.

Similarly, mqtt_cpp defines MQTT_ADD_VALUE(name, value) to pass named value to the logger. You can define your own MQTT_ADD_VALUE before include mqtt_cpp headers.

I personally don't recommend this way. Boost.Log is very flexible. You can setup as follows:

mqtt_cpp --> Boost.Log --> Boost.Log sync adaptor for your custom logger 

See https://www.boost.org/libs/log/doc/html/log/extension.html#log.extension.sinks

Disabling log at the compile time

To disable all logs, remove -DMQTT_USE_LOG option.

You can disable less than specific severity level logs.

MQTT_LOG_SEV is compile-time severity_level threshold. If you set the macro MQTT_LOG_SEV to 4, then only error and fatal logging codes are generated.

Here is severity value mapping.

severity	value
trace	0
debug	1
info	2
warning	3
error	4
fatal	5

Logging example

https://github.com/redboltz/mqtt_cpp/blob/master/example/logging.cpp